Codex

Combine the UserPromptSubmit Hook, HTTP MCP, and project-context Skill for automatic recall and explicit Handoff.

The integration has contract and HTTP service-chain coverage. No formal minimum Codex version is declared, and a full real Codex host-process E2E is Not validated.

Maturity and installation

A complete Codex installation needs all three plugin parts:

• the UserPromptSubmit Hook for automatic recall, prompt capture, and optional flush;
• the HTTP MCP Server for explicit operations;
• the bundled project-context Skill for Scope, Handoff, and write-intent rules.

powercontext setup codex --source oceanbase/powercontext --ref master
powercontext server run
powercontext doctor codex

Setup asks Codex to add the marketplace and plugin, then verifies the installed entry. Unlike Claude Code setup, the current Codex installer does not print a no-write preview plan and does not implement transactional rollback. Treat that setup preview/rollback contract as Unsupported here, not as a shared host feature.

Minimal usage

Open a new Codex session. Inspect /hooks for UserPromptSubmit and /mcp for the PowerContext Server. Then try the three paths:

1. Ask a normal repository question. The Hook may inject recalled context and captures only that prompt as a Source.
2. Ask Codex to search or maintain Memory. The bundled Skill directs it to the MCP tools.
3. Say handoff this work when you want Codex to prepare and commit one durable Handoff in the same turn.

A plugin with only the Hook can recall, but it lacks the explicit operation surface and usage policy. MCP without the Skill exposes operations without the host-specific rules. The supported integration is Hook + MCP + Skill.

Execution flow

UserPromptSubmit
→ isolated uv/Python hook
→ derive API base from plugin .mcp.json
→ resolve shared project Scope
→ expected recall failures fail open, then capture prompt
→ optional flush through captured Source position
→ hook stdout additionalContext

The Hook is a short process. It does not retain a conversation object between turns and does not capture Codex’s final response.

Scope and Workstream binding

The Scope resolver checks, in order:

1. POWERCONTEXT_CODEX_SCOPE_ID, when set;
2. a Git-private Workstream binding;
3. normalized Git remote identity, then normalized project path.

The binding is stored under the checkout’s Git directory, so it follows the local checkout without entering a commit. Codex and Claude Code use the same binding and remote normalization. This is how they can read and update one project Memory instead of creating parallel Scopes.

Before a durable Handoff or a latest Continue with no exact Workstream, the Skill calls select_handoff_workstream when available. Multiple candidates require user selection. Codex binds the returned scope_id, resolves again, and requires an exact match before a Handoff write. The picker itself is read-only.

Injection and API-base derivation

The Hook reads the powercontext HTTP MCP URL from the installed plugin’s .mcp.json, requires a safe unambiguous /mcp URL, and derives the HTTP API base by removing that path. This keeps automatic HTTP calls and MCP on one endpoint. There is no independent Hook URL that may drift away from MCP configuration.

Prepared context is schema-checked and size-bounded before it reaches Hook stdout as additionalContext. An empty result yields no content. Unknown schema, redirect, oversized response, authentication failure, Server error, or wall-clock deadline all fail open with content-free diagnostics. Authorization is never forwarded across a redirect.

Capture and flush

Automatic capture writes only the current prompt to /v1/sources/content with a deterministic codex-user-prompt: Source ID and provenance. It does not capture the assistant final response or create a Task Outcome.

Expected recall failures are isolated so capture can still run. An unexpected recall exception can reach the outer fail-open handler and skip capture for that invocation, so do not claim unconditional independence. Disable capture with POWERCONTEXT_CODEX_CAPTURE_PROMPTS=false. Enable optional flush with POWERCONTEXT_CODEX_FLUSH_ON_CAPTURE=true; POWERCONTEXT_CODEX_FLUSH_MAX_CALLS bounds attempts. The Hook clears the wait only after current_cursor >= position. If the cursor never catches up, the turn continues without claiming that Memory was generated.

A captured prompt is Source evidence. Prompts longer than 200,000 characters are skipped. Codex capture does not apply DSH’s narrow secret-marker filter, so disable it when prompts must not be persisted. Scheduler/flush processing may produce a Candidate, and Review may commit Memory or choose a no-op.

MCP, Skill, Handoff, and permission

MCP exposes explicit Memory maintenance, Work Contract, Handoff, acknowledgement, Outcome, and Review operations. POWERCONTEXT_CODEX_AUTHORIZATION may supply the complete Authorization value through .mcp.json env_http_headers; it is optional for a public local Server. Use HTTPS for remote endpoints.

The Skill gives handoff this work one-turn semantics. Codex inspects the current conversation and repository, calls handoff_current_work once with a unique source_id, passes the returned handoff unchanged to commit_handoff in the same turn, and reports success only after an exact Revision returns. It does not ask for a second confirmation when the imperative already authorizes the Handoff.

That rule has a sharp preview boundary. A Handoff question, design discussion, draft request, or preview and make no writes request authorizes no write. Codex renders the proposed fields in chat and must not call handoff_current_work, because preparation itself records a boundary Source. A Prepared Handoff can remain uncommitted, but it is not a zero-write preview.

Explicit durable mutations must report failure. MCP tool annotations describe read/write, destructive, and idempotent intent, but visibility is not an authorization boundary. Host permission UI and enforcement remain Host-gated and Not validated; do not borrow a stronger no-UI guarantee from another adapter.

