# Project export: workspace.json for Codex

This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small.

## Project metadata

- Hackathon: OpenAI Build Week
- Tagline: Portable codebase intelligence for Codex, combining workspace.json evidence, focused MCP context, and deterministic pre-edit risk checks.
- Devpost: https://devpost.com/software/workspace-json-for-codex
- GitHub: http://github.com/workspace-json/codex-mcp
- Demo: https://workspacejson.dev/implementations/codex
- Video: https://www.youtube.com/embed/Gc6t71lv4f0?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent
- Team: 1 GitHub contributor(s) — Qwynn Marcelle (63 commits)

## Devpost submission (written by the team)

No Devpost description available.

## README (from the GitHub repository)

> ### Historical namespace
>
> Development of the Codex integration is migrating to
> **[`workspacejson/integrations`](https://github.com/workspacejson/integrations)**.
> The specification lives in
> **[`workspacejson/standard`](https://github.com/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`](https://github.com/workspacejson) organization.

<br />

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/workspace-json-codex-lockup-dark.png">
    <source media="(prefers-color-scheme: light)" srcset="assets/workspace-json-codex-lockup-light.png">
    <img alt="workspace.json / Codex" src="assets/workspace-json-codex-lockup-dark.png" width="620">
  </picture>
</p>

<br />

<p align="center"><strong>Repository evidence that helps Codex plan around recorded risky changes.</strong></p>

<p align="center"><code>@workspacejson/codex-mcp</code></p>

<p align="center">
  <a href="https://github.com/workspace-json/codex-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/workspace-json/codex-mcp/actions/workflows/ci.yml/badge.svg"></a>
  <img alt="Node 20+" src="https://img.shields.io/badge/node-20%2B-339933?logo=node.js&logoColor=white">
  <img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue">
</p>

---

## 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:

```bash
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

```bash
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`.

<details>
<summary>MCP-only setup, CI check, the VS Code surface, and manual verification</summary>

### Wire the MCP server yourself

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

```toml
[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

```bash
# 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:

```bash
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:

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

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

```bash
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`](https://github.com/workspace-json/agents-audit) — a separate package in the same org:

```bash
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/`](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:


[README truncated for size]

## Detected evidence (automated analysis)

Indexed codebase: 84 recognized source files, 348 KB.
- HTML (language) — detected in the code
- TypeScript (language) — detected in the code
- Node.js (technology) — claimed on Devpost, not found in the code
- AI coding agent: Codex — evidence: config files committed to the repository

## Codebase structure (from repository index)

### Files (109 of 109)

```
.agents/plugins/marketplace.json
.codex-plugin/plugin.json
.codex/config.toml
.github/workflows/ci.yml
.github/workflows/publish-extension.yml
.github/workflows/publish-npm.yml
.gitignore
.mcp.json
.nvmrc
AGENTS.md
assets/Brand Lockup.html
assets/branding.md
assets/export-og.html
assets/readme-header-snippet.md
biome.json
CHANGELOG.md
config/repository-structure.json
CONTRIBUTING.md
docs/audits/worktree-reconciliation/2026-07-22/remediation-checklist.md
docs/audits/worktree-reconciliation/2026-07-22/remediation-results.md
docs/audits/worktree-reconciliation/2026-07-22/repository-reconciliation-report.md
docs/audits/worktree-reconciliation/2026-07-22/repository-reconciliation.json
docs/clean-install-audit.md
docs/development.md
docs/failure-modes.md
docs/fixture-verification.md
docs/how-it-works.md
docs/operational-guarantees.md
docs/project/runbook.md
docs/submission/build-week.md
docs/tools.md
docs/verification.md
docs/workspace-contract.md
extension/.gitignore
extension/.vscodeignore
extension/assets/walkthrough/generate.md
extension/CHANGELOG.md
extension/LICENSE
extension/package.json
extension/README.md
extension/src/changesetLogic.ts
extension/src/changesetTreeProvider.ts
extension/src/commandIds.ts
extension/src/commands.ts
extension/src/decorationProvider.ts
extension/src/extension.ts
extension/src/gitChangeset.ts
extension/src/hoverProvider.ts
extension/src/parseSnapshot.ts
extension/src/pathMatch.ts
extension/src/reviewerVerdict.ts
extension/src/semanticModel.ts
extension/src/statusBar.ts
extension/src/tooltips.ts
extension/src/treeModel.ts
extension/src/verdictRefresh.ts
extension/src/workspaceIntelligence.ts
extension/SUPPORT.md
extension/test/changesetLogic.check.ts
extension/test/intelligence.check.ts
extension/test/invariant.check.ts
extension/test/refresh.check.ts
extension/test/reviewerReceipt.check.ts
extension/test/reviewerVerdict.check.ts
extension/test/semanticModel.check.ts
extension/test/synchronization.check.ts
extension/test/tooltips.check.ts
extension/test/treeModel.check.ts
extension/tsconfig.json
fixture/.agents/workspace.json
fixture/package.json
fixture/src/auth/session.ts
fixture/src/bootstrap.ts
fixture/src/lib/format.ts
fixture/src/routes/checkout.ts
fixture/src/runtime/registry.ts
fixture/test/checkout.check.ts
hooks/hooks.json
hooks/pre-edit-check.mjs
LICENSE
package.json
README.md
scripts/check-generator-version.mjs
scripts/check-repo-structure.mjs
scripts/install.mjs
scripts/smoke.mjs
SECURITY.md
src/config.ts
src/constants.ts
src/evidence.ts
src/index.ts
src/path-match.ts
src/reviewer.ts
src/services/workspace.ts
src/tools/workspace.ts
src/types.ts
tests/repository-structure.test.ts
tests/unit/check-generator-version.test.ts
tests/unit/codex-config.test.ts
tests/unit/config.test.ts
tests/unit/evidence.test.ts
tests/unit/help-config.test.ts
tests/unit/installer.test.ts
tests/unit/package-bin.test.ts
tests/unit/path-match.test.ts
tests/unit/reviewer.test.ts
tests/unit/structured-bound.test.ts
tests/unit/workspace.test.ts
tsconfig.json
```

### Dependencies

- extension/package.json: @types/node@^22.0.0, @types/vscode@^1.85.0, @vscode/vsce@^3.6.0, typescript@^5.9.0
- package.json: @biomejs/biome@^1.9.4, @modelcontextprotocol/sdk@^1.20.0, @types/node@^22.0.0, publint@^0.3.21, typescript@^5.9.0, vitest@^3.2.7, zod@^3.25.0

### Recent commits (newest first)

- docs(readme): add hackathon submission snapshot for judges (#18)
- docs(audit): record cleanup wave three (#17)
- docs(audit): record duplicate branch cleanup (#16)
- docs(audit): record HAC-170 cleanup (#15)
- docs(audit): record worktree reconciliation (#14)
- release: 0.1.9 (#13)
- Release/0.1.8 (#12)
- release: 0.1.7 (array frameworkManifest normalizer) (#11)
- fix: normalize array framework manifests (#10)
- polish(extension): marketplace metadata + onboarding UX consistency (#9)
- polish(extension): syntax-color the Inspect Evidence output channel (#8)
- release: bump @workspacejson/codex-mcp to 0.1.5 (#7)
- fix: read both fileIndex/frameworkManifest shapes; conform demo fixture to spec 0.4.3 (#6)
- fix(ci): remove grep for non-existent .codex/agents/ path
- fix: bind the changeset to the most specific repo, not the first match
- fix: restore positional-only CLI dispatch in the installer
- chore(hac-170): public-release prep and repository cleanup
- chore(hac-170): on-brand marketplace icon (emerald .json dot on brand canvas)
- chore: keep local agent scratchwork out of source
- fix(hac-170): publisher is workspace-json (matches the marketplace namespace)

## Key source files (fetched from GitHub, selected and truncated for size)

### CONTRIBUTING.md

```markdown
# Contributing

Thanks for helping improve `@workspacejson/codex-mcp`.

## Development

This project uses Node.js 20+. Install dependencies with:

```bash
npm install
```

Run the standard check before submitting a PR:

```bash
npm test
```

This builds the TypeScript and runs the smoke suite.

## Pull requests

- Keep changes focused on one concern.
- Ensure `npm run build` and `npm run smoke` pass.
- Update `README.md` if the user-facing install or behavior changes.
- Add or update the `CHANGELOG.md` entry under the `[Unreleased]` section.

## Code of conduct

Be respectful and constructive. The project enforces the [Contributor Covenant](https://www.contributor-covenant.org) in spirit.

```

### SECURITY.md

```markdown
# Security Policy

## Supported versions

Only the latest published version of `@workspacejson/codex-mcp` receives security updates.

## Reporting a vulnerability

Please report security issues privately to the maintainers at the contact address on <https://workspacejson.dev>. Do not open public issues for vulnerabilities.

## Scope

This package runs locally over stdio and does not transmit repository contents over the network. Vulnerabilities of interest include: unsafe handling of workspace.json contents, path traversal, and anything that could allow the hook to block or allow edits outside the intended policy.

## Disclosure

We will acknowledge receipt within 5 business days and aim to release a fix or advisory within 30 days.

```

### package.json

```
{
  "name": "@workspacejson/codex-mcp",
  "version": "0.1.9",
  "description": "MCP server that surfaces workspace.json fragility and co-change intelligence to OpenAI Codex before it edits code.",
  "license": "Apache-2.0",
  "type": "module",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/workspace-json/codex-mcp.git"
  },
  "homepage": "https://workspacejson.dev/implementations/codex",
  "bugs": {
    "url": "https://github.com/workspace-json/codex-mcp/issues"
  },
  "keywords": [
    "codex",
    "mcp",
    "model-context-protocol",
    "workspace-json",
    "codebase-intelligence",
    "fragility",
    "co-change",
    "agent-hooks"
  ],
  "bin": {
    "codex-mcp": "scripts/install.mjs",
    "workspacejson-codex-mcp": "scripts/install.mjs"
  },
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "files": ["dist", "hooks", "scripts/install.mjs", ".codex-plugin", ".mcp.json", "vsix", "README.md", "LICENSE"],
  "scripts": {
    "build": "tsc",
    "build:extension": "rm -rf extension/node_modules extension/*.vsix vsix/*.vsix && npm --prefix extension ci && npm --prefix extension run package && mkdir -p vsix && cp extension/workspacejson-codex-decorations-*.vsix vsix/",
    "start": "node dist/index.js",
    "dev": "tsc --watch",
    "typecheck": "tsc --noEmit",
    "lint": "biome check .",
    "lint:fix": "biome check . --write",
    "format": "biome format --write .",
    "test": "vitest run --exclude '.claude/**'",
    "test:watch": "vitest --exclude '.claude/**'",
    "smoke": "node scripts/smoke.mjs",
    "check:structure": "node scripts/check-repo-structure.mjs",
    "check:generator-version": "node scripts/check-generator-version.mjs",
    "pack:check": "npm pack --dry-run && npx publint",
    "check": "npm run check:structure && npm run check:generator-version && npm run typecheck && npm run lint && npm run build && npm run test && npm run smoke",
    "verify": "npm run check",
    "prepublishOnly": "npm run check && npm run build:extension && npm run pack:check"
  },
  "engines": {
    "node": ">=20"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.20.0",
    "zod": "^3.25.0"
  },
  "devDependencies": {
    "@biomejs/biome": "^1.9.4",
    "@types/node": "^22.0.0",
    "publint": "^0.3.21",
    "typescript": "^5.9.0",
    "vitest": "^3.2.7"
  }
}

```

### fixture/package.json

```
{
  "name": "workspacejson-checkout-fixture",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --experimental-strip-types test/checkout.check.ts"
  }
}

```

### extension/package.json

```
{
  "name": "workspacejson-codex-decorations",
  "displayName": "workspace.json — Codex change intelligence",
  "description": "Surfaces local workspace.json fragility, co-change partners, and saved advisory-review receipts in VS Code. No telemetry. Running a new advisory review is an explicit action that sends only the supplied diff to the configured provider.",
  "version": "0.1.5",
  "publisher": "workspace-json",
  "license": "Apache-2.0",
  "engines": {
    "vscode": "^1.85.0"
  },
  "categories": [
    "Other"
  ],
  "keywords": [
    "workspace.json",
    "code-review",
    "fragility",
    "co-change",
    "agent-safety"
  ],
  "galleryBanner": {
    "color": "#07100e",
    "theme": "dark"
  },
  "badges": [
    {
      "url": "https://img.shields.io/badge/license-Apache--2.0-blue",
      "href": "https://github.com/workspace-json/codex-mcp/blob/main/LICENSE",
      "description": "License"
    },
    {
      "url": "https://github.com/workspace-json/codex-mcp/actions/workflows/ci.yml/badge.svg",
      "href": "https://github.com/workspace-json/codex-mcp/actions/workflows/ci.yml",
      "description": "CI Status"
    }
  ],
  "bugs": {
    "url": "https://github.com/workspace-json/codex-mcp/issues"
  },
  "homepage": "https://workspacejson.dev/implementations/codex",
  "pricing": "Free",
  "preview": true,
  "qna": false,
  "markdown": "github",
  "extensionKind": [
    "workspace"
  ],
  "author": {
    "name": "workspace.json",
    "url": "https://workspacejson.dev"
  },
  "main": "./out/src/extension.js",
  "activationEvents": [
    "onStartupFinished"
  ],
  "contributes": {
    "configuration": {
      "title": "workspace.json",
      "properties": {
        "workspacejsonCodex.decorations.enabled": {
          "type": "boolean",
          "default": true,
          "description": "Show Explorer decorations for the current-change decision recorded in .agents/workspace.json."
        }
      }
    },
    "viewsContainers": {
      "activitybar": [
        {
          "id": "workspacejson",
          "title": "workspace.json",
          "icon": "assets/icon.svg"
        }
      ]
    },
    "views": {
      "workspacejson": [
        {
          "id": "workspacejsonCodexChangeset",
          "name": "current change",
          "when": "workspaceFolderCount > 0 && workspacejsonCodex.changesetView.enabled",
          "contextualTitle": "workspace.json"
        }
      ]
    },
    "commands": [
      {
        "command": "workspacejson.focusCurrentChange",
        "title": "Show Current Change",
        "category": "workspace.json"
      },
      {
        "command": "workspacejson.inspectEvidence",
        "title": "Inspect Evidence",
        "category": "workspace.json"
      },
      {
        "command": "workspacejson.runVerification",
        "title": "Run Verification",
        "category": "workspace.json"
      },
      {
        "command": "workspacejson.runReview",
        "title": "Run Advisory Review",
        "category": "workspace.json"
      },
      {
        "command": "workspacejson.inspectReceipt",
        "title": "Inspect Review Receipt",
        "category": "workspace.json"
      },
      {
        "command": "workspacejson.openIntelligenceFile",
        "title": "Open Intelligence File",
        "category": "workspace.json"
      },
      {
        "command": "workspacejson.openFile",
        "title": "Open File",
        "category": "workspace.json"
      },
      {
        "command": "workspacejson.openWalkthrough",
        "title": "Open Getting Started Walkthrough",
        "category": "workspace.json"
      },
      {
        "command": "workspacejson.generateIntelligence",
        "title": "Generate Intelligence",
        "category": "workspace.json"
      }
    ],
    "menus": {
      "commandPalette": [
        {
          "command": "workspacejson.openFile",
          "when": "false"
        }
      ]
    },
    "viewsWelcome": [
      {
        "view": "workspacejsonCodexChangeset",
        "when": "workspacejsonCodex.viewState == noFile",
        "contents": "No `.agents/workspace.json` was found.\n\nGenerate one with `npx agents-audit@0.4.3 generate .` — it writes repository topology and hygiene. Today, `fileIndex` is empty and `manual` fragility/co-change evidence is human-authored (ASSERTED tier, not auto-generated).\n\n[Generate Intelligence](command:workspacejson.generateIntelligence)\n\n[Getting Started](command:workspacejson.openWalkthrough)"
      },
      {
        "view": "workspacejsonCodexChangeset",
        "when": "workspacejsonCodex.viewState == noEvidence",
        "contents": "Repository evidence is unavailable or stale. No deterministic assessment is being inferred.\n\n[Getting Started](command:workspacejson.openWalkthrough)"
      },
      {
        "view": "workspacejsonCodexChangeset",
        "when": "workspacejsonCodex.viewState == noChange",
        "contents": "No current change to assess.\n\nEdit or stage a repository file to see deterministic partner and fragility evidence here.\n\n[Getting Started](command:workspacejson.openWalkthrough)"
      },
      {
        "view": "workspacejsonCodexChangeset",
        "when": "workspacejsonCodex.viewState == malformed",
        "contents": "`.agents/workspace.json` could not be read.\n\nDeterministic assessment is unavailable until the file is corrected.\n\n[Getting Started](command:workspacejson.openWalkthrough)"
      }
    ],
    "walkthroughs": [
      {
        "id": "workspacejson.gettingStarted",
        "title": "workspace.json: Getting Started",
        "description": "Find the current-change intelligence view, read the deterministic decision, resolve it, and use advisory review.",
        "steps": [
          {
            "id": "generate",
            "title": "Generate workspace.json",
            "description": "The MCP server and hook consume `.agents/workspace.json`. Generate one with `npx agents-audit@0.4.3 generate .` — it writes repository topology and hygiene.
[truncated — 3966 more characters]
```

### src/index.ts

```typescript
#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { isVerifyEnabled } from "./config.js";
import { SERVER_INSTRUCTIONS } from "./constants.js";
import { registerWorkspaceTools } from "./tools/workspace.js";

const VERSION = "0.1.9";

function buildServer(): McpServer {
  const server = new McpServer(
    {
      name: "workspacejson-codex-mcp",
      version: VERSION,
    },
    {
      // Codex reads `instructions` during initialization and uses it as
      // server-wide standing guidance. This is what makes the fragility /
      // co-change check proactive rather than only-when-asked.
      instructions: SERVER_INSTRUCTIONS,
    },
  );

  registerWorkspaceTools(server);
  return server;
}

async function main(): Promise<void> {
  if (process.argv.includes("--help") || process.argv.includes("-h")) {
    process.stdout.write(
      [
        `workspacejson-codex-mcp v${VERSION}`,
        "",
        "MCP server exposing workspace.json fragility + co-change intelligence to Codex.",
        "",
        "Transport: stdio (spawned by an MCP client such as Codex).",
        "",
        "Environment:",
        "  WORKSPACE_JSON_PATH   Explicit path to a workspace.json file.",
        "  WORKSPACE_JSON_ROOT   Root dir to search (default: cwd).",
        "  WJSON_VERIFY=1        Opt in to the VERIFIED tier: re-run recorded read-only",
        "                        git commands to confirm evidence reproduces. Off by",
        "                        default; CLI/CI-time only (never on the hook hot path).",
        "",
        "Codex config (.codex/config.toml):",
        "  [mcp_servers.workspacejson]",
        '  command = "npx"',
        '  args = ["-y", "@workspacejson/codex-mcp", "server"]',
        "",
      ].join("\n"),
    );
    return;
  }

  const server = buildServer();
  const transport = new StdioServerTransport();
  await server.connect(transport);
  // stderr is safe for logging on stdio transports; stdout carries the protocol.
  console.error(`workspacejson-codex-mcp v${VERSION} ready on stdio${isVerifyEnabled() ? " (verify mode ON)" : ""}`);
}

main().catch((error) => {
  console.error("Fatal:", error instanceof Error ? error.stack : error);
  process.exit(1);
});

```

### src/config.ts

```typescript
/**
 * Verify-mode gate (HAC-111).
 *
 * VERIFIED is an OPT-IN, CI/CLI-time tier: it re-runs a recorded read-only git
 * command to confirm the evidence still reproduces. That is deliberately kept
 * OFF the Codex hook hot path — re-running git on every proposed edit would be a
 * latency machine (R-V3). Enable it explicitly with the `--verify` CLI flag or
 * `WJSON_VERIFY=1` in the environment (e.g. the MCP server's env block). Off by
 * default everywhere.
 */
export function isVerifyEnabled(env: NodeJS.ProcessEnv = process.env, argv: string[] = process.argv): boolean {
  return env.WJSON_VERIFY === "1" || argv.includes("--verify");
}

```

### assets/export-og.html

```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<!-- Fonts loaded directly from Google Fonts (Plus Jakarta Sans + Geist Mono) -->
<!-- rather than via the design system's local token file, so this asset has -->
<!-- no dependency on a sibling _ds/ directory. -->
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:ital,wght@0,400;0,500;0,600;0,700;0,800;1,400;1,500&family=Geist+Mono:wght@400;500;600;700&display=swap">
<style>
  * { margin: 0; padding: 0; box-sizing: border-box; }
  html, body { width: 100vw; height: 52.5vw; background: #07100e; overflow: hidden; display: flex; align-items: center; justify-content: center; }
  .lockup-inner { display: flex; flex-direction: column; align-items: flex-start; gap: 2.4vw; }
  .wordmark { font-family: "Plus Jakarta Sans", sans-serif; font-weight: 800; letter-spacing: -0.03em; white-space: nowrap; font-size: 6vw; color: #f5faf8; }
  .json-suffix { color: #00c896; }
  .slash { color: #00c896; font-weight: 500; }
  .codex { font-weight: 500; }
  .tagline { font-family: "Geist Mono", monospace; text-transform: uppercase; font-size: 1.3vw; color: #5d7a70; letter-spacing: 0.28em; margin-left: 0.4vw; }
</style>
</head>
<body>
  <div class="lockup-inner">
    <div class="wordmark">workspace<span class="json-suffix">.json</span> <span class="slash">/</span> <span class="codex">Codex</span></div>
    <div class="tagline">portable repository intelligence</div>
  </div>
</body>
</html>

```

### src/path-match.ts

```typescript
import { isAbsolute, normalize } from "node:path";

/**
 * THE path matcher. One implementation, imported by both the workspace service
 * and the evidence/enforcement layer, so there is exactly one definition of
 * "these two paths are the same file." A second matcher is how a deny silently
 * became a warn (audit Critical #1): the enforcement layer had drifted to a
 * symmetric fuzzy suffix match while the read layer was tightened. Never again —
 * both call these.
 *
 * Keys are pinned to META-102: repo-root-relative POSIX, forward slashes, no
 * leading "./", no trailing slash, no drive letters.
 */

export function normalizeKey(p: string): string {
  let s = normalize(p).replace(/\\/g, "/");
  s = s.replace(/^\.\//, ""); // drop leading ./
  if (s.length > 1) s = s.replace(/\/+$/, ""); // drop trailing slash(es)
  return s;
}

/** True if `query` and `storedKey` denote the same file. */
export function pathsMatch(query: string, storedKey: string): boolean {
  const q = normalizeKey(query);
  const s = normalizeKey(storedKey);
  if (q === s) return true;
  // Fallback, ONLY for an absolute query resolving to a repo-relative stored key
  // (a client may pass /abs/repo/src/x.ts for stored src/x.ts). Guarded so a bare
  // single-segment stored key (e.g. "client.ts") can never match an arbitrary
  // absolute path — the fallback requires the stored key to be multi-segment
  // (audit #13). No other fuzzy matching exists.
  if (isAbsolute(query) && s.includes("/") && q.endsWith(`/${s}`)) return true;
  return false;
}

```

### src/constants.ts

```typescript
/**
 * Shared constants for the workspace.json Codex MCP server.
 */

// Candidate locations for the workspace.json file, in priority order.
// The canonical location per the workspace.json standard is `.agents/workspace.json`.
// The others are accepted as fallbacks so the server works across consumer conventions.
export const WORKSPACE_JSON_CANDIDATES = [
  ".agents/workspace.json",
  ".workspace.json",
  "workspace.json",
  ".vreko/workspace.json",
] as const;

// Environment override: point directly at a workspace.json file.
export const ENV_WORKSPACE_PATH = "WORKSPACE_JSON_PATH";
// Environment override: root directory to search from (defaults to process.cwd()).
export const ENV_WORKSPACE_ROOT = "WORKSPACE_JSON_ROOT";

// Cap on how much text we return in any single tool response, to protect the
// agent's context window. Large lists are truncated with an explicit note.
export const CHARACTER_LIMIT = 12_000;

// Server-wide guidance handed to Codex during MCP initialization. Codex reads the
// `instructions` field and treats it as standing guidance for the whole server.
// Keep the first ~512 characters self-contained: that is the window most reliably
// consulted when the agent decides whether to reach for a tool.
export const SERVER_INSTRUCTIONS = [
  "This server exposes behavioral intelligence about the current workspace, sourced from a workspace.json file: which files are FRAGILE (historically error-prone or high-blast-radius) and which files CO-CHANGE (tend to be edited together).",
  "Before editing or creating any file, call workspace_get_file_context with the target path. If the file is fragile, proceed carefully and prefer minimal, well-tested changes. If it has co-change partners, inspect them for related updates you may also need to make.",
  "This is history the current source tree cannot tell you on its own. Use it as a prior, not a command: the human's intent still wins. All tools are read-only and operate on a local file; nothing leaves the machine.",
].join(" ");

```

[75 more indexed source files omitted to keep this export small. The full file list is in the Codebase structure section above.]