Skip to content
Back to search

claude-codex-tunnel

Let Claude Code and OpenAI Codex hand work to each other, both ways, and watch them talk live. Cross-model review and delegation with one command.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/astrokhattab--claude-codex-tunnel/badge.svg)](/listings/astrokhattab--claude-codex-tunnel)

HTML

<a href="/listings/astrokhattab--claude-codex-tunnel"><img src="/api/listings/astrokhattab--claude-codex-tunnel/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

You need [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and/or the [Codex CLI](https://github.com/openai/codex), signed in, plus `git` and `python3`.

git clone https://github.com/AstroKhattab/claude-codex-tunnel.git
cd claude-codex-tunnel && ./install.sh

That installs:

| What | Where | |---|---| | the `tunnel` command | `~/.local/bin/tunnel` (a link into this folder, so `git pull` updates it) | | a skill that teaches Claude to delegate to Codex | `~/.claude/skills/claude-codex-tunnel/` | | two Claude subagents: `codex-builder`, `codex-reviewer` | `~/.claude/agents/` | | a skill that teaches Codex to delegate to Claude | `~/.agents/skills/claude-codex-tunnel/` |

The installer asks whether Claude and Codex may run `tunnel` without asking each time (`--trust` / `--no-trust` skip the question). Restart Claude Code and Codex, then check:

tunnel doctor          # is everything installed?
tunnel doctor --live   # do both engines answer? (spends a few tokens)

**Let your AI install it.** Paste this into Claude Code or Codex:

> Clone https://github.com/AstroKhattab/claude-codex-tunnel, run its `install.sh --trust`, > then run `tunnel doctor` and tell me the result.

**One project only, shared with your team:** `./install.sh --project /path/to/repo` puts the skills inside that repo (`.claude/` and `.agents/skills/`) so they travel with git.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 223 lines
  1. # claude-codex-tunnel
  2. **Let Claude Code and OpenAI Codex hand work to each other, and watch them talk.**
  3. Claude writes the code, and Codex reviews it. Or Codex builds, and Claude checks.
  4. One model family checks the other's work. Each side asks the other in plain
  5. language, and you watch the whole conversation live in a terminal window.
  6. A real run, as the conversation window shows it (shortened):
  7. ```
  8. ── Claude → Codex · Review calc.py ─────────────────────────────────────────
  9. 12:22:30 · role review · sandbox read-only
  10. Goal:
  11. Find real bugs in calc.py.
  12. Definition of done:
  13. 1. Every bug is listed with file:line, severity and a concrete fix.
  14. 2. Edge cases: empty list, zero whole.
  15. Codex:
  16. I'll inspect calc.py and check the empty-list and zero-total cases without changing files.
  17. Codex runs $ nl -ba calc.py
  18. exit 0
  19. Codex runs $ python3 -B -c 'import calc ...'
  20. exit 0
  21. average([],) -> ZeroDivisionError: division by zero
  22. average([2, 4],) -> 3.0
  23. percent(5, 0) -> ZeroDivisionError: division by zero
  24. Codex → Claude: REVISE (35s, exit 0)
  25. Found two division-by-zero bugs in calc.py.
  26. Empty lists crash `average`; zero totals crash `percent`.
  27. Reproduced both failures and verified four ordinary cases.
  28. ❓ question: The brief does not specify the desired result for undefined averages ...
  29. report: .tunnel/reports/20261121-232213-review-calc.codex.report.md
  30. ```
  31. - **Works both ways.** Claude → Codex, and Codex → Claude.
  32. - **Real integration.** It starts the other CLI as a real process (`codex exec` or
  33. `claude -p`). No server, no API keys, no MCP setup. It uses the CLIs you already
  34. signed in to, and your existing plans.
  35. - **Live conversation window.** A terminal pops up and shows each brief going out,
  36. every command the other AI runs, and the verdict coming back.
  37. - **Safe by default.** Reviews run read-only. Writing runs are sandboxed. Nothing
  38. commits, pushes, deploys or deletes. Those go back to you as *Needs human approval*.
  39. - **One file is the whole channel.** The task is a markdown brief, and the answer is
  40. a markdown report with a verdict. You can read exactly what was asked and answered.
  41. ## Install (1 minute)
  42. You need [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and/or the
  43. [Codex CLI](https://github.com/openai/codex), signed in, plus `git` and `python3`.
  44. ```bash
  45. git clone https://github.com/AstroKhattab/claude-codex-tunnel.git
  46. cd claude-codex-tunnel && ./install.sh
  47. ```
  48. That installs:
  49. | What | Where |
  50. |---|---|
  51. | the `tunnel` command | `~/.local/bin/tunnel` (a link into this folder, so `git pull` updates it) |
  52. | a skill that teaches Claude to delegate to Codex | `~/.claude/skills/claude-codex-tunnel/` |
  53. | two Claude subagents: `codex-builder`, `codex-reviewer` | `~/.claude/agents/` |
  54. | a skill that teaches Codex to delegate to Claude | `~/.agents/skills/claude-codex-tunnel/` |
  55. The installer asks whether Claude and Codex may run `tunnel` without asking each
  56. time (`--trust` / `--no-trust` skip the question). Restart Claude Code and Codex,
  57. then check:
  58. ```bash
  59. tunnel doctor # is everything installed?
  60. tunnel doctor --live # do both engines answer? (spends a few tokens)
  61. ```
  62. **Let your AI install it.** Paste this into Claude Code or Codex:
  63. > Clone https://github.com/AstroKhattab/claude-codex-tunnel, run its `install.sh --trust`,
  64. > then run `tunnel doctor` and tell me the result.
  65. **One project only, shared with your team:** `./install.sh --project /path/to/repo`
  66. puts the skills inside that repo (`.claude/` and `.agents/skills/`) so they travel with git.
  67. ## Use it
  68. Just ask, in your own words:
  69. | In Claude Code | In Codex |
  70. |---|---|
  71. | "Ask Codex to review my last commit." | "Ask Claude to review my last commit." |
  72. | "Have Codex implement the plan in PLAN.md." | "Have Claude write tests for parser.py." |
  73. | "Get a second opinion from Codex on this bug." | "Get a second opinion from Claude on this design." |
  74. The agent writes a brief, runs `tunnel`, pops up the conversation window, waits,
  75. reads the report and tells you the verdict.
  76. ## How it works
  77. ```
  78. Claude Code Codex CLI
  79. ─────────── ─────────
  80. writes .tunnel/tasks/<id>.task.md (the brief)
  81. runs tunnel codex <brief> --window ─────────────▶ codex exec --sandbox read-only|workspace-write
  82. reads the brief + the tunnel protocol
  83. works in its sandbox
  84. reads .tunnel/reports/<id>.codex.report.md ◀──────── final message = the report
  85. acts on the verdict
  86. ```
  87. Codex → Claude is the same, mirrored: `tunnel claude <brief>` runs `claude -p`.
  88. Everything lives in `.tunnel/` in your project (git-ignored automatically):
  89. ```
  90. .tunnel/
  91. tasks/<id>.task.md the brief (who, role, scope, done-criteria)
  92. reports/<id>.<engine>.report.md the answer, starting with "## Verdict: ..."
  93. logs/<id>.<engine>.jsonl the raw live event stream
  94. threads/<id>.<engine> session id, to resume the same conversation
  95. bus.jsonl append-only record of every run
  96. ```
  97. ### Verdicts
  98. | Verdict | Meaning |
  99. |---|---|
  100. | `DONE` | Work complete, done-criteria met |
  101. | `APPROVE` | Review passed, against named criteria |
  102. | `REVISE` | Fixable issues, each with file:line and a fix |
  103. | `BLOCK` | Cannot proceed: missing information or real risk |
  104. | `FAILED` | The run errored (the report shows the log tail) |
  105. ### The rules every worker follows
  106. 1. The brief is the whole channel. If something is missing, it says `BLOCK`, not guesses.
  107. 2. Scope is a fence: it edits only the files the brief allows.
  108. 3. No commits, pushes, migrations, deploys, deletions or outbound actions.
  109. 4. The author never certifies its own work.
  110. 5. `APPROVE` must name the criterion it checked.
  111. 6. It never weakens or skips a test to get to green.
  112. 7. It does not start another tunnel run unless asked (and nesting is capped).
  113. ## Commands
  114. ```bash
  115. tunnel new <slug> --to codex|claude [--role implement|review|test|research]
  116. tunnel codex <brief> [--window] [--detach] [--resume <id>]
  117. tunnel claude <brief> [--window] [--detach] [--resume <id>]
  118. tunnel watch [--window] # the live conversation, here or in a new window
  119. tunnel wait <run-id> # collect a --detach run
  120. tunnel status # running and recent runs with verdicts
  121. tunnel dispatch [-p N] a.task.md b.task.md # run briefs in dependency waves
  122. tunnel board # a live web board at http://localhost:7799
  123. tunnel doctor [--live]
  124. ```
  125. `review` and `research` briefs run read-only. `implement` and `test` briefs may edit.
  126. ## Settings
  127. | Variable | What it does |
  128. |---|---|
  129. | `TUNNEL_CODEX_MODEL` | Codex model to use, e.g. if your default is not on your plan |
  130. | `TUNNEL_CODEX_EFFORT` | Codex reasoning effort: `low`, `medium`, `high` |
  131. | `TUNNEL_CODEX_PROFILE` | a Codex profile (`$CODEX_HOME/<name>.config.toml`) |
  132. | `TUNNEL_CLAUDE_MODEL` | Claude model, e.g. `sonnet` or `opus` |
  133. | `TUNNEL_CLAUDE_ALLOW` | extra tools for writing Claude runs, e.g. `Bash(npm test:*)` |
  134. | `TUNNEL_NETWORK=1` | let writing Codex runs use the network (off by default) |
  135. | `TUNNEL_WINDOW=1` | always pop up the conversation window |
  136. | `TUNNEL_NOTIFY=0` | no desktop notifications |
  137. | `TUNNEL_MAX_DEPTH` | how deep tunnels may nest (default 2) |
  138. A brief can also add `allow: Bash(npm test:*)` to its frontmatter, so a Claude
  139. worker may run that one command for that one task.
  140. ## Safety model
  141. | Run | Codex | Claude |
  142. |---|---|---|
  143. | review / research | `--sandbox read-only` | read, grep and read-only git only; edits refused |
  144. | implement / test | `--sandbox workspace-write` (this repo + `.tunnel/`), no network | file edits allowed; shell limited to read-only git plus what you `allow` |
  145. - Codex calling Claude: Claude needs the network and its own sign-in, so that one
  146. command runs outside Codex's sandbox. With `--trust`, the installer adds a Codex
  147. rule that allows exactly the `tunnel` command. Without it, Codex asks you first.
  148. - Claude calling Codex: with `--trust`, Claude Code may run `Bash(tunnel:*)`.
  149. - Two writing runs on the same files at once will collide. Use `tunnel dispatch`
  150. with `depends_on:` or separate git worktrees.
  151. ## Troubleshooting
  152. - **Codex says the model is not supported.** Your Codex default model is not on your
  153. plan. Set `TUNNEL_CODEX_MODEL` to one that is, then `tunnel doctor --live`.
  154. - **A run is FAILED with no report.** The report includes the last lines of the
  155. engine log. The full stream is in `.tunnel/logs/`.
  156. - **No window pops up.** On macOS it uses Terminal (or iTerm). On Linux it tries
  157. `x-terminal-emulator`, `gnome-terminal`, `konsole` and `xterm`. You can always
  158. run `tunnel watch` in any terminal.
  159. - **The agent's tool call timed out.** Long runs: `tunnel codex <brief> --detach`,
  160. then `tunnel wait <run-id>` (returns exit 124 while still running; call again).
  161. ## Uninstall
  162. ```bash
  163. ./uninstall.sh # removes the command, skills, subagents and trust entries
  164. ```
  165. Your projects' `.tunnel/` folders are left alone.
  166. ## Tests
  167. ```bash
  168. tests/run.sh # offline: fake codex/claude, throwaway HOME, no credit spent
  169. ```
  170. CI runs it on Ubuntu and macOS (stock bash 3.2).
  171. ## License
  172. MIT. See [LICENSE](LICENSE).
  173. Not affiliated with Anthropic or OpenAI. "Claude" and "Codex" are trademarks of
  174. their owners.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.