feat(integration): add Claude Code plugin by XnLemon · Pull Request #1237 · oceanbase/powercontext

XnLemon · 2026-08-14T05:00:34Z

Which issue or RFC does this PR close?

Closes #1233.

Rationale for this change

PowerContext already provides automatic project-scoped recall for Codex, but Claude Code users cannot receive relevant context before each prompt through an official integration.

This change adds a native Claude Code plugin that reuses the existing HTTP and MCP interfaces. Runtime selection, ranking, citation, rendering, Memory, and Handoff logic remain owned by the PowerContext Server.

What changes are included in this PR?

Add a repository-level Claude Code Marketplace and a self-contained PowerContext plugin.
Add a native UserPromptSubmit Hook that:
- derives the same project scope as the Codex plugin;
- calls /v1/context/prepare at most once;
- validates and injects Prepared Context through additionalContext;
- captures the current prompt as ordinary Content Source evidence;
- keeps recall and capture independent and fail-open.
Add Streamable HTTP MCP configuration for explicit Memory and Handoff workflows.
Add an environment-backed authorization header helper.
Add a bundled Skill describing explicit Memory maintenance and the inspected Handoff lifecycle.
Add powercontext setup claude-code and powercontext doctor claude-code.
Report configuration changes, storage, permissions, and rollback commands before setup mutates the Claude Code environment.
Roll back only Marketplace and plugin objects created by the failing setup invocation.
Add contract, Hook, CLI, cross-agent, authenticated transport, Memory, and Handoff tests.
Add English and Chinese setup, configuration reference, and troubleshooting documentation.

The v1 integration does not install a Stop Hook, read Claude Code transcripts, capture assistant responses, or mark ordinary prompts as task-outcome.

Are there any user-facing changes?

Yes.

Users can install and diagnose the Claude Code integration with:

powercontext setup claude-code
powercontext doctor claude-code

After setup, Claude Code automatically recalls project context and captures user prompts as ordinary Source evidence by default. Prompt capture can be disabled with --no-capture-prompts or POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS=false.

Claude Code and Codex share Memory when they resolve the same Git project scope. Authentication is configured through POWERCONTEXT_CLAUDE_AUTHORIZATION.

There are no breaking HTTP API, MCP API, or persisted-format changes.

How was this change tested?

Evidence

Test the current branch:

uv tool install --force \
  "powercontext[cli,server] @ git+https://github.com/XnLemon/powercontext.git@feat/claude-code-integration"

powercontext setup claude-code \
  --source XnLemon/powercontext \
  --ref feat/claude-code-integration

Then start the Server:

powercontext server run

In another terminal, run:

powercontext doctor
powercontext doctor claude-code
claude

In Claude Code, check /hooks and /mcp to confirm that the PowerContext Hook and MCP Server are active.

Automated validation:

python -m pytest \
  tests/claude_code_plugin \
  tests/codex_plugin \
  tests/test_system_cli.py \
  tests/e2e/test_claude_code_service_chain.py \
  tests/e2e/test_codex_service_chain.py \
  tests/e2e/test_mcp_transport.py

Result: 109 passed.

Additional validation:

prek run -a
ty check
zensical build -s
claude plugin validate --strict .
claude plugin validate --strict integrations/claude-code/plugins/powercontext

All commands passed.

Manual validation covered:

installing the CLI and plugin from the feature branch;
running setup and both doctor commands;
starting the PowerContext Server and Claude Code;
confirming the PowerContext entries in /hooks and /mcp;
explicitly saving project Memory in one Claude Code session;
automatically recalling that Memory in a new session.

A full python -m pytest --doctest-modules run reported 508 passed, 7 skipped, 2 failed. One failure is an unchanged LoCoMo fixture hash mismatch. The other was a provider-readiness timeout that passed when rerun independently. Neither failure touches this integration.

AI usage statement

OpenAI Codex 5.6 Sol xhigh was used for repository analysis, implementation support, test and documentation authoring, and validation. The resulting changes were reviewed, and the CLI integration was manually validated end to end by the author.

中文

该 PR 关闭哪个 Issue 或 RFC？

Closes #1233。

修改原因

PowerContext 已经为 Codex 提供项目级自动上下文召回，但 Claude Code 用户还无法通过官方集成，在处理每条 prompt 前获得相关上下文。

该修改增加原生 Claude Code 插件，并复用现有 HTTP 和 MCP 接口。选择、排序、引用、渲染、Memory 和 Handoff 逻辑仍由 PowerContext Server 负责。

该 PR 包含哪些修改？

增加仓库级 Claude Code Marketplace 和自包含的 PowerContext 插件。
增加原生 UserPromptSubmit Hook：
- 使用与 Codex 插件相同的项目 scope；
- 每条 prompt 最多调用一次 /v1/context/prepare；
- 校验 Prepared Context，并通过 additionalContext 注入；
- 将当前 prompt 采集为普通 Content Source 证据；
- 让召回与采集独立执行并 fail open。
增加 Streamable HTTP MCP 配置，用于显式 Memory 和 Handoff 工作流。
增加从环境变量读取认证信息的 header helper。
增加说明显式 Memory 维护和可检查 Handoff 生命周期的 Skill。
增加 powercontext setup claude-code 和 powercontext doctor claude-code。
setup 修改 Claude Code 环境前，会报告配置变更、存储位置、所需权限和回滚命令。
setup 失败时，只回滚本次调用创建的 Marketplace 和插件对象。
增加 contract、Hook、CLI、跨 Agent、认证传输、Memory 和 Handoff 测试。
增加中英文安装、配置参考和故障排查文档。

v1 不安装 Stop Hook，不读取 Claude Code transcript，不采集助手回复，也不把普通 prompt 标记为 task-outcome。

是否存在用户可见修改？

