workspace.json for Codex

Historical namespace

Development of the Codex integration is migrating to workspacejson/integrations. The specification lives in workspacejson/standard.

This repository is retained because it is the current npm publication authority for @workspacejson/codex-mcp and because it preserves the submitted OpenAI Build Week state. Publication has not yet cut over to the workspacejson organization.

---

Hackathon submission snapshot

The OpenAI Build Week submission was finalized on July 21, 2026 (5:00 PM Pacific deadline).

For judging, the submitted project state is preserved at:

• Git tag: codex-mcp-v0.1.9 (also available as build-week-2026-submission)
• Commit: 7d42a61af78a383219c536cc49220f154a93a2bf

Commits made after the submission deadline are limited to repository maintenance, audit documentation, and branch/worktree reconciliation. They are not part of the work submitted for judging.

Commit	Date	Description
6eeb49f	Jul 22	docs(audit): record worktree reconciliation (#14)
7ca4c19	Jul 22	docs(audit): record HAC-170 cleanup (#15)
7882883	Jul 23	docs(audit): record duplicate branch cleanup (#16)
e188225	Jul 23	docs(audit): record cleanup wave three (#17)

Each of these commits touches only files under docs/audits/ — no source code, tests, dependencies, or packaging were modified after the deadline.

Installation and testing instructions for the submitted version remain available below. To check out the exact submitted state:

git checkout codex-mcp-v0.1.9

---

See it in 30 seconds

Task	Update the checkout route
Recorded evidence	The route and its webhook partner share a repeated co-change history, including a rounding change and its later revert—not an import.
An incomplete patch	The hook denies it, citing the specific evidence and the omitted partner
Outcome	The incomplete patch does not land; Codex receives the evidence and must account for the recorded partner before retrying.

Installation

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

That gives you MCP context plus the deterministic pre-edit hook — the enforcement shown in the 30-second demo above. It's idempotent, scoped to this repo's .codex/ directory, and never touches ~/.codex. Restart Codex, then run /mcp to confirm workspacejson is connected.

Add surfaces as you want them. Each flag is additive and asks for exactly the consent it needs — nothing is installed silently:

Command	Adds	Touches
install	MCP context (read tools) + optional GPT-5.6 reviewer	this repo's .codex/
install --with-hook	+ deterministic pre-edit hook	this repo's .codex/
install --with-extension	+ VS Code editor surface	your global VS Code (explicit consent)
install --full	the hook and the extension	both

Uninstall mirrors that consent. npx @workspacejson/codex-mcp uninstall removes only what this repo owns — the MCP block, hook, and runtime — and leaves your global VS Code extension in place. To remove the editor extension too, ask for it explicitly: npx @workspacejson/codex-mcp uninstall --with-extension.

Wire the MCP server yourself

Add this to .codex/config.toml (project) or ~/.codex/config.toml (global):

[mcp_servers.workspacejson]
command = "npx"
args = ["-y", "@workspacejson/codex-mcp", "server"]
# Optional: point at a specific file or search root.
# env = { WORKSPACE_JSON_PATH = "/abs/path/.agents/workspace.json" }

Without the hook you still get the read tools, but not deterministic enforcement.

CI / repo-native check — no editor required

# After `install --with-hook` (the installed path, works in any repo):
git diff --name-only | node .codex/workspacejson-codex-mcp/hooks/pre-edit-check.mjs --paths-stdin

# From a checkout of this repo (the source path):
git diff --name-only | node hooks/pre-edit-check.mjs --paths-stdin

Exit code 2 means a fragile change is missing a co-change partner; the reason prints with its evidence. Drop it into a GitHub Action to gate pull requests the same way the hook gates edits.

VS Code editor surface (optional)

Let the installer handle the code CLI, idempotency, and the reload prompt for you:

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

This installs the workspace-json.workspacejson-codex-decorations extension: Explorer decorations on fragile files, a current-change view, a synchronized status item, and saved review receipts. The decorations, current-change view, status item, and saved review receipts read local workspace data with no telemetry. Running a new advisory review is a separate explicit action that sends only the supplied diff to the configured provider.

The installer targets VS Code Stable only. If the code CLI isn't on your PATH it reports UNAVAILABLE with a one-line fix and leaves your MCP/hook install untouched — it never silently targets Insiders, Cursor, a remote, or a container. To aim it at a different editor's CLI deliberately, set WORKSPACEJSON_CODE_CLI (e.g. cursor) and rerun.

Building from a checkout of this repo? Produce the VSIX first, then install:

npm run build:extension
npx @workspacejson/codex-mcp install --with-extension

Prefer to install a pinned VSIX by hand (offline, or a release artifact)?

code --install-extension workspacejson-codex-decorations-<version>.vsix

Demo and fixture repos may recommend the exact extension ID through .vscode/extensions.json; that's discovery only and never installs anything on its own.

Generate workspace.json

The MCP server and hook consume .agents/workspace.json. The reference generator is agents-audit — a separate package in the same org:

npx agents-audit@0.4.3 generate .

This writes .agents/workspace.json with repository topology and hygiene. Today, generated.fileIndex is empty and manual fragility/co-change evidence is not auto-generated — those remain human-authored (ASSERTED tier at minimum, OBSERVED when backed by evidence records). The generator does not guess risk signals; guessed churn has no evidence records, remains ASSERTED, and cannot block. See fixture/ for a worked example with manual evidence.

Local proof path — two recorded partners

generate (above) writes repository topology only — no fragility or co-change evidence, so a freshly generated workspace.json has nothing to deny yet. To see the deny path itself, use this repo's fixture/, whose manual evidence is hand-authored for exactly this demo:

1. Open fixture/ in Codex. In Codex, ask it to edit src/routes/checkout.ts.
2. Watch the hook refuse the patch, citing the recorded evidence and the co-change partners the change left out.
3. Ask Codex to include both partners and retry — the edit proceeds.

No configuration beyond step 1 above. On your own repo, the same deny path activates once you've authored manual.fragileFiles / manual.coChangePatterns yourself — see docs/workspace-contract.md.

Provider-demo proof path — Billfold's one recorded partner

The judge-facing demo runs against workspace-json/billfold, a small public payments service. This is a separate proof path from this repository's local fixture/: Billfold uses the single recorded pairing shown on camera, src/routes/checkout.ts and src/webhooks/stripe.ts; the local walkthrough above uses src/auth/session.ts and src/lib/format.ts.

git clone https://github.com/workspace-json/billfold.git
cd billfold
git checkout 5e97f1dc9e6a41eb80d2d6eb80d5ef703cbe1cde  # main as of 2026-07-20; no tag covers this pairing yet
npm install
npx @workspacejson/codex-mcp install --with-hook

1. Open billfold in Codex. Ask it to change the idempotency-key format in src/routes/checkout.ts.
2. The hook denies the patch, citing the recorded revert/incident and the omitted partner, src/webhooks/stripe.ts.
3. Ask Codex to include src/webhooks/stripe.ts and retry — the patch proceeds. That clears the recorded-partner check; it is not a correctness verdict on the change (see Current limitations).

This pins to the commit above because billfold's main is mutable and the two existing tags (fixture-v1, fixture-v2) predate this pairing — clone and stay on main instead if you want the current state.

How it works

MCP supplies context. A deterministic hook enforces evidenced omissions. An optional, direct read-only GPT-5.6 API review challenges a supplied completed diff and preserves its request/response receipt locally. The reviewer never controls the hook, and a PASS verdict is not a safety certification.

git diff | npx @workspacejson/codex-mcp review --diff-stdin

Requires OPENAI_API_KEY (or OPENROUTER_API_KEY) in the environment. Without one, it reports UNAVAILABLE and deterministic enforcement is unaffected.

Full derivation rules for evidence tiers (ASSERTED/OBSERVED/VERIFIED), the hook's fail-open behavior, and the GPT-5.6 reviewer's scope live in docs/how-it-works.md.

Operational guarantees

• Missing evidence never becomes a safety approval.
• Malformed evidence never crashes the edit loop.
• Reviewer output never controls deterministic enforcement.
• Installation never overwrites unmanaged configuration.
• Uninstall removes only owned artifacts.
• The editor extension installs only with explicit --with-extension consent.
• Every VERIFIED claim maps to a reproducible command.

Each is checkable, not asserted: run npm run verify from a clean clone to reproduce the gate this repository's own CI runs, or read the source citations in docs/operational-guarantees.md. See docs/failure-modes.md for the behavior behind each guarantee under missing, malformed, or unavailable input.

Trust boundary

Local, no network: the MCP server, the deterministic hook, and the VS Code extension run over stdio and the local filesystem only. None of them upload repository contents or make network calls.

Network, by explicit action only: npx package installation contacts npm. The optional review command sends only the diff you explicitly supply to a configured API provider: OpenAI (OPENAI_API_KEY) or OpenRouter (OPENROUTER_API_KEY). When both keys exist, set WORKSPACEJSON_REVIEWER_PROVIDER to openai or openrouter; an explicit WORKSPACEJSON_REVIEWER_BASE_URL also selects OpenRouter. It uses store: false with OpenAI and preserves a local request/response receipt that identifies the provider and model. Do not supply diffs containing secrets.

Current limitations

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

Learn more

• How it works — evidence tiers, hook enforcement, GPT-5.6 reviewer
• Operational guarantees — the seven promises above, with source citations
• Failure modes — behavior under missing, malformed, or unavailable input
• Tools — full MCP tool reference (workspace_get_file_context, workspace_get_cochange_partners, workspace_list_fragile_files, workspace_assess_change)
• The workspace.json contract — fields consumed and normalization
• Verification — what's been verified and how
• Build Week disclosure — what was authored in-window
• Development — build, test, and smoke-suite commands
• Clean-install audit · Fixture verification · billfold — the public repo behind the demo video

License

Apache-2.0