feat(integration): add a PowerContext plugin for Claude Code

[XnLemon]

Part of #1213.
cc @PsiACE, If you think the proposal is feasible and assign it to me, I will submit a PR.

Goal

Add an official Claude Code integration that gives each prompt automatic, project-scoped recall from PowerContext while reusing the existing HTTP and MCP interfaces.

This integration should provide behavior equivalent to the Codex plugin without moving Runtime or Memory logic into the adapter.

User experience

After installing the plugin and starting a PowerContext Server, a Claude Code session should automatically recall relevant project context before processing each user prompt.

powercontext setup claude-code --source oceanbase/powercontext --ref master
powercontext server run

Claude Code should also receive the existing PowerContext MCP tools for explicit Memory and Handoff operations.

Proposed design

Automatic recall and prompt capture

Use the Claude Code UserPromptSubmit hook:

UserPromptSubmit
  -> derive the project scope
  -> POST /v1/context/prepare
  -> validate powercontext.prepared-context.v1
  -> return the rendered context through additionalContext
  -> independently POST /v1/sources/content to capture the prompt

The hook should:

• call POST /v1/context/prepare at most once per prompt;
• inject the validated Prepared Context unchanged;
• leave selection, ranking, citation, rendering, and output budgeting to the Server;
• derive the same scope IDs as the Codex plugin;
• capture the prompt as ordinary Source evidence, not as a completed task outcome;
• treat recall and capture as independent fail-open operations.

For example, both Codex and Claude Code should derive:

git:github.com/oceanbase/powercontext

Using the same scope allows memories created through either agent to be recalled by the other.

Explicit operations through MCP

Configure Claude Code to use the existing Streamable HTTP MCP endpoint.

MCP remains responsible for explicit operations such as:

• searching Memory;
• creating or revising Memory;
• retiring obsolete Memory;
• reading and recording Handoffs.

MCP does not replace automatic recall because an agent cannot reliably decide to search for context it does not yet know exists.

Completion capture

The first version should not use the Claude Code Stop hook to capture assistant output automatically.

A Stop event does not necessarily represent completion of the user's task. Reading the session transcript would also expand the exposure of secrets and tool output, and repeated Stop events could create duplicate evidence.

Completed work should continue to use the explicit Handoff flow. Completion-aware task outcome capture can be considered separately once its lifecycle and privacy semantics are defined.

Plugin layout

The integration can be distributed from this repository as a self-contained Claude Code plugin:

.claude-plugin/marketplace.json
integrations/claude-code/plugins/powercontext/
  .claude-plugin/plugin.json
  .mcp.json
  pyproject.toml
  uv.lock
  settings.py
  hooks/hooks.json
  hooks/user_prompt_submit.py
  hooks/prepared_context.py
  scripts/project_scope.py
  skills/project-context/SKILL.md

The Claude Code and Codex plugins may initially remain self-contained. Shared behavior should be protected by common contract tests before extracting a runtime package that could complicate marketplace installation.

Configuration

Use Claude Code-specific environment variables:

POWERCONTEXT_CLAUDE_SCOPE_ID
POWERCONTEXT_CLAUDE_AUTHORIZATION
POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS
POWERCONTEXT_CLAUDE_REQUEST_TIMEOUT_SECONDS
POWERCONTEXT_CLAUDE_HTTP_BUDGET_SECONDS

POWERCONTEXT_CLAUDE_AUTHORIZATION must contain the complete optional Bearer <token> header.

Authorization values must only come from the environment. They must not appear in the Server URL, plugin configuration, Source metadata, response diagnostics, or logs.

Failure and security behavior

The integration should preserve the Codex plugin's transport boundaries:

• reject redirects;
• accept plain HTTP only for loopback endpoints;
• enforce per-request and shared wall-clock deadlines;
• cap response body size;
• strictly validate the Prepared Context schema;
• emit content-free diagnostics;
• never block normal Claude Code work when PowerContext is unavailable.

Authentication failures, unavailable Servers, unknown schemas, malformed responses, oversized responses, and empty results must not inject context.

Installation and recovery

Add:

powercontext setup claude-code
powercontext doctor claude-code

Before changing the user's environment, setup must report:

• files and configuration entries that will be created or modified;
• required permissions;
• plugin and dependency storage locations;
• the exact rollback procedure.

A failed installation must either restore the previous state or provide deterministic recovery instructions.

Acceptance criteria

• A Claude Code prompt receives relevant context through additionalContext.
• Two Claude Code sessions can recall project Memory across sessions.
• Claude Code and Codex share Memory when operating in the same Git project.
• Each prompt causes at most one prepare_context request.
• Recall and prompt capture fail independently and do not block Claude Code.
• Prompt capture can be disabled through configuration.
• MCP supports the existing explicit Memory and Handoff workflows.
• 401, 404, 503, unknown schemas, malformed responses, and oversized responses do not inject content.
• Authorization values never appear in persisted metadata or diagnostics.
• Setup reports mutations and rollback steps before installation.
• Contract and end-to-end tests cover recall, capture, scope compatibility, and failure behavior.
• English and Chinese setup and troubleshooting documentation are included.

中文

目标

增加官方 Claude Code 集成，在每次处理用户 prompt 前，从 PowerContext 自动召回与当前项目相关的上下文，并复用现有 HTTP 和 MCP 接口。

该集成应提供与 Codex 插件等价的行为，不在适配器中重复实现 Runtime 或 Memory 逻辑。

用户体验

安装插件并启动 PowerContext Server 后，Claude Code 应在每次处理用户 prompt 前自动召回相关的项目上下文。

