雙 agent 編排：Claude 主腦（思考） + OpenAI Codex 手（執行），用 Notion 當任務佇列 + inbox 反向通道
Dual-agent orchestration: Claude (main brain) + OpenAI Codex (worker hand) glued by Notion + inbox notifications
重活不該綁住主對話。這是把工作交給 Codex 跑、結果自動回傳的連結層。
Heavy execution shouldn't bloat your Claude conversation.
This is the glue layer that hands work off to Codex and pipes the result back automatically.
中文：你用 Claude Code 當思考夥伴，但重活（下載 / 爬資料 / batch ffmpeg / video-breakdown / 多步驟自動化）一跑就吃 context、把對話拖慢。你裝了 OpenAI Codex CLI，但沒有乾淨的方式委派任務給它。這個 repo 補上中間那條橋。
English: You're using Claude Code as a thinking partner, but heavy work (download / scrape / batch-process / video-breakdown / multi-step automation) bloats your context and slows the conversation. You also have OpenAI Codex CLI installed but no clean way to delegate to it.
| 元件 / Component | 角色 / Role |
|---|---|
| Notion DB | 任務佇列 + 狀態追蹤 / task queue + status tracking |
wake_agent.sh |
從主腦即時觸發 / instant trigger from Claude main brain |
run_loop.sh |
launchd / systemd 排程 30 分鐘保險網 / safety-net cron |
CODEX_LOOP_PROMPT.md |
worker 常駐指令（載入 baseline → 撿任務 → 跑 → 寫 RESULT.md → 通知）/ standing orders |
| Inbox + hook | 反向通道，結果自動注入主腦下次 prompt / reverse channel auto-inject |
一人事業跑 8+ 部門 stress-test 過。邏輯本身通用，只有 CONTEXT 檔需要客製。
Built and stress-tested on a one-person business. The pattern is universal; only CONTEXT files are personal.
┌─────────────────────┐ ┌────────────────────────┐
│ Claude main brain │ │ Codex worker │
│ (thinking layer) │ │ (execution layer) │
└──────────┬──────────┘ └────────────┬───────────┘
│ │
│ 1. create row │
▼ │
┌────────────────┐ │
│ Notion DB │ ◄──── 2. pick row (status=Pending) ┤
│ Agent Tasks │ │
└───────┬────────┘ │
│ │
│ 3. wake_agent.sh │
├──────────────────────────────────────────────►
│ │
│ │ 4. run task
│ │ write RESULT.md
│ │ write to inbox
│ │
┌───────▼────────┐ │
│ Inbox dir │ ◄────────── 5. notify ────────────┤
│ (file watch) │ │
└───────┬────────┘ │
│ │
│ 6. hook injects to Claude prompt │
▼ │
┌────────────────┐ │
│ Claude reads │ │
│ RESULT.md │ │
│ → triage user │ │
└────────────────┘ │
為什麼雙 agent？ 單 agent 思考 + 執行混在一起會膨脹。Codex 跑 --dangerously-bypass-approvals-and-sandbox 跳過 OS 同意彈窗 → 安全靠 prompt 內紅線。Claude 保持輕量對話。
Why dual-agent? Single-agent gets bloated when you mix thinking + execution. Codex skips OS approval prompts so safety lives in the prompt. Claude stays cheap, fast, and conversational.
- Install dependencies (codex CLI, Claude Code, jq, gh — see
docs/install.md) - Clone + setup:
git clone https://github.com/<you>/claude-codex-bridge.git ~/.dual-agent cd ~/.dual-agent cp .env.example .env # fill in tokens chmod 600 .env bash install.sh # creates dirs + copies scripts
- Build your Notion DB following
docs/notion-schema.md, put the data source ID in.env - Customize templates (
install.shalready copied them to~/.dual-agent/agent-runner/— edit them in place):~/.dual-agent/agent-runner/CONTEXT/*.md(5 files: company / tone / customers / output / user)~/.dual-agent/agent-runner/ANTI-PATTERNS.md(10 red lines — keep all, customize wording)
- Run preflight + first test:
bash preflight.sh # verify codex / Notion / paths bash examples/create_test_task.sh # creates "hello world" task in Notion bash scripts/wake_agent.sh # triggers codex to pick it up ls ~/codex-output/ # see the RESULT.md
claude-codex-bridge/
├── README.md — this file
├── LICENSE (MIT)
├── .env.example — required env vars
├── install.sh — creates ~/.dual-agent dirs + copies scripts
├── preflight.sh — verifies setup before first run
├── docs/
│ ├── architecture.md — why dual-agent, why this design
│ ├── workflow.md — 4-step call path (create row → wake → run → inbox)
│ ├── notion-schema.md — DB schema spec (column names, types, options)
│ ├── install.md — dependency install (codex / Claude Code / jq / gh)
│ ├── anti-patterns.md — red-line philosophy
│ └── retro.md — why this exists (real-world story)
├── scripts/
│ ├── wake_agent.sh — instant trigger
│ ├── run_loop.sh — single-round loop (launchd entry point)
│ └── inbox_drain.sh — formats inbox for Claude hook injection
├── templates/
│ ├── CONTEXT/ — 5 baseline files (replace with yours)
│ ├── ANTI-PATTERNS.md.template
│ └── CODEX_LOOP_PROMPT.md.template
├── examples/
│ ├── example-task-spec.md
│ └── create_test_task.sh
└── hooks/
└── claude-inbox-hook.example.json — settings.json snippet
- ❌ 不是 Claude Code 外掛 / not a plugin（沒 MCP server / no MCP server）
- ❌ 不是 OpenAI Codex extension（不改 codex 內部 / no codex internals）
- ❌ 不是 獨立 agent 框架 / not a standalone agent framework（LangGraph / AutoGen / Crew 都比這重）
這是兩個既有 CLI 的連結層。~200 行 shell + Notion + prompt 規約，就這樣。
This is the glue layer between two existing CLIs. ~200 lines of shell + Notion + a prompt convention. That's the whole thing.
- ✅ macOS 14+ (Apple Silicon) 穩定 / stable
- ✅ Codex CLI v0.128+ / Claude Code v2.x 測試過 / tested
- 🟢 Linux: 看
docs/linux.md（systemd timer 替代 launchd） ⚠️ Windows: 沒測過 / untested
🎬 30-second flow demo coming soon. Recording in progress — will update when published.
MIT. See LICENSE.
Built by @keng1304. Pattern inspired by Stanford's "Beyond LLM" course (Centaur vs Cyborg automation modes) and OpenAI's codex /goal Ralph Wiggum loop.
If this saves you 10 hours a week, ⭐ the repo and tag me when you ship something with it.