Claude Code

Install the UserPromptSubmit + MCP + Skill plugin, then work within the v1 capture and permission boundaries.

The v1 integration is documented here. Claude Code 2.1.133 is tested compatibility evidence, not a declared minimum version. Explicit denial of a durable mutation when no permission UI is available is Not validated.

Maturity and installation

The integration has contract tests and public/authenticated service-chain tests. Its automatic path is deliberately narrow: only UserPromptSubmit runs. Setup installs a user-scope marketplace plugin containing the Hook, HTTP MCP configuration, and bundled project-context Skill.

powercontext setup claude-code \
  --source oceanbase/powercontext \
  --ref master \
  --server-url http://127.0.0.1:8000

powercontext server run
powercontext doctor claude-code

Setup prints its mutation plan before changing anything. It snapshots the existing Claude Code settings, preserves pre-existing marketplace and plugin objects, and restores the snapshot if installation or verification fails.

Minimal usage

Start a new Claude Code session. Check /hooks for UserPromptSubmit and /mcp for the connected PowerContext Server. Then use the two paths separately:

1. Ask an ordinary coding question. The Hook may recall context and captures only your prompt as a Source.
2. Ask the agent to search or maintain Memory through MCP when you need an exact operation.
3. Say handoff this work only when you want a durable Handoff prepared and committed in that turn.

The bundled Skill supplies these usage rules. The Hook does not turn every prompt into Memory, and MCP writes are never a substitute for explicit user intent.

Execution flow

UserPromptSubmit
→ prompt (compatibility fallback: user_prompt)
→ resolve shared project Scope
→ prepare and capture independently
→ optional flush
→ additionalContext

There is no second automatic event in v1. In particular, the plugin does not inspect a transcript when the turn ends.

Scope

Before its first Memory operation, the Skill runs the project Scope resolver. Resolution uses this order:

1. POWERCONTEXT_CLAUDE_SCOPE_ID, when set;
2. the Git-private Workstream binding shared with Codex;
3. normalized Git remote identity, then normalized project path.

A Workstream binding lives below the checkout’s Git directory and is not committed. When several Workstreams remain consequential, the agent must ask you to select one instead of guessing. After selection, it binds the returned scope_id, resolves again, and requires an exact match before writing a Handoff.

Injection

The Hook validates the prepared-context schema and returns temporary context through hookSpecificOutput.additionalContext. That context affects the current turn; it is not transcript capture and does not become durable merely because Claude saw it.

Recall fails open. An unavailable Server, invalid response, unknown schema, oversized body, redirect, or expired wall-clock budget produces no injection and does not block the host task. Diagnostics omit the prompt, Scope, prepared content, and authorization value.

Capture and flush

Automatic capture writes the current user prompt to /v1/sources/content with a deterministic claude-code-user-prompt: Source ID. It does not capture Claude’s final response and does not record a Task Outcome.

Recall and capture are independent. A recall failure does not prevent capture; a capture failure does not erase valid additionalContext. Disable capture with POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS=false. Optional POWERCONTEXT_CLAUDE_FLUSH_ON_CAPTURE=true retries /v1/memory/flush until current_cursor >= position, bounded by POWERCONTEXT_CLAUDE_FLUSH_MAX_CALLS and the shared HTTP deadline.

Capture is still only Source evidence. The Source window Trigger and candidate pipeline decide whether it eventually produces or updates Memory.

MCP, Skill, and permission

.mcp.json connects the HTTP MCP Server. Its headersHelper reads the complete POWERCONTEXT_CLAUDE_AUTHORIZATION value from the environment and emits an Authorization header only when set. The token stays out of plugin configuration, prompts, and diagnostics. Use HTTPS for a remote endpoint.

MCP exposes exact Memory maintenance, Work Contract, Prepared/committed Handoff, acknowledgement, Outcome, and Review operations. The Skill treats a direct handoff this work imperative as authorization for one durable Handoff: inspect live state, call handoff_current_work once, pass the returned handoff unchanged to commit_handoff in the same turn, then report success only after an exact Revision returns.

A question, design discussion, or preview request does not authorize a write. For a preview, render the proposed fields in chat and make no PowerContext write. Do not call handoff_current_work for a no-write preview: it records a boundary Source even when you skip commit_handoff.

Claude Code’s host-side behavior when a durable MCP mutation needs approval but no permission UI exists is Not validated. Do not claim Pi’s stable confirmation_required behavior here.

Unsupported vs Not validated