powercontext setup claude-code --source oceanbase/powercontext --ref master
powercontext server run

Claude Code 同时应获得现有 PowerContext MCP 工具，用于显式执行 Memory 和 Handoff 操作。

设计方案

自动召回与 prompt 捕获

使用 Claude Code 的 UserPromptSubmit Hook：

UserPromptSubmit
  -> 推导项目 scope
  -> POST /v1/context/prepare
  -> 校验 powercontext.prepared-context.v1
  -> 通过 additionalContext 返回渲染后的上下文
  -> 独立调用 POST /v1/sources/content 捕获 prompt

Hook 应满足：

• 每个 prompt 最多调用一次 POST /v1/context/prepare；
• 将校验后的 Prepared Context 原样注入；
• 选择、排序、引用、渲染和输出预算由 Server 负责；
• 使用与 Codex 插件相同的 scope 推导规则；
• 将 prompt 捕获为普通 Source 证据，而不是已完成的任务结果；
• recall 和 capture 作为两个独立的 fail-open 操作。

例如，Codex 和 Claude Code 都应推导出：

git:github.com/oceanbase/powercontext

使用相同 scope 后，由任一 Agent 创建的 Memory 都可以被另一个 Agent 召回。

通过 MCP 执行显式操作

配置 Claude Code 使用现有 Streamable HTTP MCP 端点。

MCP 继续负责以下显式操作：

• 搜索 Memory；
• 创建或修订 Memory；
• 废弃过时的 Memory；
• 读取和记录 Handoff。

MCP 不能替代自动召回，因为 Agent 无法稳定地决定搜索一段自己尚不知道存在的上下文。

任务完成捕获

第一版不使用 Claude Code 的 Stop Hook 自动捕获助手输出。

Stop 事件不一定代表用户任务已经完成。读取会话 transcript 还会扩大秘密信息和工具输出的暴露范围，重复触发 Stop 也可能产生重复证据。

已完成工作继续使用显式 Handoff 流程。待任务生命周期和隐私语义明确后，再单独考虑 completion-aware 的任务结果捕获。

插件目录

该集成可以作为自包含的 Claude Code 插件从当前仓库分发：

.claude-plugin/marketplace.json
integrations/claude-code/plugins/powercontext/
  .claude-plugin/plugin.json
  .mcp.json
  pyproject.toml
  uv.lock
  settings.py
  hooks/hooks.json
  hooks/user_prompt_submit.py
  hooks/prepared_context.py
  scripts/project_scope.py
  skills/project-context/SKILL.md

Claude Code 和 Codex 插件可以先保持自包含。在抽取共享运行包前，先通过公共 contract tests 保证行为一致，避免 marketplace 安装后依赖插件目录之外的源码。

配置

使用 Claude Code 专用环境变量：

POWERCONTEXT_CLAUDE_SCOPE_ID
POWERCONTEXT_CLAUDE_AUTHORIZATION
POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS
POWERCONTEXT_CLAUDE_REQUEST_TIMEOUT_SECONDS
POWERCONTEXT_CLAUDE_HTTP_BUDGET_SECONDS

POWERCONTEXT_CLAUDE_AUTHORIZATION 应包含完整的可选 Bearer <token> header。

Authorization 只能从环境变量读取，不能出现在 Server URL、插件配置、Source metadata、响应诊断或日志中。

失败与安全行为

该集成应保持 Codex 插件已有的传输边界：

• 拒绝重定向；
• 仅允许 loopback 端点使用普通 HTTP；
• 限制单次请求和共享 wall-clock 时间；
• 限制响应体大小；
• 严格校验 Prepared Context schema；
• 只输出不含内容的诊断信息；
• PowerContext 不可用时不阻塞 Claude Code 的正常工作。

认证失败、Server 不可用、未知 schema、错误响应、超大响应和空结果都不能注入上下文。

安装与恢复

增加：

powercontext setup claude-code
powercontext doctor claude-code

修改用户环境前，setup 必须报告：

• 将创建或修改的文件和配置项；
• 所需权限；
• 插件和依赖的存储位置；
• 准确的回滚步骤。

安装失败时必须恢复原有状态，或者提供确定性的恢复操作。

验收标准

• Claude Code prompt 可以通过 additionalContext 获得相关上下文。
• 两个 Claude Code 会话可以跨会话召回项目 Memory。
• Claude Code 和 Codex 在同一 Git 项目中共享 Memory。
• 每个 prompt 最多产生一次 prepare_context 请求。
• recall 和 prompt capture 独立失败，且不阻塞 Claude Code。
• 可以通过配置关闭 prompt capture。
• MCP 支持现有的显式 Memory 和 Handoff 流程。
• 401、404、503、未知 schema、错误响应和超大响应不会注入内容。
• Authorization 不会出现在持久化 metadata 或诊断信息中。
• setup 在安装前报告修改内容和回滚步骤。
• contract 和端到端测试覆盖 recall、capture、scope 兼容性和失败行为。
• 提供中英文安装与故障排查文档。

属于 #1213 的子任务。

[PsiACE]

provide behavior equivalent to the Codex plugin

Hi @XnLemon Thanks for the proposal. Assigned. The direction looks good, but please also review established Claude Code plugins and follow its native patterns where appropriate.

[XnLemon]

provide behavior equivalent to the Codex plugin

Hi @XnLemon Thanks for the proposal. Assigned. The direction looks good, but please also review established Claude Code plugins and follow its native patterns where appropriate.

Sure, thanks for ur review and feedback -w-