workspace.json / Codex

Portable repository history that changes Codex’s plan before an evidenced risky edit lands.

@workspacejson/codex-mcp reads a local workspace.json and exposes it to OpenAI Codex as MCP tools plus a deterministic pre-edit hook — so Codex sees which files are fragile and which files co-change before it proposes an edit, not just when asked.

Status

This page documents what’s shipped and independently verifiable today: the MCP server, the hook, the installer, and the operational guarantees below. Live before/after evidence from a recorded Codex session is still being captured and will be published here once it exists — nothing on this page substitutes for that.

Three planes

Plane	Role	Authority
Evidence	portable workspace.json history	descriptive
Action	MCP context + deterministic hook	mechanical enforcement on supported edits
Challenge	read-only GPT-5.6 reviewer	advisory

The reviewer never controls the hook. A PASS verdict is not a safety certification.

Install

1. Run the managed installer from your repository root:

   npx @workspacejson/codex-mcp install --with-hook

2. Restart Codex, then run /mcp in the TUI to confirm workspacejson is connected.

3. Ask Codex to edit a file your workspace.json flags as fragile and watch the hook cite the evidence and any omitted co-change partner before the edit lands.

This installs MCP context, the deterministic pre-edit hook, and the read-only GPT-5.6 reviewer. It’s idempotent and scoped to the current repo’s .codex/ directory — it never touches ~/.codex. Remove everything it wrote with npx @workspacejson/codex-mcp uninstall.

Operational guarantees

Six promises, each checkable against the source rather than taken on faith:

1. Missing evidence never becomes a safety approval.
2. Malformed evidence never crashes the edit loop.
3. Reviewer output never controls deterministic enforcement.
4. Installation never overwrites unmanaged configuration.
5. Uninstall removes only owned artifacts.
6. Every VERIFIED claim maps to a reproducible command.

Reproduce them yourself: clone the repository, run npm ci && npm run verify. Full citations for each guarantee, and how the system behaves under missing, malformed, or unavailable input, are documented in the repository.

Current limitations

• Enforcement currently covers Codex apply_patch.
• Other edit mechanisms may receive context without deterministic blocking.
• fragile:false means the file has no recorded fragility, not that it is verified safe.
• Missing or malformed workspace.json fails open with an explicit unavailable warning.
• Stale evidence is not treated as proof of current risk.
• This does not replace tests, review, or repository instructions.

Learn more

Repository Source, install instructions, and full documentation.

How it works Evidence tiers, hook enforcement, and the GPT-5.6 reviewer's scope.

Tool reference The four read-only MCP tools this server exposes.

workspace.json spec The open specification this implementation reads.