State	Capability	Practical consequence
Unsupported	v1 Stop Hook	No automatic work runs at session stop.
Unsupported	transcript or assistant final-response capture	Persist a final result with an explicit MCP operation.
Unsupported	automatic Task Outcome	Call record_task_outcome at a real completion or interruption boundary.
Not validated	formal minimum Claude Code version	2.1.133 is compatibility evidence, not a lower bound.
Not validated	no-UI denial of durable mutation	Keep the uncertainty visible; do not promise a host denial contract.

Negative experiments

Run these before treating the integration as complete:

• Stop the Server, submit a normal prompt, and confirm Claude Code continues.
• Make recall fail while capture succeeds; then reverse the failures and retain valid additionalContext.
• Return an unknown PreparedContext schema and confirm nothing is injected.
• Redirect the Hook request and confirm Authorization is not forwarded.
• Exceed the response-size or deadline budget and confirm the turn remains bounded.
• Enable flush, keep current_cursor behind the Source position, and confirm retries stop without claiming Memory exists.
• Let Handoff preparation succeed and commit fail; report the boundary Source and the missing durable milestone.
• Request a preview and confirm no PowerContext write occurs.

Configuration defaults

Non-secret options can be set during setup or overridden for one launch:

Key	Default	Meaning
--server-url / POWERCONTEXT_CLAUDE_SERVER_URL	http://127.0.0.1:8000	Server used by the hook; may also come from pluginConfigs or CLAUDE_PLUGIN_OPTION_SERVER_URL
POWERCONTEXT_CLAUDE_SCOPE_ID	unset	Explicit Scope; otherwise the same derivation as Codex
POWERCONTEXT_CLAUDE_AUTHORIZATION	unset	Complete Bearer header; the hook and MCP headersHelper both read it
POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS	true	Also overridable by CLAUDE_PLUGIN_OPTION_CAPTURE_PROMPTS
POWERCONTEXT_CLAUDE_FLUSH_ON_CAPTURE	false	Test-only flush
POWERCONTEXT_CLAUDE_REQUEST_TIMEOUT_SECONDS	1	Per-request HTTP timeout
POWERCONTEXT_CLAUDE_HTTP_BUDGET_SECONDS	4	Total prepare/capture budget for one turn
POWERCONTEXT_CLAUDE_FLUSH_MAX_CALLS	4	Maximum flush calls; allowed range 1–16
Recall budget	8000	max_bytes the hook sends to prepare_context; no matching env
Hook timeout	10	Outer Claude Code hook timeout in seconds

POWERCONTEXT_CLAUDE_* takes precedence over CLAUDE_PLUGIN_OPTION_* and plugin options. Do not put the token in the Server URL, plugin options, .mcp.json, or logs. headersHelper reads the complete Authorization value from the environment only. Use HTTPS for a remote endpoint.

Setup writes a .mcp.json with these fields:

{
  "powercontext": {
    "type": "http",
    "url": "http://127.0.0.1:8000/mcp"
  }
}

The installed file also has a headersHelper that builds the header from POWERCONTEXT_CLAUDE_AUTHORIZATION. The URL may come from user_config.server_url. When you inspect the file, check three things: type, a /mcp URL, and no token in the file.

In a new session, check:

1. /hooks shows UserPromptSubmit.
2. /mcp shows the powercontext Server connected.
3. The tool list includes remember_memory and does not include prepare_context.

export POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS=false
claude

Finish the shared check on this host

What should happen after the OpenAPI contract changes?

1. Store the answer in a stable Scope with MCP remember_memory. Do not rely on a prompt Source alone.
2. Open a new session, confirm /hooks and /mcp, and ask the same question.
3. The recall must include a Citation and appear only in additionalContext. v1 does not capture the assistant final response.
4. Stop the Server and ask an ordinary coding question. Claude Code should continue.
5. Make another explicit MCP write. The failure must stay visible.

Completion checklist

Treat the integration as complete only when these results are observable:

• powercontext doctor claude-code reports plugin installation/enabled state.
• Separate powercontext doctor checks Server liveness/readiness.
• /hooks shows only the v1 UserPromptSubmit automatic path.
• /mcp shows the PowerContext Server connected without exposing credentials.
• Ordinary prompts receive valid additionalContext when recall succeeds.
• Prompt Source exists.
• Assistant final response and automatic Task Outcome do not.
• Claude Code and Codex resolve the same repository or Workstream Scope.
• Preview produces no write.
• An imperative Handoff returns an exact committed Revision.
• Server and explicit MCP write failures remain distinguishable.
• Unsupported and Not validated claims above remain visible in release notes and tests.

Continue with DeepSeek Harness.