@Workspacejson/Codex

БесплатноНе проверен

Gives OpenAI Codex behavioral history from workspace.json, exposing file fragility and co-change partners as tools to enforce safer edits and block incomplete p

автор: workspace-json

GitHub Embed

Описание

Gives OpenAI Codex behavioral history from workspace.json, exposing file fragility and co-change partners as tools to enforce safer edits and block incomplete patches.

README

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

@workspacejson/codex-mcp

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.

MCP-only setup, CI check, editor decorations, and manual verification

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:

In Codex, ask it to edit a file the workspace flags as fragile.
Watch the hook refuse the patch, citing the recorded evidence and the co-change partner the change left out.
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

from github.com/workspace-json/codex-mcp

Установка @Workspacejson/Codex

У этого сервера нет опубликованного пакета — он собирается из исходников. Открой репозиторий и следуй инструкции в README.

▸ github.com/workspace-json/codex-mcp

FAQ