OmniCodex

OmniCodex is a Windows-local, owner-authenticated Streamable HTTP MCP gateway for the callable tool surface of an already installed Codex runtime. It owns a separate hidden child runtime and never registers itself in the Codex desktop app, modifies Codex authentication/configuration, or controls the desktop app.

Install and configure

Requirements: Windows, Node.js 22.12 or newer, and an installed Codex runtime.

npm install --global @heelee912/omnicodex
omnicodex init --issuer https://tenant.example/ --audience https://mcp.example `
  --resource https://mcp.example --subject owner-sub
omnicodex auth login             # official Auth0 device flow; refresh token stays in Windows keyring
omnicodex auth setup             # idempotently creates the dedicated API and strict DCR grant
omnicodex start
omnicodex status
omnicodex runtime probe --json  # isolated hidden runtime + full-surface live check

Initialization is fail-closed. OAuth issuer, audience/resource, scopes, and the owner sub must match. auth login downloads a pinned, checksum-verified official Auth0 CLI when one is not supplied and uses its Windows-keyring-backed device login. No Management API token is written to OmniCodex configuration. OmniCodex binds locally to 127.0.0.1; remote access requires an explicitly configured authenticated HTTPS ingress.

Optional Oracle consent companion

The optional companion attaches only to an explicitly configured loopback Chrome DevTools endpoint. It never launches, profiles, navigates, or terminates Chrome. Setup is a dry-run unless --execute is supplied.

omnicodex oracle setup --connector-id exact-id --connector-name OmniCodex `
  --run-id exact-run --resource https://mcp.example/mcp --surface /mcp/full `
  --cdp-endpoint http://127.0.0.1:9222 --non-interactive
omnicodex oracle status --json
omnicodex oracle test                 # no click
omnicodex oracle test --execute       # Connect / Always allow only
omnicodex oracle disable --execute

It is bound to the exact app, run, session, resource, and surface. General, one-time, destructive, stale, ambiguous, or reconnected confirmations fail closed. Receipts contain identifiers and state hashes only—never prompts, screenshots, secrets, or raw tool content.

Architecture and safety

• The installed runtime is the authority for callable tools.
• Ordinary calls do not silently become model calls.
• Protected Codex files are read-only and hash-checked by the non-interference guard.
• Owned console children use hidden/no-window creation.
• OAuth resource, issuer, scope, and owner subject are checked before MCP sessions.
• Browser automation is optional and separate from MCP server authority.

Operational commands include doctor, logs, runtime discover, runtime probe, autostart, auth, tunnel, update, and rollback. Run omnicodex --help for details.

Documentation: 한국어 · 日本語 · 中文 · source attribution.

Release policy

Maintainers run npm run check, npm run build, and npm pack --dry-run. Publishing is intentionally separate: npm publish --provenance --access public must run only from the protected GitHub release workflow after review. No local release script publishes, pushes, deploys, or changes GitHub state.

MIT licensed. This community project is not an official OpenAI product.