ci: validate Claude Code integration

.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "powercontext",
+  "description": "PowerContext integrations for agent memory and inspectable handoff workflows.",
+  "owner": {
+    "name": "PowerContext Team",
+    "email": "open_oceanbase@oceanbase.com"
+  },
+  "plugins": [
+    {
+      "name": "powercontext",
+      "source": "./integrations/claude-code/plugins/powercontext",
+      "description": "Restore project memory and transfer current work from Claude Code",
+      "version": "0.1.0",
+      "category": "Productivity"
+    }
+  ]
+}

docs/en/docs/how-to/configure-claude-code.md

@@ -0,0 +1,190 @@
+---
+title: Configure Claude Code
+description: Install the PowerContext Claude Code plugin and configure recall, prompt capture, and authentication.
+---
+
+# Configure Claude Code
+
+## Check prerequisites
+
+Install PowerContext and Claude Code first, and make sure both commands are available in the environment that will
+run setup:
+
+```bash
+powercontext --version
+claude --version
+```
+
+Use the same PowerContext repository ref for the Python package and plugin. The Hook validates a versioned Prepared
+Context contract, so mixing an older Server with a newer plugin can disable recall without blocking Claude Code.
+
+## Install or update the plugin
+
+Run:
+
+```bash
+powercontext setup claude-code --source oceanbase/powercontext --ref master
+```
+
+Before changing Claude Code settings, setup reports the settings entry, plugin cache, persistent data location,
+required permissions, and exact rollback commands. It then registers the Marketplace, installs the plugin at user
+scope, and verifies the enabled plugin through Claude Code's JSON output.
+
+Claude Code owns the user settings entry, Marketplace registry, versioned plugin cache, and plugin data directory.
+PowerContext resolves the displayed locations from `CLAUDE_CONFIG_DIR` or Claude Code's default configuration
+directory using platform-independent path handling. Setup delegates the mutations to Claude Code and prints the
+resolved locations before the first one.
+
+For a local checkout, pass its directory:
+
+```bash
+powercontext setup claude-code --source ./powercontext
+```
+
+Start the Server and open a new Claude Code session after installation:
+
+```bash
+powercontext server run
+claude
+```
+
+Use `/hooks` to confirm the `UserPromptSubmit` Hook and `/mcp` to confirm the `powercontext` Server.
+
+Running setup again updates the plugin configuration and verifies the installed version. It does not remove existing
+PowerContext Server data.
+
+## Understand the plugin behavior
+
+For each user prompt, the Hook:
+
+1. derives the same project scope as the Codex integration;
+2. calls `POST /v1/context/prepare` at most once;
+3. strictly validates `powercontext.prepared-context.v1` and injects it unchanged through `additionalContext`;
+4. independently captures the prompt as ordinary Content Source evidence.
+
+The Source pipeline may later extract Memory when a generation model is configured. Prompt capture does not call
+`remember_memory`, and the Hook never labels an ordinary prompt as `task-outcome`.
+
+The plugin does not install a `Stop` Hook in v1. It does not read the transcript or automatically capture Claude's
+final response. Memory writes and durable Handoff milestones remain explicit MCP operations guided by the bundled
+Skill.
+
+Scope resolution uses this order:
+
+1. `POWERCONTEXT_CLAUDE_SCOPE_ID`, when explicitly set;
+2. the normalized `remote.origin.url` of the Git top-level directory;
+3. a `local:sha256:<digest>` identifier derived from the resolved project directory.
+
+Git-backed Claude Code and Codex sessions therefore share the normalized remote scope. For this repository both
+derive:
+
+```text
+git:github.com/oceanbase/powercontext
+```
+
+The local fallback is stable for one resolved directory, but it is not intended to join unrelated checkouts. Set an
+explicit scope only when that separation or sharing is deliberate.
+
+## Use explicit Memory and Handoff operations
+
+The bundled MCP Server exposes the existing PowerContext operations. Claude can search and list Memory, and can
+create, revise, or retire an entry when the user explicitly asks to persist a change.
+
+For a task transfer, the bundled Skill guides Claude through Source capture, Handoff activation, Draft inspection,
+finalization, and `continue_handoff` with the complete Prepared Handoff. Prepared Handoffs are temporary carriers.
+`commit_handoff` creates a durable milestone and is used only when the user explicitly requests one.
+
+Automatic recall does not depend on Claude deciding to call MCP. Conversely, MCP Memory writes do not replace prompt
+capture: the Hook stores each enabled prompt as ordinary Source evidence, and the Server decides whether later Source
+processing produces Memory.
+
+## Configure the Server endpoint and prompt capture
+
+Set the endpoint during setup:
+
+```bash
+powercontext setup claude-code \
+  --server-url http://127.0.0.1:9000 \
+  --no-capture-prompts
+```
+
+Claude Code stores these non-sensitive options in its user `pluginConfigs`. You can also override the Hook process for
+one launch:
+
+```bash
+export POWERCONTEXT_CLAUDE_SERVER_URL=http://127.0.0.1:9000
+export POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS=false
+claude
+```
+
+Use `POWERCONTEXT_CLAUDE_SCOPE_ID` only when the Memory scope must intentionally differ from both the Git remote and
+local project path.
+
+`POWERCONTEXT_CLAUDE_FLUSH_ON_CAPTURE=true` makes the Hook wait for Source processing and is intended for tests, not
+normal interactive use.
+
+The timeout and flush controls are listed in the
+[configuration reference](../reference/configuration.md#claude-code-plugin). They apply to the Hook process; the MCP
+client remains managed by Claude Code.
+
+## Connect an authenticated Server
+
+Start the Server with its token loaded from your secret manager:
+
+```bash
+export POWERCONTEXT_SERVER_AUTH_ENABLED=true
+export POWERCONTEXT_SERVER_AUTH_TOKEN="$POWERCONTEXT_LOCAL_TOKEN"
+powercontext server run
+```
+
+Start Claude Code from an environment containing the matching complete header:
+
+```bash
+export POWERCONTEXT_CLAUDE_AUTHORIZATION="Bearer $POWERCONTEXT_LOCAL_TOKEN"
+claude
+```
+
+The Hook and MCP `headersHelper` read this process environment value. The helper emits no `Authorization` header when
+the variable is absent. Never put the token in the Server URL, plugin options, `.mcp.json`, Source metadata, or logs.
+
+Plain HTTP is accepted only for `127.0.0.1`, `localhost`, or `::1`. Use HTTPS when Claude Code connects to a remote
+Server.
+
+## Understand failure behavior
+
+Recall and capture are independent and fail open. A failed recall does not prevent prompt capture, and a failed
+capture does not remove valid recalled context. In every case Claude Code continues processing the current prompt.
+
+| Condition | Hook behavior |
+| --- | --- |
+| Empty Prepared Context | Injects nothing and records the `empty` outcome |
+| HTTP 401 | Injects nothing and records `authentication_failed` |
+| HTTP 404 | Injects nothing and records `version_mismatch` |
+| HTTP 503 or unavailable Server | Injects nothing and records `server_unavailable` |
+| Unknown schema, malformed JSON, or oversized response | Injects nothing and records `invalid_response` |
+
+Diagnostics contain the outcome and safe numeric metadata only. They omit the prompt, scope, prepared content,
+Authorization value, and response body. The plugin rejects redirects and enforces both response-size and wall-clock
+limits.
+
+## Diagnose or roll back
+
+Check the CLI and enabled plugin without contacting the Server:
+
+```bash
+powercontext doctor claude-code
+```
+
+If setup fails after creating a new Marketplace or plugin entry, it removes only the objects created by that setup
+call. A Marketplace or plugin that existed before setup is preserved. Rerun setup after correcting the reported
+Claude CLI or repository error; the operation is safe to repeat.
+
+Remove the plugin and Marketplace:
+
+```bash
+claude plugin uninstall powercontext@powercontext --scope user
+claude plugin marketplace remove powercontext --scope user
+```
+
+Uninstalling the plugin from its last scope also removes its `${CLAUDE_PLUGIN_DATA}` directory unless Claude Code is
+run with `--keep-data`.

docs/en/docs/how-to/troubleshoot.md

@@ -1,6 +1,6 @@
 ---
 title: Troubleshoot
-description: Diagnose PowerContext installation, Server, database, and Codex plugin problems.
+description: Diagnose PowerContext installation, Server, database, Codex, Claude Code, and DeepSeek Harness plugin problems.
 ---
 
 # Troubleshoot
@@ -17,6 +17,7 @@ the top-level result and every check include `ok` and `status`. Check optional h
 
 ```bash
 powercontext doctor codex
+powercontext doctor claude-code
 powercontext doctor dsh
 ```
 
@@ -31,19 +32,20 @@ git ls-remote https://github.com/oceanbase/powercontext.git HEAD
 If this fails, configure the credential helper or SSH key used by Git, then rerun `uv tool install`. `uv` uses Git's
 credential configuration; PowerContext does not accept or store repository credentials.
 
-## `powercontext`, `codex`, or `dsh` is not found
+## `powercontext`, `codex`, `claude`, or `dsh` is not found
 
 Run:
 
 ```bash
 uv tool dir --bin
 command -v powercontext
 command -v codex
+command -v claude
 command -v dsh
 ```
 
-Add the uv tool bin directory to `PATH` if needed. `powercontext setup codex` and `powercontext setup dsh` report an
-error rather than installing a plugin when the host CLI is unavailable.
+Add the uv tool bin directory to `PATH` if needed. `powercontext setup codex`, `powercontext setup claude-code`, and
+`powercontext setup dsh` report an error rather than installing a plugin when the host CLI is unavailable.
 
 ## The plugin is missing or stale
 
@@ -58,12 +60,35 @@ Reinstall it from the same ref as the tool:
 ```bash
 powercontext setup codex --source oceanbase/powercontext --ref <ref>
 codex plugin list --json
+```
+
+Then start a new Codex session. Check `/hooks` if prompt recall and capture do not run.
+
+For Claude Code, run:
+
+```bash
+powercontext doctor claude-code
+powercontext setup claude-code --source oceanbase/powercontext --ref <ref>
+claude plugin list --json
+```
+
+Then start a new Claude Code session. Check `/hooks` and `/mcp`; the plugin inventory should contain one
+`UserPromptSubmit` Hook and one `powercontext` MCP Server.
+
+If setup fails while creating new user-scoped objects, it attempts to remove only the plugin and Marketplace entries
+created by that invocation. Existing entries are preserved. Correct the reported Claude CLI or repository error and
+rerun the same setup command.
+
+For DeepSeek Harness, run:
+
+```bash
+powercontext doctor dsh
 powercontext setup dsh --source oceanbase/powercontext --ref <ref>
 dsh --profile web --dump-config
 ```
 
-Then start a new host session. Check `/hooks` in Codex, or confirm dump-config lists `id: powercontext-dsh` for DeepSeek
-Harness. The DSH plugin directory must contain `lib/index.js`.
+Then start a new DeepSeek Harness session and confirm dump-config lists `id: powercontext-dsh`. The DSH plugin
+directory must contain `lib/index.js`.
 
 ## The Server check fails
 
@@ -81,7 +106,7 @@ powercontext doctor --server-url http://127.0.0.1:9000
 powercontext --server-url http://127.0.0.1:9000 ready
 ```
 
-The bundled Codex plugin uses port 8000 by default. A liveness failure means the process cannot answer health
+The bundled Codex and Claude Code plugins use port 8000 by default. A liveness failure means the process cannot answer health
 requests, so readiness is not checked. `not_ready` with HTTP 503 means the Runtime or database cannot accept work.
 `degraded` with HTTP 200 means a configured inference capability failed while database-backed operations remain
 available. Human and JSON output retain the Server's individual check statuses.
@@ -125,10 +150,10 @@ powercontext capabilities
 
 `Memory extraction: disabled` means the Server has no generation model.
 
-## Codex continues when the Server is down
+## The coding agent continues when the Server is down
 
-This is expected. The prompt hook fails open so a Memory outage cannot block ordinary Codex work. Restart the Server
-to restore recall and capture; the existing database is reopened automatically.
+This is expected. Both prompt hooks fail open so a Memory outage cannot block ordinary Codex or Claude Code work.
+Restart the Server to restore recall and capture; the existing database is reopened automatically.
 
 ## Codex does not inject recalled context
 
@@ -140,3 +165,40 @@ events intentionally omit the query and prepared content.
 
 Run `powercontext capabilities` and confirm that `powercontext.prepared-context.v1` appears under Context
 versions.
+
+## Claude Code does not inject recalled context
+
+First separate installation from Server health:
+
+```bash
+powercontext doctor claude-code
+powercontext doctor
+```
+
+The first command checks the Claude CLI and enabled plugin without contacting the Server. The second checks Server
+liveness and readiness. Then inspect the Hook's single-line stderr event. Claude Code uses the same Prepared Context
+contract as Codex, with component `powercontext.claude_code.recall`:
+
+| Outcome | Action |
+| --- | --- |
+| `empty` | No relevant Memory was prepared; no action is required |
+| `authentication_failed` | Export the complete `POWERCONTEXT_CLAUDE_AUTHORIZATION` header before starting Claude Code |
+| `version_mismatch` | Install the package and plugin from the same ref, then restart both processes |
+| `server_unavailable` | Start the Server or correct `POWERCONTEXT_CLAUDE_SERVER_URL` |
+| `invalid_response` | Check for a proxy, redirect, incompatible schema, malformed JSON, or an oversized response |
+
+The diagnostics never log the token, query, scope, prepared content, or response body. Prompt capture is independent
+of recall; a capture failure cannot suppress valid context, and a recall failure cannot suppress capture.
+
+## Claude Code MCP authentication fails
+
+The Hook and MCP `headersHelper` read `POWERCONTEXT_CLAUDE_AUTHORIZATION` from the environment that starts Claude
+Code. Stop the current process, export the complete header, and start it again:
+
+```bash
+export POWERCONTEXT_CLAUDE_AUTHORIZATION="Bearer $POWERCONTEXT_LOCAL_TOKEN"
+claude
+```
+
+Do not add the token to `.mcp.json`, the Server URL, or plugin options. Use `/mcp` after restart to confirm that the
+`powercontext` Server is connected.

docs/en/docs/index.md

@@ -6,7 +6,7 @@ description: Install PowerContext, connect Codex, and choose the right integrati
 # PowerContext documentation
 
 PowerContext stores project-scoped context for agents. It runs as a local or remote Server and exposes the same
-durable Memory through Codex, DeepSeek Harness, Python, HTTP, and MCP.
+durable Memory through Codex, Claude Code, DeepSeek Harness, Python, HTTP, and MCP.
 
 If you are installing PowerContext for yourself, start with the [Codex quickstart](tutorials/codex-quickstart.md). It
 takes you from a Git install to a second Codex session that can restore the first session's work.
@@ -15,10 +15,11 @@ takes you from a Git install to a second Codex session that can restore the firs
 
 - [Install and run](how-to/install-and-run.md): install from Git, start the Server, and update it.
 - [Configure Codex](how-to/configure-codex.md): install the plugin and control project scope and prompt capture.
+- [Configure Claude Code](how-to/configure-claude-code.md): install the plugin and share project Memory with Codex.
 - [Configure DeepSeek Harness](how-to/configure-dsh.md): install the DSH plugin and control project scope and prompt capture.
 - [Troubleshoot](how-to/troubleshoot.md): diagnose credentials, plugin, Server, database, and hook failures.
 
 ## Look up details
 
-- [Interfaces](reference/interfaces.md): Codex, DeepSeek Harness, CLI, Client SDK, Core SDK, HTTP, and MCP.
+- [Interfaces](reference/interfaces.md): Codex, Claude Code, DeepSeek Harness, CLI, Client SDK, Core SDK, HTTP, and MCP.
 - [Configuration](reference/configuration.md): defaults and environment variables.