Content
# cc-in-codex
> Main document in Chinese. English README: [README.en.md](./README.en.md)
`cc-in-codex` is a local MCP server that allows Codex to utilize your locally logged-in Claude Code, transforming it into a persistent companion for the current project.
The goal of this tool is not to create another one-time code generator but to establish a more efficient dual-agent workflow:
- You only interact with Codex.
- Codex acts as the lead agent, responsible for thinking, breaking down tasks, judging, reviewing, and summarizing.
- Claude Code serves as the implementation companion, responsible for reading repository files, modifying code, running tests, refactoring, executing commands, and using its own subagent/skill system.
- The same project directory is bound to the same Claude Code companion, allowing context to accumulate persistently or be restored from the Claude Code CLI.
## Table of Contents
- [Why is it needed?](#why-is-it-needed)
- [Core capabilities](#core-capabilities)
- [Working model](#working-model)
- [Two backends: SDK and TUI](#two-backends-sdk-and-tui)
- [System requirements](#system-requirements)
- [Installation and building](#installation-and-building)
- [Registering MCP in Codex](#registering-mcp-in-codex)
- [Quick start: New project](#quick-start-new-project)
- [Continuing an existing Claude Code project](#continuing-an-existing-claude-code-project)
- [Visible TUI mode](#visible-tui-mode)
- [How Codex should call](#how-codex-should-call)
- [MCP tool descriptions](#mcp-tool-descriptions)
- [Context, resume, and compact](#context-resume-and-compact)
- [Status bar and context pressure monitoring](#status-bar-and-context-pressure-monitoring)
- [Security and permission model](#security-and-permission-model)
- [Local state and privacy](#local-state-and-privacy)
- [CLI usage](#cli-usage)
- [Development and release checks](#development-and-release-checks)
- [Frequently asked questions](#frequently-asked-questions)
- [Current boundaries](#current-boundaries)
- [Recommended workflow](#recommended-workflow)
- [Open-source agreement](#open-source-agreement)
## Why is it needed?
The strengths of Codex and Claude Code are not entirely the same.
In many real engineering tasks, a natural division of labor is:
- Codex is more suitable for scientific thinking, scheme weighing, task decomposition, risk judgment, code review, and final decision-making.
- Claude Code is more suitable for local engineering execution: reading large files, modifying code, running tests, processing tool chains, using subagents, and continuously advancing implementation.
If Codex were to send a standalone task to Claude Code every time, the effect would be poor:
- Claude Code's context is not continuous.
- Codex does not know what Claude Code has done before.
- Users need to manage two agents simultaneously.
- Prompts are prone to duplication, lengthening, and context pollution.
- There is a lack of timely monitoring and loss control when issues arise.
`cc-in-codex` solves this interaction problem. It allows Codex to manage a local, persistent, and recoverable Claude Code companion through MCP. Users only need to interact with Codex, and Codex will call Claude Code at the right time and review its results.
## Core capabilities
`cc-in-codex` currently provides:
- Using the local `claude` executable and local Claude Code login status, including Claude Max accounts.
- No new Anthropic API key is required.
- Each `cwd` maintains a persistent Claude Code companion.
- Supports SDK backend for Codex background delegation of code tasks and waiting for results.
- Supports TUI backend, running native Claude Code full-screen CLI in `tmux`, allowing users to watch or take over in real-time.
- Supports resuming from an existing Claude Code session:
- SDK: binding a clear `sessionId`.
- TUI: `claude --resume <session-id>` or `claude --continue`.
- Supports raw TUI input, such as `/status`, `/help`, `/clear`, `Escape`, `C-c`.
- Supports Claude Code statusLine, reading real `context_window` information for determining whether to compact.
- Supports `companion_tui_compact_check` and `companion_tui_compact`, allowing compaction to occur at reasonable nodes rather than mechanically triggered.
- Supports stop-loss: SDK backend has runtime and stall timeout; TUI backend can be explicitly interrupted by Codex or the user.
- Supports project initialization: generating shared `AGENTS.md` and `CLAUDE.md`, allowing Codex and Claude Code to read the same project instructions.
- State is only stored in the local `~/.cc-in-codex/`.
## Working model
The basic idea of `cc-in-codex` is:
```text
User
|
v
Codex
|
| MCP tools
v
cc-in-codex
|
| local claude executable
v
Claude Code companion
|
v
Project files / tests / tools
```
Responsibility boundaries:
- Users only interact with Codex.
- Codex is the lead agent, responsible for judging when Claude Code is needed, giving high-quality task prompts, monitoring execution, and reviewing results.
- Claude Code is the implementation companion, responsible for executing engineering tasks in the local project.
- `cc-in-codex` is the connection layer, not replacing Codex or Claude Code.
This means Claude Code's output is not the final answer; Codex still needs to review and synthesize.
## Two backends: SDK and TUI
### SDK backend
SDK is the default backend, suitable for daily background delegation.
Characteristics:
- Codex calls `companion_send` or `companion_start`.
- Claude Code completes tasks in SDK/print style.
- Codex can obtain structured results, events, cost, turn count, and session id.
- Suitable for code modification, testing, auditing, small refactoring, and read-only analysis.
Recommended scenarios:
- “Let Claude Code fix this bug and run the test.”
- “Let Claude Code read these modules and give me an implementation report.”
- “Let Claude Code execute a set of clear engineering tasks.”
### TUI backend
TUI backend opens the native Claude Code CLI in `tmux`.
Characteristics:
- You can attach to the Codex right-terminal and see Claude Code's native ASCII/TUI interface.
- Codex can send task prompts to this TUI.
- You can also type directly in the TUI, send slash commands, and take over the session.
- TUI backend does not attempt to “guess task completion” from the full-screen terminal; it is more like visible remote control.
Recommended scenarios:
- You want to watch in real-time what Claude Code is doing.
- Tasks are complex, and you want to retain manual takeover capabilities.
- You want to continue the experience of the existing Claude Code CLI.
- You want to use Claude Code's own TUI capabilities, slash commands, resume picker, or subagent workflow.
### How to choose
Use SDK by default. Use TUI when you need to “see the Claude Code native interface” or “human takeover at any time.”
| Scenario | Recommendation |
| --- | --- |
| Background execution of clear tasks | SDK |
| Codex needs to wait for results and review | SDK |
| Need to watch Claude Code UI in real-time | TUI |
| Need to input slash commands manually | TUI |
| Continue recent Claude Code CLI conversation | TUI `--continue` |
| Precisely bind existing session id | SDK or TUI |
## System requirements
- Node.js 22 or later.
- Locally installed and logged-in Claude Code, `claude --version` can run.
- Codex supports MCP server.
- TUI mode requires `tmux`.
macOS installation `tmux`:
```bash
brew install tmux
```
Confirm dependencies:
```bash
node --version
claude --version
tmux -V
```
## Installation and building
Install from source:
```bash
npm install
npm run build
```
Development check:
```bash
npm run typecheck
npm run build
npm run smoke
```
`npm run smoke` will not start real Claude tasks or create TUI sessions. It only checks:
- MCP server can start normally and expose key tools.
- SDK resume binding logic is available.
- CLI help includes resume/continue options.
## Registering MCP in Codex
Register the built server to Codex:
```bash
codex mcp add cc-in-codex -- node /absolute/path/to/cc-in-codex/dist/index.js
```
View configuration:
```bash
codex mcp get cc-in-codex
```
If `claude` is not in PATH, specify:
```bash
CC_IN_CODEX_CLAUDE_PATH=/absolute/path/to/claude
```
After registration, restart Codex to ensure the tool list is refreshed. After restarting, Codex should see tools like `companion_send`, `companion_resume`, `companion_tui_open`, and `companion_tui_resume`.
## Quick start: New project
In a brand-new project, it is recommended to use it like this:
1. User tells Codex: “This project uses cc-in-codex.”
2. Codex calls `companion_init_project`.
3. `cc-in-codex` creates:
- `AGENTS.md`
- `CLAUDE.md`
4. Codex subsequently uses `companion_send` to assign tasks to Claude Code.
5. When the user wants to see the real-time UI, Codex calls `companion_tui_open`, and the user attaches to the right-terminal.
Initialize project:
```json
{
"cwd": "/absolute/path/to/project"
}
```
The generated `AGENTS.md` is the shared project memory for Codex and Claude Code. `CLAUDE.md` reminds Claude Code to read `AGENTS.md` first.
The reason for this is that project instructions should be written in the repository rather than repeated in every prompt.
## Continuing an existing Claude Code project
If a project has already used Claude Code, you usually do not want to lose the existing session context. `cc-in-codex` supports two recovery methods.
### Precise recovery of session id
If you know Claude Code's session id, you can let the SDK backend bind it:
```json
{
"cwd": "/absolute/path/to/project",
"backend": "sdk",
"sessionId": "00000000-0000-0000-0000-000000000000"
}
```
After that, Codex uses `companion_send` to resume this Claude Code session.
TUI can also precisely recover:
```json
{
"cwd": "/absolute/path/to/project",
"sessionId": "00000000-0000-0000-0000-000000000000"
}
```
This is equivalent to starting in the project:
```bash
claude --resume 00000000-0000-0000-0000-000000000000
```
### Continuing the current directory's recent Claude Code conversation
If you do not know the session id but want to continue the recent Claude Code conversation of the project, use TUI:
```json
{
"cwd": "/absolute/path/to/project",
"continueLatest": true
}
```
This is equivalent to:
```bash
claude --continue
```
Note: SDK backend requires a clear session id. `--continue` is the semantics of Claude Code CLI/TUI, currently responsible for the TUI backend.
### Avoid mistakenly replacing the TUI being watched
If the project already has a cc-in-codex TUI pane running, resume will not replace it by default. You will get an explicit error, prompting that a tmux session already exists.
If you explicitly want to close the existing pane and start the recovered session, pass:
```json
{
"cwd": "/absolute/path/to/project",
"continueLatest": true,
"replaceTui": true
}
```
This protection is important: the Claude Code session seen by the user on the right-terminal must be consistent with the session operated by Codex.
## Visible TUI mode
Open TUI:
```json
{
"cwd": "/absolute/path/to/project"
}
```
The tool returns something like:
```bash
tmux attach -t ccic-my-project-abc123def0
```
Running this command in Codex's right-terminal allows you to see the native Claude Code TUI.
Common tmux operations:
```text
Ctrl-b d detach, exit observation but do not close Claude Code
Ctrl-b [ enter scrollback
q exit scrollback
```
When Codex sends tasks to TUI, it will paste the prompt into Claude Code CLI and press Enter. Users will see input, output, tool calls, and Claude Code's interaction status in real-time in the TUI.
### TUI prompt layering
The TUI backend has an important UX design: bootstrap and task separation.
The first time a task is sent to a new TUI pane, `cc-in-codex` will send a bootstrap to establish the companion role:
- Codex is the lead agent.
- Claude Code is the execution companion.
- Current working directory.
- Permission policy.
- Reporting format.
- Do not ask users directly; report blockers to Codex.
Subsequent tasks only send:
```text
Task: ...
```
This avoids putting a lot of identity descriptions into the Claude Code context every round, while the new pane can still be correctly initialized.
When `/clear` or `/compact` is executed, the next round will automatically re-bootstrap.
### Raw input
Some inputs should not be packaged into tasks by cc-in-codex, such as slash commands or control keys. Use `companion_tui_raw`:
```json
{
"cwd": "/absolute/path/to/project",
"text": "/status"
}
```
Send Escape:
```json
{
"cwd": "/absolute/path/to/project",
"keys": ["Escape"],
"enter": false
}
```
Send Ctrl-C:
```json
{
"cwd": "/absolute/path/to/project",
"keys": ["C-c"],
"enter": false
}
```
Raw input is suitable for:
- `/status`
- `/help`
- `/clear`
- `/compact`
- `Escape`
- `C-c`
- Content that users explicitly require to be input raw
Long task prompts and longer raw inputs will be pasted through the tmux buffer and dynamically wait before pressing Enter. This is more suitable for long commands, long slash commands, or multi-line task descriptions.
## How Codex should call
This MCP server is for Codex. The ideal behavior is:
- User says “Use Claude Code to do this implementation,” Codex calls `companion_send`.
- User says “Make a longer implementation/refactor/audit,” Codex calls `companion_start`, then uses the returned `eventCursor` to call `companion_wait` for progress.
- User says “Open visible TUI,” Codex calls `companion_tui_open`.
- User says “Continue my original Claude Code context,” Codex first judges if there is a session id; if not, use TUI `continueLatest`.
- User says “Look at what Claude Code is doing on the right,” Codex calls `companion_tui_screen`.
- User says “Stop it,” Codex calls `companion_cancel` or TUI raw `C-c`.
- User says “Should we compact now,” Codex first calls `companion_tui_compact_check`, then decides whether to `companion_tui_compact`.
Codex should not:
- Paste the entire repository summary to Claude Code.
- Repeat long identity descriptions every round.
- Compact without checking checkpoints.
- Blindly trust Claude Code's output without review.
- Silently replace another session when the user is watching the TUI.
## MCP tool descriptions
### General tools
| Tool | Purpose |
| --- | --- |
| `companion_open` | Open or restore the current project companion, do not send tasks |
| `companion_resume` | Bind an existing Claude Code session or trigger TUI continue/resume |
| `companion_send` | Send short tasks and wait for completion |
| `companion_start` | Start long tasks, immediately return run id |
| `companion_wait` | Wait for new events, completion, or timeout of long tasks, used for `start → wait` flow monitoring |
| `companion_recent` | View recent events |
| `companion_status` | View current companion status |
| `companion_result` | View recent results and resume commands |
| `companion_cancel` | Stop current running |
| `companion_reset` | Forget the companion binding of the cwd |
| `companion_init_project` | Create shared project instruction files |
### TUI Tools
| Tool | Purpose |
| --- | --- |
| `companion_tui_open` | Create or restore a visible Claude Code TUI |
| `companion_tui_resume` | Open a visible TUI with `--resume` or `--continue` |
| `companion_tui_send` | Send a task to a visible TUI |
| `companion_tui_raw` | Send raw text or keys to the TUI |
| `companion_tui_screen` | Capture the current TUI screen text |
| `companion_tui_compact_check` | Check if it's suitable for compacting |
| `companion_tui_compact` | Send a `/compact` with protection instructions |
## Context, Resume, and Compact
### Does Claude Code preserve context on its own?
Yes, Claude Code saves recoverable sessions locally. `cc-in-codex` doesn't need to copy Claude Code's entire conversation history.
However, there's a boundary to clarify:
Codex can't naturally see Claude Code's complete history. Codex sees content from:
- Structured results returned by MCP tools.
- Event summaries saved by `companion_recent`.
- Current TUI screen captured by `companion_tui_screen`.
- `AGENTS.md` / `CLAUDE.md` / project files.
- Status line snapshots.
So, `cc-in-codex` is designed as:
- Claude Code's complete context is maintained by Claude Code itself.
- Codex's current judgment relies on high-signal states exposed by MCP.
- Important project knowledge should be in `AGENTS.md`, not just in some terminal scroll records.
### Purpose of Resume
Resume isn't about copying all history to Codex, but to let Claude Code continue the original context.
When Codex calls `companion_send`, the SDK backend uses the bound session ID to resume. The TUI backend can start `claude --resume` or `claude --continue`.
### Principles of Compact
Compact shouldn't be too frequent. A good compact should happen when:
- The current task has reported completion.
- Test or verification results are clear.
- There are no running commands.
- No approval popups or incomplete interactions.
- Context pressure is medium to high, and the benefit of retaining a complete transcript decreases.
Recommended process:
1. Call `companion_tui_compact_check`.
2. Check `checkpointReady` and `recommendation`.
3. Only compact if recommended as `compact_now` or explicitly requested by the user.
`companion_tui_compact` sends a `/compact` with protection instructions, requiring Claude Code to retain:
- Companion division of labor.
- Current project status.
- Recent key decisions.
- Incomplete tasks.
- Verification status.
- Blockers.
- User-visible workflow assumptions.
## Status Line and Context Pressure Monitoring
Claude Code supports statusLine. After configuration, Claude Code sends a JSON with `context_window` to commands. `cc-in-codex` saves these snapshots for more accurate context pressure judgment.
Add the following to Claude Code settings:
```json
{
"statusLine": {
"type": "command",
"command": "node /absolute/path/to/cc-in-codex/dist/index.js statusline"
}
}
```
Snapshots are written to:
```text
~/.cc-in-codex/statusline/
```
`companion_tui_compact_check` prioritizes using the actual `context_window.used_percentage` from statusLine. If not configured, it falls back to heuristic judgments based on screen length and event count.
Current pressure level logic:
- `used_percentage >= 75`: high
- `used_percentage >= 60`: medium
- Others: low
If no statusLine:
- Increase pressure level if there are many events, long screen content, or high character count.
## Security and Permission Model
The default strategy is `balanced`. Note that SDK backend and TUI backend have different security boundaries.
The SDK backend uses Claude Agent SDK's tool permission callback for interception, allowing for stronger tool-level policies. The TUI backend runs the native Claude Code CLI, and `cc-in-codex` is responsible for visible startup, sending prompts, sending raw keys, reading screens, and interrupting, but can't intercept every tool call at the MCP level.
`maxBudgetUsd` is an optional loss limit parameter for SDK single-round calls, not persisted as a default project configuration. Normal personal workflows for Claude Max/subscription suggest omitting it, relying on `maxRuntimeMs`, `stallTimeoutMs`, TUI visible monitoring, and manual `C-c` loss.
### Mode
| Mode | Meaning |
| --- | --- |
| `read-only` | SDK backend blocks mutating tools; TUI backend writes read-only intent to companion prompt, but still relies on Claude Code CLI permissions and manual monitoring |
| `workspace-write` | Allows normal engineering modifications within the project directory |
### Permission Policy
| Policy | Meaning |
| --- | --- |
| `balanced` | SDK default policy, allowing local project work while blocking detected paths outside cwd |
| `strict` | SDK only allows `allowedTools` |
| `trusted` | More trust in Claude Code and local environment |
| `bypass` | Explicitly skips Claude Code permission confirmation; SDK uses `bypassPermissions`, TUI creates new processes with `--dangerously-skip-permissions` |
SDK read-only mode blocks:
- `Bash`
- `Edit`
- `MultiEdit`
- `Write`
- `NotebookEdit`
SDK `balanced` checks common path parameters and rejects if outside cwd.
TUI backend security strategy is closer to "visible remote control":
- Users can attach to the same `tmux` pane for real-time viewing.
- Codex can check status with `companion_tui_screen`.
- If a dangerous command, error loop, permission loop, or user request to stop occurs, Codex can send `C-c`.
- TUI internal tool permissions are still determined by Claude Code CLI, project settings, user confirmation, and local environment.
Note that no local automation tool can replace user and Codex review. For high-risk commands, cross-directory writes, deletion operations, or publish operations, Codex should maintain explicit review.
## Local State and Privacy
`cc-in-codex` uses local Claude Code login state, introducing no new cloud accounts.
Local state location:
```text
~/.cc-in-codex/state.json
~/.cc-in-codex/statusline/
```
`state.json` saves:
- cwd to companion binding.
- Claude Code session ID.
- tmux session name.
- Attach command.
- Recent event summaries.
- Recent results.
- Configuration items.
It doesn't attempt to save Claude Code's complete transcript. Complete Claude Code sessions are maintained by Claude Code itself.
## CLI Usage
`cc-in-codex` defaults to starting as an MCP server from stdio.
### Status Line
Claude Code statusLine invocation:
```bash
cc-in-codex statusline
```
Usually not executed manually.
### Attach
Open or attach to a project's TUI:
```bash
cc-in-codex attach /absolute/path/to/project
```
Continue the project's recent Claude Code conversation:
```bash
cc-in-codex attach /absolute/path/to/project --continue
```
Resume a specified session:
```bash
cc-in-codex attach /absolute/path/to/project --resume <session-id>
```
Close an existing `cc-in-codex` tmux pane and restart:
```bash
cc-in-codex attach /absolute/path/to/project --continue --replace
```
View help:
```bash
cc-in-codex attach --help
```
## Development and Pre-Release Checks
Run the following before release:
```bash
npm run typecheck
npm run build
npm run smoke
npm pack --dry-run
```
Additional checks recommended:
```bash
npm audit --audit-level=moderate
git status --short
```
`npm pack --dry-run` should only include:
- `dist/`
- `scripts/smoke.mjs`
- `README.md`
- `README.en.md`
- `LICENSE`
- `package.json`
Don't publish `node_modules/`, local state, logs, temporary packages, or test residuals.
Current `.gitignore` already ignores:
```text
node_modules/
dist/
.DS_Store
.cc-in-codex/
*.log
```
## Frequently Asked Questions
### Will this tool affect my regular use of Claude Code?
No, it uses your existing `claude` command and Claude Code local session. You can still open Claude Code CLI normally.
### Can I resume a conversation created by cc-in-codex in Claude Code CLI?
Yes, `companion_status` and `companion_result` return:
```bash
claude --resume <session-id>
```
You can execute this command in the terminal.
### Can Codex see Claude Code's complete history?
Not naturally. Codex can only see MCP server-exposed results, summaries, screen captures, and project files. Claude Code's complete context is retained by Claude Code itself.
### Is TUI real-time synchronized?
Yes, in TUI mode, Claude Code runs in `tmux`. When you attach to the same `tmux` session, you'll see the same native Claude Code interface. When Codex sends prompts, input appears in this interface.
### Can I type in TUI myself?
Yes, you and Codex operate the same Claude Code TUI. Note that if you manually change the state, Codex may need to re-confirm via `companion_tui_screen` or `companion_status`.
### Why doesn't TUI send wait for task completion?
Because Claude Code TUI is a full-screen interactive interface, there's currently no stable structured signal proving "task completed". `cc-in-codex` chooses conservatively: responsible for sending, monitoring, screenshot, and interrupting, but doesn't pretend to perfectly parse TUI state.
### Are SDK and TUI the same process?
No, SDK backend and TUI backend are different call paths, but they can connect to the same session context via Claude Code session ID. TUI can be used for observation/takeover, while SDK is suitable for structured background tasks.
### Why are AGENTS.md and CLAUDE.md needed?
Because long-term instructions should go into the repository, not repeated through prompts. `AGENTS.md` is a shared project memory for Codex and Claude Code, and `CLAUDE.md` points to it.
### Can I use without tmux?
You can use the SDK backend. Only the TUI backend requires `tmux`.
### Is statusLine necessary?
No, but with statusLine, compact checks can see more accurate context window pressure.
## Current Boundaries
This is a locally prioritized developer tool, intentionally kept simple.
Known boundaries:
- TUI backend doesn't guarantee automatic task completion judgment.
- SDK backend's `--continue` semantics require a clear session ID; recent session continuation is handled by the TUI backend.
- statusLine relies on JSON fields provided by Claude Code, which may require adaptation if fields change.
- `balanced` path checks cover common tool parameters but aren't a formal sandbox.
- This project doesn't replace Codex's final review.
## Recommended Workflow
### Ordinary Code Tasks
1. User describes the goal to Codex.
2. Codex breaks down the task.
3. Codex calls `companion_send`.
4. Claude Code modifies code and runs checks.
5. Codex reviews diff and verifies results.
6. Codex reports to the user.
### Complex Implementation Tasks
1. Codex reads key context with SDK or local tools.
2. Codex opens TUI: `companion_tui_open`.
3. User attaches to the right terminal for viewing.
4. Codex sends high-quality tasks with `companion_tui_send`.
5. Codex periodically checks status with `companion_tui_screen`.
6. If an error loop or dangerous command occurs, Codex uses `C-c` to stop loss.
7. After task completion, Codex reviews code and runs final checks.
### Long-Term Projects
1. Initialize `AGENTS.md` and `CLAUDE.md`.
2. Write stable project knowledge into `AGENTS.md`.
3. Let Claude Code companion continuously work in the same cwd.
4. Compact before high pressure at checkpoints.
5. Manually take over if necessary with `claude --resume <session-id>`.
## Open-Source License
MIT. See [LICENSE](./LICENSE).
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available