claude-to-codex
lobo235/claude-to-codex
Bridge Claude Code MCP servers, skills, and slash commands into Codex.
Instalação
npx convez-ai lobo235/claude-to-codex1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
claude-to-codex
claude-to-codex lets Claude Code users try Codex without rebuilding their local automation. It carries over Claude Code MCP servers, skills, slash commands, and project conventions into Codex.
What To Type
Daily use:
cwc
Setup verification:
cwc --doctor
cwc --status
cwc --smoke-test
cwc --version
cwc --help
Uninstall preview:
cwc --uninstall --dry-run
Names To Know
cwc: the daily launcher. Run this from a project instead ofcodex.claude-to-codex: the maintenance CLI. It serves MCP, syncs skills/commands, and provides diagnostics.claude-bridge: the Codex MCP server entry that runsclaude-to-codex serve.codex-with-claude: the same launcher ascwc, kept as a longer, explicit alias.
Quick Start
git clone https://github.com/lobo235/claude-to-codex.git ~/dev/claude-to-codex
cd ~/dev/claude-to-codex
./install.sh
codex mcp add claude-bridge -- claude-to-codex serve
cwc --doctor
cwc
MCP is how Codex talks to external tools. See docs/mcp-and-claude-bridge.md for a short explanation of MCP and what claude-bridge does.
Setup Paths
There are three supported ways to set this up. They should all end in the same complete setup state.
- Read this README and run the commands yourself.
- Paste SETUP_PROMPT.md into Claude Code or Codex and let an agent do the setup.
- Give an agent this repository URL and say "install this"; the agent should follow this README and use SETUP_PROMPT.md as the detailed checklist.
If you are starting from Claude Code only, follow docs/cold-start.md first. That guide includes the manual OpenAI account, Codex install, and login checkpoints.
Complete Setup Means
A complete setup has all of these:
claude-to-codex,cwc, andcodex-with-claudeinstalled onPATH- Codex installed and logged in
- Codex MCP entry
claude-bridgeconfigured to runclaude-to-codex serve - Claude skills, agents, and slash commands synced into generated Codex artifacts
cwc --doctor,cwc --status, andcwc --smoke-testrun without unexpected failures- daily use is simply
cwcfrom inside a project
Install Details
Requirements:
- Linux, WSL/WSL2, or macOS
- Go matching
go.modor newer - Git
- Node.js/npm if you want the standard Codex CLI npm install path
- Codex installed and available as
codex - Claude Code config already present if you want to bridge existing Claude setup
Install:
git clone https://github.com/lobo235/claude-to-codex.git ~/dev/claude-to-codex
cd ~/dev/claude-to-codex
./install.sh
If you prefer Make directly:
make test build install
To install somewhere other than ~/.local, set PREFIX:
PREFIX=/usr/local ./install.sh
make PREFIX=/usr/local install
The install step places these commands in $PREFIX/bin:
claude-to-codex: the maintenance CLIcwc: the daily launchercodex-with-claude: the same launcher with a more explicit name
Make sure $PREFIX/bin is on your PATH:
export PATH="$HOME/.local/bin:$PATH"
That command is correct for the default PREFIX=$HOME/.local; adjust it if you choose a different prefix.
Configure Details
Add claude-bridge as a Codex MCP server:
codex mcp add claude-bridge -- claude-to-codex serve
Or edit ~/.codex/config.toml directly:
[mcp_servers.claude-bridge]
command = "claude-to-codex"
args = ["serve"]
If claude-bridge already exists and points at claude-to-codex serve, leave it alone. If it points somewhere else, stop and confirm it is safe to replace because it may be user-owned.
Use cwc for normal project launches. It computes the environment
variable names referenced by Claude MCP config and starts Codex with a
session-scoped mcp_servers.claude-bridge.env_vars override so
Claude local-scope MCP entries, project-scoped .mcp.json entries, and
HTTP/SSE headers can reach the claude-bridge process. It forwards
variable names only; values stay in the launching environment.
If a Claude local-scope MCP entry or project .mcp.json references values
from a private env file, source that file before launching cwc. Changing
a token, env file, MCP config, or project root requires a fresh Codex
session because an already-running Codex-managed claude-bridge keeps
its original environment.
Verify
Preferred checks:
cwc --doctor
cwc --status
cwc --smoke-test
Lower-level checks:
claude-to-codex inspect
claude-to-codex inspect --tools
claude-to-codex bridge-env-vars --project "$PWD"
claude-to-codex sync-skills
claude-to-codex sync-agents
claude-to-codex sync-commands
claude-to-codex sync-artifacts --artifact-cache-dir /tmp/cwc-cache --project "$PWD"
Then launch Codex from a project:
cwc
Use cwc instead of codex when you want project-scoped Claude MCP
servers to load correctly. The launcher sets CLAUDE_BRIDGE_PROJECT_ROOT
and passes Codex a per-session claude-bridge env_vars override for
that project root plus any ${VAR} / $VAR references in Claude MCP
config, including local-scope entries that Claude stores under the
active project in ~/.claude.json.
cwc reserves only its top-level maintenance options: --doctor,
--status, --smoke-test, --install, --uninstall, --version,
and --help. Any other arguments are passed through to codex. If a
future Codex top-level flag needs one of those names, use cwc -- <args...> to force pass-through.
cwc --help prints codex --help first, then appends the
cwc-specific options. cwc --version prints the installed
claude-to-codex version and exits without launching Codex.
Secret Scanning
This repo includes a Gitleaks pre-commit hook:
sudo apt install pre-commit
pre-commit install
pre-commit run gitleaks --all-files
On macOS, use brew install pre-commit. If you prefer Python tooling,
install pre-commit with pipx or your normal Python package manager.
The same full-repo scan is available through Make:
make secrets
If the hook reports a real secret, rotate it before committing. If it
reports a confirmed false positive, prefer changing the example value;
use .gitleaksignore only for a specific fingerprint that cannot be
rewritten cleanly.
MCP Security
Claude local-scope MCP entries and project .mcp.json files are trusted
code: stdio MCP servers can run local commands. Run cwc only inside
projects whose MCP configuration you trust.
claude-bridge starts stdio MCP servers with a restricted environment
by default. It passes a small non-secret baseline such as PATH,
HOME, temp, locale, and certificate variables, then adds only the
server's explicit env values from Claude MCP config. Ambient shell
secrets such as cloud tokens, API keys, and database URLs are not passed
to every child MCP process.
If a legacy MCP server requires ambient shell environment variables, prefer opting in for only that server:
{
"mcpServers": {
"legacy-tool": {
"command": "legacy-mcp",
"x-claude-bridge-inherit-env": true
}
}
}
For temporary compatibility debugging, this global escape hatch restores full environment inheritance for all stdio MCP children:
CLAUDE_BRIDGE_INHERIT_ENV=1 cwc
HTTP MCP headers and stdio env values are never printed by normal
diagnostics. Diagnostic URLs and error text are redacted for common
token, key, secret, password, authorization, credential, and signature
patterns.
What It Does
claude-to-codex serve starts a Codex-facing MCP server named claude-bridge.
When Codex connects to claude-bridge, claude-to-codex:
- Reads user-scoped MCP servers from
~/.claude.json. - Detects the active project root.
- Reads Claude local-scope MCP servers from the active project's entry in
~/.claude.json. - Reads project-scoped MCP servers from
<project>/.mcp.json. - Applies MCP server precedence by name: project
.mcp.jsonoverrides Claude local scope, and Claude local scope overrides user scope. - Connects to each configured Claude MCP server as a child MCP client.
- Re-exposes child tools, prompts, resources, resource templates, completions, subscriptions, and reads through one Codex MCP server.
Claude-style HTTP MCP entries are supported for streamable HTTP and
legacy SSE transports. For SSE, use type: "sse" with url and optional
headers:
{
"mcpServers": {
"remote-tools": {
"type": "sse",
"url": "https://example.com/sse",
"headers": {
"Authorization": "Bearer ${REMOTE_TOOLS_TOKEN}"
}
}
}
}
String values in MCP server config support ${VAR} and $VAR environment
expansion. Missing variables fail that child server closed before the
bridge connects to it; unrelated child servers can still start.
When launched with cwc, those variable names are forwarded to the
Codex-managed claude-bridge MCP process for that session. The forwarded
entries are variable names, not secret values; the values must already be
present in the environment that launches cwc.
The cwc launcher also syncs Claude user and project artifacts before launching Codex:
~/.claude/skills/<name>/SKILL.mdis mirrored into a generated Codex-compatible wrapper at$CODEX_HOME/skills/<name>/SKILL.md, or~/.codex/skills/<name>/SKILL.mdwhenCODEX_HOMEis unset.~/.claude/agents/*.mdis mirrored into generated Codex agent TOML under$CODEX_HOME/agents/*.toml, or~/.codex/agents/*.tomlwhenCODEX_HOMEis unset.<project>/.claude/agents/*.mdis mirrored into generated Codex agent TOML under<project>/.codex/agents/*.toml.~/.claude/commands/*.mdis mirrored into generated Codex skill wrappers under$CODEX_HOME/skills/<command>/SKILL.md, or~/.codex/skills/<command>/SKILL.mdwhenCODEX_HOMEis unset.
Generated skill wrappers and agent TOML files point back to the Claude source. Claude remains canonical. Hand-written Codex skills and agents are not overwritten. Descriptions are generated with codex exec using a fast model, then cached by source hash so unchanged artifacts are not rewritten on every launch. The generator receives only Claude metadata and a bounded, sanitized preview, not the full skill or agent body.
Set CLAUDE_TO_CODEX_FRONTMATTER_MODEL to override the default fast model, or set CLAUDE_TO_CODEX_DISABLE_CODEX_FRONTMATTER=1 to force deterministic fallback descriptions.
For headless automation, set CLAUDE_TO_CODEX_ARTIFACT_CACHE_DIR.
When that variable is present, cwc runs sync-artifacts instead of the
desktop sync sequence. Generated wrappers and agent TOML are refreshed in
a schema/versioned persistent cache, then materialized into CODEX_HOME
if set, otherwise $HOME/.codex. The cache contains only generated
artifacts, not Codex auth, config, sessions, logs, or other runtime state.
Project agents are cached outside the repository and materialized into
$CODEX_HOME/agents, so automation mode does not write
<project>/.codex/agents.
Auto-agents workers should mount persistent storage at
/mnt/fast/auto-agents and keep $HOME/CODEX_HOME allocation-local:
HOME="$ALLOC_HOME" \
CODEX_HOME="$ALLOC_CODEX_HOME" \
CLAUDE_TO_CODEX_ARTIFACT_CACHE_DIR=/mnt/fast/auto-agents/cwc-cache \
cwc exec ...
When cwc has to generate frontmatter or agent descriptions, it prints progress such as:
generating frontmatter for <skill_name> [1/20 skills]
generating description for agent <agent_name> [1/3 agents]
For Agents
If the user gives you this repository URL and says "install this":
- Follow this README.
- Use SETUP_PROMPT.md as the detailed checklist.
- Preserve unrelated Codex and Claude Code state.
- End with
cwc --doctor,cwc --status,cwc --smoke-test, and tell the user daily use iscwc.
Uninstall
To remove claude-to-codex files and return to plain Codex/Claude Code:
cd ~/dev/claude-to-codex
cwc --uninstall --yes
For a preview:
cwc --uninstall --dry-run
The uninstaller removes installed claude-to-codex/cwc commands, generated Codex skill wrappers and agents containing generated-by: claude-to-codex, and the claude-bridge MCP entry only when it points at claude-to-codex. It does not remove unrelated Codex config, auth, agents, plugins, MCP entries, hand-written skills, or Claude Code files.
Tool Names
Codex sees child tools and prompts as native tools on the configured
claude-bridge MCP server. To preserve the original Claude MCP server
identity, claude-to-codex always prefixes bridged tool and prompt names
with the child server name:
wiki__wiki_get_article
project_mcp__status
filesystem__list
Calls are routed back to the original child server and original tool name. In Codex's function-tool UI, the full native tool name includes the Codex MCP server plus this exposed child-prefixed name.
Links
Security Notes
claude-to-codex reads local Claude and Codex configuration files and starts the MCP servers already configured on your machine. It does not copy secrets into this repository and does not create a new remote service.
Treat inspect --tools like starting your MCP servers: it may execute local stdio MCP commands or connect to HTTP MCP endpoints configured in Claude.
Review generated Codex skills and agents before relying on them. The generated artifacts instruct Codex to use the Claude source as canonical context.
Development
make lint
make test
make cover
make vuln
make build
make inspect
make inspect-tools
The binary version is embedded at build time from git describe --tags --always --dirty.
Public Repo Checklist
Before publishing or tagging:
- Review
LICENSEand change it if MIT is not the intended license. - Confirm the GitHub repository path is
github.com/lobo235/claude-to-codex; if not, updatego.modand README install commands. - Run
make lint test cover vuln build. - Push to GitHub and confirm the CI workflow passes.
Official Codex Links
- OpenAI Codex CLI getting started: https://help.openai.com/en/articles/11096431-openai-codex-ci-getting-started
- Codex CLI sign in with ChatGPT: https://help.openai.com/en/articles/11381614-codex-cli-and-sign-in-withgpt