Kevin7QiKevin7Qi/codex-collab/CLAUDE.md

codex-collab

CLAUDE.md99 starsChanged 9 months agoMITView on GitHub

CLI tool for Claude + Codex collaboration via the Codex app server JSON-RPC protocol. Stack: TypeScript, Bun, OpenAI Codex CLI (app server protocol)

In this repository2 other files it gives its agents.
- claude-collabSkill
- codex-collabSkill

The file

We split this CLAUDE.md into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Run ledger tracks per-invocation state (status, timing, output) under runs/
line 59

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

CLAUDE.md

codex-collab

CLI tool for Claude + Codex collaboration via the Codex app server JSON-RPC protocol.

Stack: TypeScript, Bun, OpenAI Codex CLI (app server protocol)

Development

./install.sh --dev    # symlink for live iteration
bun run src/cli.ts --help
codex-collab health
bun run test:ci       # what CI runs, the way it runs it (no claude on PATH) — before every push

Key Files

File	Purpose
`src/cli.ts`	CLI router, argument parsing, signal handlers
`src/client.ts`	JSON-RPC client for Codex app server (spawn, handshake, request routing)
`src/commands/`	CLI command handlers (run, review, threads, kill, config, approve; `send` with its detached receiver, `task`/`tasks`, `peers` with `peers stop` and the reaper entry point)
`src/threads.ts`	Thread index, run ledger, short ID mapping
`src/turns.ts`	Turn lifecycle (runTurn, runReview), event wiring
`src/events.ts`	Event dispatcher (progress lines, log writer, output accumulator)
`src/approvals.ts`	Approval handler abstraction (auto-approve, interactive IPC)
`src/questions.ts`	Ask-channel mailbox (Codex asks mid-turn via `ask`, fail-open on timeout; markers, temp-space mailbox)
`src/types.ts`	Protocol types (JSON-RPC, threads, turns, items, approvals)
`src/config.ts`	Configuration constants, workspace resolution
`src/broker.ts`	Shared app-server lifecycle (connection pooling)
`src/peer.ts`	Native peer messaging (Claude session-registry entries, messaging sockets, consult bridge, per-thread peers)
`src/claude-sessions.ts`	Codex's side of peer messaging: the Claude Code sessions `peers` lists and `send` reaches, sessions `send` starts (`claude --bg`), their records and reaper
`src/claude-transcript.ts`	Reads a Claude Code session's own transcript for why a turn failed (API errors); fails open, undocumented format
`src/claude-tasks.ts`	Task records for `send`: one per message, written by a detached receiver, read by `task status\|wait\|result` and `tasks`
`src/broker-client.ts`	Socket-based client for connecting to the broker server
`src/shared-server.ts`	Attach to Codex's shared app-server over its control socket (WebSocket client, attach/spawn decision)
`src/models.ts`	Model and effort defaults shared by the CLI and the peer
`src/broker-server.ts`	Detached broker server process (multiplexes JSON-RPC between clients and app-server)
`src/process.ts`	Process spawn/lifecycle utilities
`src/lock.ts`	Advisory file locks (sync/async, single-winner stale breaking)
`src/git.ts`	Git operations (default-branch detection for reviews)
`src/skill.ts`	Installed-skill rendering for both skills (embedded SKILL.md sources), the opt-in Codex exec-policy rule (`CODEX_RULES_SOURCE`), drift detection, unified diff
`src/update.ts`	Release checking, update notices (`skill sync` / `update` commands live in `src/commands/update.ts`)
`SKILL.md`	Claude Code skill definition
`codex-skill/SKILL.md`	Codex-side skill (`claude-collab`): how Codex reaches Claude Code sessions (`peers`, `send`, `task`, `peers stop`)

Dependencies

Runtime: Bun, codex CLI (codex app-server)

Architecture Notes

Communicates with Codex via the codex app-server JSON-RPC protocol: over Codex's control socket ($CODEX_HOME/app-server-control/app-server-control.sock, WebSocket) when a shared app-server is running, else over stdio to a private child (config server auto|shared|private)
Codex 0.145+ allows one writer per thread (flock in ~/.codex/thread-writer-locks/), released only when the holding process unloads the thread or exits. The broker unsubscribes idle threads it does not keep; Codex unloads an unsubscribed idle thread after a delay (observed ~7 min on 0.153.4 — -c thread_unload_delay_secs did not shorten it) and releases the lock then. A thread held by another process is reported as exit code 8
Per-workspace state under ~/.codex-collab/workspaces/{slug}-{hash}/ (threads, logs, runs, approvals, kill signals, PIDs, tasks)
User defaults stored in ~/.codex-collab/config.json (model, reasoning, sandbox, approval, timeout)
Broker manages one app-server connection per workspace via Unix socket / named pipe with thread-scoped routing: parallel runs on different threads multiplex over it; same-thread contention is refused (-32001) — a second app-server could no longer take the thread anyway — and only an unavailable broker falls back to a direct connection
Short IDs are 8-char hex, support prefix resolution
Run ledger tracks per-invocation state (status, timing, output) under runs/
Bun is the TypeScript runtime — never use npm/yarn/pnpm for running
Skill installed to ~/.claude/skills/codex-collab/ via install.sh (build + copy; --dev for symlinks)
Contract tests against live codex/claude binaries live in contracts/ — opt-in via CODEX_COLLAB_CONTRACTS=1 bun test contracts/ (skipped by default; spends a few trivial model turns and writes probe entries into the real session registry with cleanup)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free