> ## 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.

# Codex

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

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

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

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

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

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


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