Origence Codex — VS Code Extension

Connects AI agents (Claude Code, Cursor, Copilot, OpenAI Codex CLI) to the Origence Codex — the org's security policies, platform knowledge, and threat model — in every repo, without cloning the Codex.

How It Works

The extension is a zero-step dropper — install the VSIX, and the MCP server is automatically bootstrapped and configured for all AI tools in your workspace.

Stage 1                    Stage 2                           Stage 3
Install VSIX ──────> Extension bootstraps MCP ───────> MCP server runs locally
(VS Code               binary into ~/.origence/bin/       and serves policies,
 Marketplace)           (signed standalone executable)     knowledge, and threat
                                                           model to your AI agent
Requires:              Automatic:                         Provides:
- VS Code              - Binary download + install        - 100+ coding policies
                       - Azure sign-in (VS Code prompt)   - 14+ knowledge docs
                       - Network to Azure Artifacts       - Library manifest
                                                          - Threat model

Stage 1 — Install the VSIX. From the VS Code marketplace (search "Origence Codex") or manually:

code --install-extension origence-codex-1.0.0.vsix

Stage 2 — Binary bootstrap (automatic). On activation, the extension checks for the MCP server binary at ~/.origence/bin/origence-codex-mcp (or %LocalAppData%\Origence\Codex\bin\origence-codex-mcp.exe on Windows). If not found, it automatically:

1. Downloads the published standalone binary artifact from Azure DevOps
2. Installs it into the Origence home directory
3. Runs origence-codex-mcp setup --add-to-path
4. Records a version marker for background upgrade detection

Authentication uses VS Code's built-in Microsoft sign-in (no az login needed). No runtime Python, uv, or local Codex clone is required.

Stage 3 — MCP server registration (automatic). Each client registers into its workspace config when one already exists, otherwise its global config — append-to-existing only, never created:

• VS Code's MCP provider API (preferred on supported VS Code builds)
• .vscode/mcp.json (fallback for older VS Code / Visual Studio builds)
• Claude Code: .mcp.json (project) → ~/.claude.json (global), HTTP transport
• Cursor: .cursor/mcp.json → ~/.cursor/mcp.json
• OpenAI Codex CLI: .codex/config.toml → ~/.codex/config.toml

Codex does not gate commits — see Policy gating: there isn't one, on purpose. The extension provides the binary, the policies, the knowledge base and the threat model; your agent reads them through the MCP tools as it works.

Once complete, your AI agent has access to:

• 100+ coding policies (security, quality, architecture)
• 60+ platform knowledge articles (architecture, domain model, multi-tenancy, etc.)
• Current technology choices (library-manifest.yaml)
• Threat model summary

The agent cites policy IDs in a structured codex_meta JSON block at the end of every response.

What Happens on Activation

If origenceCodex.autoSetup is enabled (default), the extension runs Stages 2-3 automatically:

1. Checks bin/ in the Origence home (~/.origence, or %LocalAppData%\Origence\Codex on Windows) and PATH for the MCP server binary.
2. If not found, downloads a fresh install into the Origence home.
3. If found but older than the extension, upgrades it in the background. A newer binary — installed by the Visual Studio extension at a higher version, in the same bin/ — is left in place: neither extension ever downgrades it.
4. Registers the MCP server for VS Code, Claude Code, Cursor, and OpenAI Codex CLI.
5. Loads the Policies, Knowledge Base and Threat Model views from the binary's local API. Each item opens in its own tab as the Codex page the binary lays out in the Origence home (webui/<version>/ui.html); the extension relays every read the page makes, proving the server first. When the page cannot load, the tab says why and offers Retry, Setup Workspace or Open in browser.
6. Shows a shield icon in the status bar when ready.

Uninstall

When the extension is uninstalled, the vscode:uninstall hook automatically:

• Removes MCP server entries from all workspace config files it ever wrote to
• Releases its claim on the Origence home, and deletes the home (binary, version marker, .api-port, catalog package, laid-out pages) and, on Windows, %USERPROFILE%\.origence\ once no other owner (the Visual Studio extension, an Intune install) claims the home

No manual cleanup needed.

Troubleshooting

Commands

Settings

Environment variables (development only)

Requirements

• Network access to dev.azure.com (Azure Artifacts) — needed only on first activation and upgrades
• VS Code Microsoft auth — used to acquire Azure DevOps feed tokens (no az login needed)

Policy gating: there isn't one, on purpose

Codex alerts; it never blocks (ADR-016 codex-alerts-never-blocks), and as of 2.4.0 it has no detection engine to block with (ADR-017 no-detection-engine); both live under decisions/ in the Codex repo. The origence-codex-mcp evaluate command this section used to document is gone, along with the published .pre-commit-hooks.yaml. Any pre-commit config still calling either one fails every commit and push — three repos were in that state and have been corrected.

Guidance reaches developers through the MCP tools instead, where Codex can explain why a policy exists and what the platform threat model says about the service being edited, rather than only rejecting a diff.

