> ## Documentation Index
> Fetch the complete documentation index at: https://powercontext.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

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

> [!NOTE]
>
> 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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://powercontext.mintlify.site/en/coding-agents/dsh.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.