See it in 30 seconds

| | | | --- | --- | | Task | Update the checkout route | | Without workspace.json | Codex proposes one file | | With workspace.json | The hook identifies two evidenced partners | | Enforcement | The incomplete patch is denied | | Outcome | Codex revises the changeset before the edit lands |

Installation

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

Installs:

• MCP context
• deterministic pre-edit hook

Includes:

• optional, read-only GPT-5.6 API reviewer

Idempotent, scoped to this repo's .codex/ directory, never touches ~/.codex. Restart Codex, then run /mcp to confirm workspacejson is connected. Remove everything it wrote with npx @workspacejson/codex-mcp uninstall.

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

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.

Editor decorations — VS Code / Cursor (optional)

Install the packaged extension from the release .vsix:

# VS Code
code --install-extension workspacejson-codex-<version>.vsix

# Cursor
cursor --install-extension workspacejson-codex-<version>.vsix

Fragile files are flagged in the Explorer with their tier and evidence on hover. The extension reads the same local .agents/workspace.json; it makes no network calls.

Verify in two minutes

From a repo that has a committed .agents/workspace.json:

1. In Codex, ask it to edit a file the workspace flags as fragile.
2. Watch the hook refuse the patch, citing the recorded evidence and the co-change partner the change left out.
3. Ask Codex to include the partner and retry — the edit proceeds.

No configuration beyond step 1 above. The example/ fixture in this repo reproduces the exact denial shown in the demo.

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.

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

The MCP and deterministic hook run locally over stdio and do not upload repository contents. Initial package installation may contact 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.
• 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 six 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

License

Apache-2.0