是。

用户可以通过以下命令安装和诊断 Claude Code 集成：

powercontext setup claude-code
powercontext doctor claude-code

setup 完成后，Claude Code 默认自动召回项目上下文，并把用户 prompt 采集为普通 Source 证据。可以通过 --no-capture-prompts 或 POWERCONTEXT_CLAUDE_CAPTURE_PROMPTS=false 禁用采集。

Claude Code 和 Codex 解析到同一个 Git 项目 scope 时，会共享 Memory。认证通过 POWERCONTEXT_CLAUDE_AUTHORIZATION 配置。

该修改不包含破坏性的 HTTP API、MCP API 或持久化格式变更。

如何测试该修改？

证据

使用当前分支测试：

uv tool install --force \
  "powercontext[cli,server] @ git+https://github.com/XnLemon/powercontext.git@feat/claude-code-integration"

powercontext setup claude-code \
  --source XnLemon/powercontext \
  --ref feat/claude-code-integration

然后启动并检查：

powercontext server run

另一个终端：

powercontext doctor
powercontext doctor claude-code
claude

在 Claude Code 中检查 /hooks 和 /mcp。

自动化验证：

python -m pytest \
  tests/claude_code_plugin \
  tests/codex_plugin \
  tests/test_system_cli.py \
  tests/e2e/test_claude_code_service_chain.py \
  tests/e2e/test_codex_service_chain.py \
  tests/e2e/test_mcp_transport.py

结果：109 passed。

其他验证：

prek run -a
ty check
zensical build -s
claude plugin validate --strict .
claude plugin validate --strict integrations/claude-code/plugins/powercontext

以上命令全部通过。

手动验证覆盖：

从功能分支安装 CLI 和插件；
执行 setup 和两个 doctor 命令；
启动 PowerContext Server 和 Claude Code；
在 /hooks 与 /mcp 中确认 PowerContext；
在一个 Claude Code 会话中显式保存项目 Memory；
在新会话中自动召回该 Memory。

完整执行 python -m pytest --doctest-modules 时结果为 508 passed, 7 skipped, 2 failed。一个失败来自未修改的 LoCoMo fixture 哈希不一致；另一个是 provider readiness timeout，单独重跑已通过。两者均不涉及本集成。

AI 使用声明

使用了 OpenAI Codex 进行仓库分析、辅助实现、测试与文档编写以及验证。最终修改经过人工审阅，并由作者完成 CLI 集成的端到端手动验证。

CLAassistant · 2026-08-14T05:00:44Z

All committers have signed the CLA.

XnLemon · 2026-08-14T05:08:51Z

cc @PsiACE, The content is essentially aligned with the Codex implementation, and evidence of the successful use of powercontext has been added. Pls review it when you have time. -w- )b

Teingi

Requesting changes for three blocking integration issues: authenticated MCP cannot load its header helper from a normal project working directory; setup can silently ignore the requested marketplace source/ref; and failure rollback can remove a pre-existing disabled plugin. I reproduced the header-helper failure and the disabled-plugin reinstall behavior with a temporary local Claude Code plugin installation. The PR's declared 109-test selection passes, but it does not cover these runtime and state-transition paths. Concrete fixes and regression-test shapes are included inline.

Teingi · 2026-08-14T15:36:25Z

Please resolve the merge conflicts with the latest master branch. Thanks!

XnLemon · 2026-08-14T15:41:25Z

Please resolve the merge conflicts with the latest master branch. Thanks!

sure, i will fix them in midnight -w-)b

XnLemon · 2026-08-14T22:10:08Z

Conflict files resolved, review fixed~ I will continue to follow up ( -w- ) b

feat(integration): add Claude Code plugin

7e43802

XnLemon marked this pull request as ready for review August 14, 2026 05:05

style: apply pinned Ruff formatting

4811579

Teingi requested changes Aug 14, 2026

View reviewed changes

Comment thread integrations/claude-code/plugins/powercontext/.mcp.json Outdated

Comment thread src/powercontext/cli/system.py Outdated

Comment thread src/powercontext/cli/system.py

XnLemon added 2 commits August 15, 2026 02:55

Merge oceanbase/master into feat/claude-code-integration

38cf875

fix(claude-code): harden plugin setup

f7aa2c5

XnLemon mentioned this pull request Aug 14, 2026

ci: validate Claude Code integration XnLemon/powercontext#1

Closed

XnLemon requested a review from Teingi August 14, 2026 22:10

Navigation Menu

Uh oh!

feat(integration): add Claude Code plugin - #1237

feat(integration): add Claude Code plugin#1237
XnLemon wants to merge 4 commits into
oceanbase:masterfrom
XnLemon:feat/claude-code-integration

XnLemon commented Aug 14, 2026

Uh oh!

CLAassistant commented Aug 14, 2026 •

edited

Loading

Uh oh!

XnLemon commented Aug 14, 2026

Uh oh!

Teingi left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Teingi commented Aug 14, 2026

Uh oh!

XnLemon commented Aug 14, 2026

Uh oh!

XnLemon commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

XnLemon commented Aug 14, 2026

Which issue or RFC does this PR close?

Rationale for this change

What changes are included in this PR?

Are there any user-facing changes?

How was this change tested?

Evidence

AI usage statement

该 PR 关闭哪个 Issue 或 RFC？

修改原因

该 PR 包含哪些修改？

是否存在用户可见修改？

如何测试该修改？

证据

AI 使用声明

Uh oh!

CLAassistant commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

XnLemon commented Aug 14, 2026

Uh oh!

Teingi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Teingi commented Aug 14, 2026

Uh oh!

XnLemon commented Aug 14, 2026

Uh oh!

XnLemon commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

CLAassistant commented Aug 14, 2026 •

edited

Loading