Unsupported vs Not validated

State	Capability	Practical consequence
Unsupported	automatic assistant final-response capture	Persist a final result explicitly through MCP.
Unsupported	automatic Task Outcome	Call record_task_outcome at a real boundary.
Unsupported	zero-write preview through handoff_current_work	Render preview fields in chat and do not call the tool.
Unsupported	Codex setup no-write plan and transactional rollback	Review the command before running it; cleanup may be manual after partial failure.
Not validated	formal minimum Codex version	Do not turn a tested development version into a support floor.
Not validated	full real Codex host-process E2E	Contract and HTTP service-chain tests do not prove the complete host lifecycle.
Not validated	real-host enforcement of one-turn Handoff and preview no-write policy	These are bundled Skill rules backed by real MCP primitives, not a completed Codex behavioral acceptance test.
Not validated	exact Codex permission UI and enforcement	MCP annotations express intent; the host owns authorization behavior.

Managed Skill export supports Codex, but an exported managed Skill and the bundled plugin Skill are different objects. Installing one does not substitute for the other.

Negative experiments

• Stop the Server and submit a normal prompt. Codex should continue; an explicit write should report failure.
• Trigger an expected recall failure and confirm capture still runs. Inject an unexpected recall exception separately and confirm the whole Hook still fails open; capture may be skipped for that invocation.
• Change the MCP URL to an unsafe, ambiguous, or non-/mcp value. Settings should reject it rather than guessing an API base.
• Redirect a Hook request. Authorization must not reach the target.
• Return an unknown schema or oversized response. Nothing should be injected.
• Let flush exhaust its attempt/deadline budget while the cursor stays behind. The turn should continue without a false Memory claim.
• Let Handoff preparation succeed and commit fail. Report the boundary Source and absence of a durable milestone; do not create a second boundary merely to retry.
• Request preview and make no writes. Confirm no PowerContext call writes a Source or Handoff.
• Revise or retire Memory with an old Citation. Expect conflict, refresh the head, and do not overwrite blindly.

Configuration defaults

The hook derives its API base from plugin .mcp.json, which defaults to http://127.0.0.1:8000/mcp. Other behavior comes from POWERCONTEXT_CODEX_ environment variables:

Key	Default	Meaning
MCP url	http://127.0.0.1:8000/mcp	Stored in plugin .mcp.json; do not add credentials
POWERCONTEXT_CODEX_SCOPE_ID	unset	Explicit Scope; otherwise Workstream / Git / path
POWERCONTEXT_CODEX_AUTHORIZATION	unset	Complete Bearer header; the hook and MCP both read it
POWERCONTEXT_CODEX_CAPTURE_PROMPTS	true	Capture the current user prompt as Source
POWERCONTEXT_CODEX_FLUSH_ON_CAPTURE	false	Test-only: wait for flush after capture
POWERCONTEXT_CODEX_REQUEST_TIMEOUT_SECONDS	1	Per-request HTTP timeout
POWERCONTEXT_CODEX_HTTP_BUDGET_SECONDS	4	Total prepare/capture budget for one turn
POWERCONTEXT_CODEX_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 Codex hook timeout in seconds

Plugin .mcp.json needs at least these fields. Put the environment variable name in the file, not the token:

{
  "mcpServers": {
    "powercontext": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "required": false,
      "env_http_headers": {
        "Authorization": "POWERCONTEXT_CODEX_AUTHORIZATION"
      }
    }
  }
}

In a new session, check:

1. /hooks lists the PowerContext UserPromptSubmit hook. Trust it only when prompted.
2. /mcp shows a Server named powercontext. It should be connected when the Server is running.
3. The /mcp tool list includes remember_memory and does not include prepare_context.

POWERCONTEXT_CODEX_SERVER_URL is ignored. server_url comes only from plugin .mcp.json. Do not put the token in .mcp.json, the Server URL, or a static MCP header. Disable capture when the current work must not become Source evidence:

export POWERCONTEXT_CODEX_CAPTURE_PROMPTS=false
codex

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 automatic capture alone.
2. Open a new Codex session, confirm /mcp still sees the Server, and ask the same question.
3. The recall must include a Citation and appear only in UserPromptSubmit additionalContext.
4. Stop the Server and ask an ordinary coding question. The hook may fail open. Coding should continue.
5. Call MCP remember_memory again. The failure must stay visible. Do not pretend the write succeeded.

Completion checklist

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

• powercontext doctor codex finds the installed, enabled plugin.
• Separate powercontext doctor checks Server liveness/readiness.
• /hooks shows UserPromptSubmit.
• /mcp shows the PowerContext Server.
• The bundled project-context Skill is present alongside Hook and MCP.
• The Hook derives the API base from the same .mcp.json URL used by MCP.
• Codex and Claude Code resolve one repository/Workstream Scope.
• Automatic Source contains the user prompt only, never the assistant final response.
• Prompts that must remain private have capture disabled.
• Optional flush is bounded and proves current_cursor >= position before success.
• preview and make no writes produces no write.
• An imperative Handoff completes in one turn and returns an exact committed Revision.
• Explicit write failure remains visible while automatic recall/capture failures remain fail-open.
• Unsupported, Not validated, and Host-gated claims above remain separate, including real-host Handoff, preview, and permission validation.

Continue with Claude Code.