@Workspacejson/Codex

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

@workspacejson/codex-mcp

See it in 30 seconds

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.

[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" }

git diff --name-only | node hooks/pre-edit-check.mjs --paths-stdin

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

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

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