If a specific invariant genuinely needs a blocking gate, write it as a rule for a tool built to enforce rules — Semgrep, a Roslyn analyzer, or a stack-native linter — and keep Codex as the single place the reason for the rule is written down.

Uninstall and cleanup

code --uninstall-extension origence.origence-codex runs the bundled cleanup hook, which removes what the artifact manifest (src/artifacts.ts) lists:

• The origence-codex entry in the global configs ~/.claude.json, ~/.cursor/mcp.json, and ~/.codex/config.toml
• For every workspace this extension was activated in: the MCP server entry in .mcp.json, .vscode/mcp.json, .cursor/mcp.json, and .codex/config.toml
• The PATH entry written by ~/.origence/bin/origence-codex-mcp setup --add-to-path
• The extension's VS Code global storage
• Its claim on the Origence home (owners/vscode). The home itself — ~/.origence/, or %LocalAppData%\Origence\Codex\ on Windows (binary, HTTP-server pid file, version marker, .api-port, catalog package, the pages under webui/) — and on Windows %USERPROFILE%\.origence\, where released versions of the Visual Studio extension and of the binary write, go only when no other owner (the Visual Studio extension, an Intune install) claims the home.

Cleanup for users who already uninstalled an older version

The v1.x uninstall hook left several artifacts on disk (the ~/.claude.json entry, per-workspace pre-commit hooks, etc.). If you uninstalled v1.x and don't want to reinstall v2.x just to clean up, run the binary's built-in cleanup subcommand. The binary itself is what got installed at ~/.origence/bin/ (Linux/macOS) or %LocalAppData%\Origence\Codex\bin\ (Windows v2+) on first activation — it stays there after extension uninstall and serves exactly this case:

# Linux / macOS:
~/.origence/bin/origence-codex-mcp cleanup --orphans            # dry-run preview
~/.origence/bin/origence-codex-mcp cleanup --orphans --yes      # apply

# Windows (cmd or PowerShell):
%LocalAppData%\Origence\Codex\bin\origence-codex-mcp.exe cleanup --orphans
%LocalAppData%\Origence\Codex\bin\origence-codex-mcp.exe cleanup --orphans --yes

No external runtime needed — not Node, not PowerShell, not Python. The binary is the same PyInstaller-built artifact that ships with the extension; cross-platform behavior is a property of Python's standard library, exercised in CI on Linux, Windows, and macOS via pytest.

If you no longer have the binary on disk (e.g., you ran the v1.x uninstall AND deleted ~/.origence manually), download a fresh copy from the published ADO artifact or rebuild from source (pip install -e . from the repo root produces origence-codex-mcp on PATH).

It reads the tracked-workspaces list from every VS Code-family install path (Stable, Insiders, VSCodium) and removes only artifacts that carry the Codex marker or live under Codex-owned paths. User-authored pre-commit hooks and co-tenant MCP entries are preserved verbatim.

Build from Source

The extension ships on the VS Code Marketplace; build it from source only to test a change. From the repository root, with the Origence feed configured (knowledge/codex-contributing.md, Feed credentials):

just vsix-install    # npm ci --ignore-scripts at the root: both npm workspaces, no package's install script runs
just vsix-package    # build the extension, then package it with vsce

This produces vscode-extension/origence-codex-<version>.vsix. Do not run npm install: it runs every package's install script, and keytar's downloads a native build from GitHub, outside the Origence feed (ORG-SEC-0015).

Cross-platform test-review checklist

Every test for cross-platform code (anything in process-wrapper.ts, artifacts.ts, binary-resolver.ts, mcp-config.ts, and the Python codex_cli/cleanup.py) must survive the CI matrix (Linux + Windows + macOS). Common ways a "passes-locally" test fails on another platform:

• Hardcoded path separators in expected values. Use join() for the expected value, not a forward-slash string literal:

  // bad — fails on Windows where path.join returns backslashes
  expect(result).toBe("/home/foo/.origence");
  // good — matches host platform's separator
  expect(result).toBe(join("/home/foo", ".origence"));
  

• toContain / not.toContain against env-bearing strings. Anything that stringifies the whole config / entry / TOML can substring-match agent PATH entries on the failing platform (pipx_bin on macOS, C:\... on Windows). Scope to the field you actually want to constrain:

  // bad — matches pipx_bin in env.PATH on macOS
  expect(JSON.stringify(entry)).not.toContain("pip");
  // good — checks the actual contract
  expect(entry.command).not.toContain("pip");
  

• process.platform branches with one path untested. If your test has if (process.platform === "win32") { ... } else { ... }, the OPPOSITE branch only runs on the OPPOSITE OS in CI. Prefer separate it() blocks per platform with explicit skip, OR a parameterized helper that accepts platform as an injected arg (see computeOrigenceHome in binary-resolver.ts for the pattern, and install_dir_candidates in codex_cli/cleanup.py for the Python equivalent).

• spawnSync({ env: ... }) on Windows merges case-insensitively with the agent's real env. Don't trust env overrides for Windows-only env vars (LOCALAPPDATA, APPDATA); they leak through. Verify the contract via a unit test of the path-resolution helper instead.