Run Codex as a safe sidecar for reviews, exploration, risk checks, and small scoped fixes without handing it your active working tree.
日本語 README | Usage | Architecture | Protocol
codex-sidecar is a shared execution layer for calling Codex from another
developer workflow. It gives humans, Claude Code, MCP clients, hooks, and other
automation a stable way to ask Codex for a second opinion while preserving
machine-readable results, raw App Server diagnostics, and safety boundaries.
Callers can let Codex inherit its configured model or set an explicit
per-request/preset model policy when a workflow needs one.
It is not an OpenAI API gateway. It is not an image generation proxy. Its job is to make Codex useful as a controlled companion process inside real repositories.
Install the CLI globally:
npm install -g codex-sidecar-cliInstall the MCP stdio server globally when a client wants a command on PATH:
npm install -g codex-sidecar-mcpThe MCP package is distributed as an npm bin. npm global installs normally
place a symlink on PATH, and codex-sidecar-mcp is tested to start correctly
through that symlinked command.
Build from source:
corepack pnpm install
corepack pnpm buildCheck how a target project config resolves:
codex-sidecar diagnostics \
--project /path/to/project \
--preset review \
--model gpt-5.5 \
--model-reasoning-effort mediumAsk Codex to explore a codebase through the real App Server:
codex-sidecar explore \
--project /path/to/project \
"Find where request safety is enforced and cite files."Ask Codex to make a scoped fix in an isolated worktree:
codex-sidecar work \
--project /path/to/project \
--preset work \
"Add the smallest regression test for the parser."codex_work preserves the generated worktree by default so the caller can
inspect the diff before applying anything.
| CLI workflow | MCP tool | Purpose | Writes? | Output highlights |
|---|---|---|---|---|
review |
codex_review |
Review a diff, branch, or patch | No | findings, missingTests, residualRisks |
explore |
codex_explore |
Investigate a codebase question | No | summary, fileReferences |
opinion |
codex_opinion |
Challenge a plan or design | No | recommendation, objections, assumptions |
risk-check |
codex_risk_check |
Focus on secrets, MCP, OAuth, hooks, Docker, CI | No | risks, sourceBoundaries |
auditor |
codex_auditor |
Return a primary tool-use auditor judgment | No | pass, missingTools |
work |
codex_work |
Implement a small scoped change | Isolated worktree only | changedFiles, tests, worktreePath |
Every workflow returns one SidecarResult JSON object. Downstream tools should
consume the structured fields instead of scraping prose.
| Approach | What it is good at | Where codex-sidecar helps |
|---|---|---|
| Codex CLI directly | Interactive Codex sessions | Stable request/result JSON, raw logs, presets, and caller-owned safety policy |
| Claude Code alone | Primary implementation flow | Adds Codex as a second opinion without replacing Claude's working context |
| A bespoke MCP tool | One workflow in one repo | Shared CLI/MCP/core contracts across repositories |
| Direct active-tree automation | Fast local edits | codex_work keeps writes in a git worktree and reports changed files |
flowchart LR
caller[Human, Claude Code, MCP client, hook, or automation]
cli[packages/cli]
mcp[packages/mcp]
core[packages/core]
config[.codex-sidecar.yml]
app[Codex App Server]
worktree[isolated git worktree]
logs[raw JSONL event logs]
result[SidecarResult JSON]
caller --> cli
caller --> mcp
cli --> core
mcp --> core
config --> core
core --> app
core --> logs
app --> core
core --> result
core -->|codex_work only| worktree
worktree --> app
The CLI and MCP package stay thin. packages/core owns config loading, preset
resolution, safety policy, App Server protocol handling, structured output
parsing, raw event logs, and worktree isolation.
Consuming repositories provide .codex-sidecar.yml:
project: example-project
defaults:
readonly: true
result_format: json
safety_profile: generic
allowed_paths:
- src/
- docs/
- tests/
deny_paths:
- .env
- .env.*
- "**/*.key"
- "**/*.pem"
presets:
review:
workflow: review
readonly: true
prompt: "Review this change for regressions and missing tests."
work:
workflow: work
readonly: false
require_worktree: true
prompt: "Implement a small scoped change within allowed_paths."See docs/USAGE.md for CLI options, MCP input examples, worktree behavior, raw App Server logs, and structured result examples.
packages/mcp ships both a stdio transport (the npm bin default) and a
Streamable HTTP transport. The HTTP mode lets a single host serve multiple
LAN-local MCP clients (Claude Code on other machines, hooks, automation)
without putting codex-sidecar-mcp on every workstation.
The repository includes a Dockerfile and docker-compose.yml that build the
MCP server and bind it to a chosen LAN IP only:
# On the host that will run the sidecar
git clone https://github.com/kitepon-rgb/codex-sidecar.git
cd codex-sidecar
docker compose up -d --buildThe defaults bind to 192.168.1.2:39201/tcp and mount ~/.codex (Codex CLI
auth) and ~/projects (consumer repos) into the container. Override per host
via env or a sibling .env file:
CODEX_SIDECAR_BIND_HOST=10.0.0.5 \
CODEX_SIDECAR_PORT=39201 \
CODEX_HOME_HOST=/home/alice/.codex \
PROJECTS_HOST=/home/alice/projects \
docker compose up -d --buildAdd a firewall rule restricting access to the local subnet, e.g. with UFW:
sudo ufw allow from 192.168.1.0/24 to any port 39201 proto tcp comment 'codex-sidecar-mcp LAN'Optional bearer-token enforcement is available via CODEX_SIDECAR_MCP_BEARER
in compose; clients then must send Authorization: Bearer <token>. DNS
rebinding protection (CODEX_SIDECAR_MCP_ALLOWED_HOSTS) is enabled by default
and must list both the bare host and host:port since the MCP SDK matches the
HTTP Host header verbatim.
Sample MCP client config:
{
"mcpServers": {
"codex-sidecar-lan": {
"type": "http",
"url": "http://192.168.1.2:39201/mcp"
}
}
}Callers must pass server-side paths in projectRoot (for example
/projects/<repo>), not paths from the client machine.
See docs/USAGE.md for the full HTTP transport reference, env vars, and operational commands.
codex-sidecar was built for an environment where Claude Code is the primary
agent and Codex is a controlled sidecar. It is designed to compose with nearby
tools without requiring them:
- Relay stores and retrieves cross-device Claude conversation context.
- Throughline compresses Claude Code context and carries explicit handoffs.
- Caveat stores long-term trap memory and repo-specific gotchas.
- SmartClaude measures and optimizes token/context cost.
- CodeGraph provides local symbol graph context when a repository is initialized.
- image-generator and IP-MCP provide MCP/OAuth/deployment patterns and source-boundary lessons.
codex-sidecar/
├─ docs/
│ ├─ README.md
│ ├─ TODO.md
│ ├─ CODEX_MODEL_POLICY_TODO.md
│ ├─ ARCHITECTURE.md
│ ├─ PROTOCOL.md
│ ├─ USAGE.md
│ └─ archive/
├─ examples/
│ └─ .codex-sidecar.yml
├─ packages/
│ ├─ core/
│ ├─ cli/
│ └─ mcp/
├─ package.json
├─ pnpm-workspace.yaml
└─ tsconfig.base.json
The current spine is functional:
- config validation and preset/request normalization
- path safety, safety profiles, and structured refusals
- stable
SidecarRequest/SidecarResulttypes - CLI commands for all workflows
- MCP tool descriptors, schemas, and core-backed handlers
- Codex App Server stdio client and read-only turn execution
- structured result normalization for App Server-backed workflows
- raw App Server JSONL event logs with
rawEventLogRef - caller-selected turn timeouts and optional interruption
- worktree-backed
codex_workwith changed-file reporting - ecosystem context adapters and fixture snapshots
- local CodeGraph index support for this repository
The current release is ready for npm-based CLI and MCP installation. The MCP
stdio server is verified against npm-style symlinked bin startup, which is the
normal path for Claude Code and other MCP clients that launch
codex-sidecar-mcp from PATH. Caveat adoption is implemented through
caveat codex-sidecar ... commands and optional Claude hook advisory.
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build- AGENTS.md: working instructions for Codex and future agents.
- docs/README.md: docs index and archive map.
- docs/USAGE.md: CLI, MCP handler, worktree, raw log, and structured result examples.
- docs/ARCHITECTURE.md: package boundaries, layering, safety model, and result contract.
- docs/PROTOCOL.md: Codex App Server protocol boundary and stable sidecar contracts.
- docs/TODO.md: durable task list and linked GitHub issues.
- docs/CODEX_MODEL_POLICY_TODO.md: explicit Codex model policy plan and task list.
MIT