Plugin Overview
The Prism plugin runs inside Claude Code with four automatic hooks and eight slash commands. The hooks run silently in the background; the commands are on-demand.
Automatic hooks
Section titled “Automatic hooks”These run without any commands — they’re always active once the plugin is installed:
| Hook | Trigger | What it does |
|---|---|---|
SessionStart | Session begins | Validates your API key, syncs OTEL settings, optionally sets the gateway URL |
UserPromptSubmit | Before each prompt | Prints the prior turn’s status line, shows context-management nudges (/compact, /clear), captures the prompt to Ingest |
Stop | After each response | Updates session counters (turns, tokens, response times), builds the next status line, queues periodic alerts |
PostCompact | After /compact | Resets turn count, token baselines, and context tracking |
The hooks never block your prompt — if anything fails, the prompt still goes through.
What the submit hook actually emits
Section titled “What the submit hook actually emits”The UserPromptSubmit hook writes to stderr (shown inline above your prompt). Two things land there:
- Status line from the last turn:
[Prism]summary of turns, tokens, and cost so far. - Context nudges, only when they apply:
- Turn count > 80 or context grew > 10× → suggests
/clear - Turn count > 20 and context grew > 3× → suggests
/compact - Every 15 turns → a dim periodic reminder
- Turn count > 80 or context grew > 10× → suggests
The hook skips status / nudge processing entirely for slash commands (/prism:...), shell passthrough (!...), and short navigational inputs (yes, ok, lgtm, etc.) — but it still captures the prompt for analytics when a key is configured.
What the submit hook does not do
Section titled “What the submit hook does not do”It does not score your prompt for PES, and it does not emit prompt-quality coaching lines. Per-prompt scoring runs server-side in the Prism Engine after the prompt is captured. In-terminal prompt coaching is on-demand via /prism:advisor.
Slash commands
Section titled “Slash commands”Run these explicitly during a session:
| Command | Purpose |
|---|---|
/prism:setup [key] | Configure API key, resolve service URLs, enable telemetry |
/prism:status | Connection health, install scope, gateway toggle, status-line toggle |
/prism:cost | Current session cost and token usage |
/prism:score | Skill profile with coaching for the weakest input |
/prism:report | 30-day comprehensive review |
/prism:advisor [prompt] | Detailed prompt optimization review with a rewrite |
/prism:help | List all commands |
/prism:uninstall | Remove plugin settings and OTEL config |
See Commands for the detailed reference.
/prism:advisor
Section titled “/prism:advisor”Run /prism:advisor "your prompt" when you want a detailed review of a specific prompt — scores for the four PES dimensions, a concrete rewrite using real paths from the project, and a short explanation of why the rewrite is better. Works in any language.
It uses your recent session activity (turn count, token growth, response times, model mix) to tailor the advice. That session context is written by the submit hook to ~/.prism/advisor-context.json; if the file is missing, the command still works from conversation context alone.
For automatic coaching between sessions, see the server-side Advisor & Summaries on the dashboard — that’s where per-session coaching cards live.
Config
Section titled “Config”The plugin stores config at ~/.prism/config.json. The fields are:
| Field | Purpose |
|---|---|
apiKey | Your gck_* key (file is owner-only) |
enableGateway | Route API calls through the Optra gateway. Toggle with /prism:status. |
prismThreshold | Minimum prompt-efficiency score; passed to the plugin runtime for internal use |
showStatusLine | Whether the submit hook prints the status line above prompts. Default: on |
Service URLs (ingest, gateway, dashboard) are resolved automatically from the API key — there are no URL fields to set. Only PRISM_INGEST_URL can be overridden, and only for local development.