FAQ
General
Section titled “General”What is Optra Prism?
Section titled “What is Optra Prism?”Optra Prism is an intelligence layer for AI-assisted coding. It plugs into Claude Code and gives you visibility into how you use AI — then helps you improve through PRISM scoring, real-time advisor coaching, and usage analytics.
What data does it collect?
Section titled “What data does it collect?”- OTEL telemetry — logs, metrics, traces (token counts, timing, model usage, tool calls)
- Prompt text — your actual prompts, used for PRISM scoring and coaching
Prompt text is stored encrypted at rest and is scoped to your organization. See the privacy policy for details.
Does it slow down my coding?
Section titled “Does it slow down my coding?”The plugin hook is lightweight:
- Status line + context nudges: sub-millisecond.
- Prompt capture to the ingest service: async, fire-and-forget.
- OTEL export: async, non-blocking.
The prism-advisor skill runs inside your Claude Code session, so it can add the cost of a short extra LLM call when it has advice to give. Gateway routing, when enabled, adds a small network hop (~50–100ms); disable it if you want zero latency impact.
What does “always-active” mean for the advisor?
Section titled “What does “always-active” mean for the advisor?”The prism-advisor skill is installed as always-active but user-invocable: false. Claude Code evaluates your prompt, emits at most one > [Prism] … advisory line when it qualifies, and then handles your request normally. You can also run /prism:advisor to force a detailed review.
Plugin
Section titled “Plugin”Do I need to restart Claude Code after setup?
Section titled “Do I need to restart Claude Code after setup?”Yes. The plugin writes OTEL_* variables and the gateway ANTHROPIC_BASE_URL into ~/.claude/settings.json on session start. After initial setup or toggling gateway routing, restart Claude Code so those variables take effect.
Can Prism block my prompts?
Section titled “Can Prism block my prompts?”No. The submit hook always exits 0 and never modifies or delays your prompt. Everything the plugin emits is advisory.
How do I adjust advisor strictness?
Section titled “How do I adjust advisor strictness?”Change prismThreshold in ~/.prism/config.json (default 4). Higher values make the advisor more willing to flag prompts; it never blocks. You can also set it via CLAUDE_PLUGIN_OPTION_prismThreshold during plugin install.
How do I turn off the [Prism] status line?
Section titled “How do I turn off the [Prism] status line?”Run /prism:status and toggle it, or set showStatusLine: false in ~/.prism/config.json.
What if I don’t have an API key?
Section titled “What if I don’t have an API key?”Sign up at dashboard.prism.optra-ai.com to get a gck_* key.
How do I enable debug logging?
Section titled “How do I enable debug logging?”Set PRISM_DEBUG=1 in your shell before starting Claude Code. Debug output goes to ${CLAUDE_PLUGIN_DATA}/debug.log (or ~/.prism/logs/debug.log if no plugin data dir) and also to stderr.
What happens when the ingest service is unreachable?
Section titled “What happens when the ingest service is unreachable?”The submit hook fails open — your prompt still goes through. OTEL export retries internally. Prompt capture failures are logged to the debug log but not surfaced to you.
Scoring
Section titled “Scoring”What scorer is used?
Section titled “What scorer is used?”Per-prompt PES is produced by the Insight LLM rubric agent (authoring or debugging variant chosen by intent) via the Optra gateway. Everything above that is deterministic arithmetic: Layer 2 workers roll up sub-session metrics, Layer 3 assembles them into Skill / Speed / Efficiency.
There is no heuristic PES fallback wired in today; if the LLM call fails the scoring worker skips the row. The scoring_tier column is always llm for now.
What’s a good PRISM score?
Section titled “What’s a good PRISM score?”It depends on which of the three personal scores you mean. See PRISM Scores for the full formulas.
Skill (0–100):
- 90–100 — Elite
- 70–89 — Expert
- 50–69 — Proficient
- 30–49 — Practitioner
- 0–29 — Novice
Speed (hours/week):
- 30h+ — Heavy
- 15–30h — Steady
- 5–15h — Light
- < 5h — Low
Efficiency (tokens / active hour): lower is better — improving PES and IE drives this down automatically. There’s no universal “good” number for any of the three — track your own trend and focus on the weakest Skill input.
Do scores affect my Claude Code experience?
Section titled “Do scores affect my Claude Code experience?”No. Scores are informational. They don’t limit access, change model behavior, or affect billing.
How often are sessions scored?
Section titled “How often are sessions scored?”The scoring worker runs after each S3 write batch with a ~30-second debounce. Sub-session scores typically appear in the dashboard within 1–5 minutes after a session ends.
Which prompts short-circuit the rubric?
Section titled “Which prompts short-circuit the rubric?”Insight classifies each prompt into one of seven intents. Four of them — question, meta, continuation, system_callback — skip the rubric and aren’t scored. The other three (new_code, fix, refactor) are routed to the rubric agent. Short-circuited prompts are still logged for audit but don’t affect PES averages.
Dashboard
Section titled “Dashboard”Why don’t I see any data?
Section titled “Why don’t I see any data?”Common causes:
- Plugin not configured — run
/prism:setup gck_YOUR_KEY. - Session too recent — wait 1–5 minutes for ingest, scoring, and analytics cache.
- API key issue — verify with
/prism:status. - Gateway disabled and OTEL export blocked by a firewall — telemetry ingestion needs outbound HTTPS to
ingest.prism.optra-ai.com.
Can my team see my prompts?
Section titled “Can my team see my prompts?”Team leads see aggregate analytics (scores, usage, waste patterns) by default. Individual prompt text is only visible to admins and is subject to your organization’s data-access policy.
How do I share insights with the team?
Section titled “How do I share insights with the team?”- Connect Slack from the Integrations page — the org receives scheduled deliveries there.
- Share dashboard URLs directly — access is scoped by org membership.
Gateway routing
Section titled “Gateway routing”What does gateway routing do?
Section titled “What does gateway routing do?”When enableGateway is true, the plugin points ANTHROPIC_BASE_URL at the Optra gateway. Requests flow through the gateway, which applies guardrails, budgets, and analytics before forwarding to Anthropic. When enableGateway is false, requests go directly to Anthropic and only OTEL telemetry is captured.
Is gateway routing required?
Section titled “Is gateway routing required?”No. Scoring, analytics, and coaching work without the gateway — they rely on OTEL telemetry and prompt capture only. The gateway is required for guardrails and budget enforcement.
Is my API key exposed?
Section titled “Is my API key exposed?”No. Gateway auth uses a header (X-Gateway-Api-Key) set via ANTHROPIC_CUSTOM_HEADERS. The gateway forwards using its own upstream credentials. Your gck_* key is not shared with Anthropic.
Self-hosting
Section titled “Self-hosting”Can I self-host Optra Prism?
Section titled “Can I self-host Optra Prism?”Yes. The entire stack (dashboard, ingest, engine) can run locally or on your infrastructure. See the Architecture page and the Environment Variables page.
What infrastructure do I need?
Section titled “What infrastructure do I need?”- PostgreSQL (Supabase or self-managed)
- NATS JetStream
- S3-compatible storage
- Node.js (dashboard)
- Rust runtime (ingest, engine)
Do I need an Anthropic API key to run the engine?
Section titled “Do I need an Anthropic API key to run the engine?”No — the engine no longer calls the Anthropic API directly. All server-side LLM inference (PRISM scoring, session summaries, insights reports) is routed through the Optra AI gateway using a platform-scoped gck_* key. Set PUBLIC_GATEWAY_URL (the gateway base, e.g. http://localhost:3003) and OPTRA_GATEWAY_KEY (gck_…) on the engine; without them the engine refuses to boot. This OPTRA_GATEWAY_KEY is distinct from the plugin’s gck_* key issued for Claude Code redirection — don’t reuse one for the other.