Ccm Orchestra

**Promotion:** This project is promoted through [linux.do](https://linux.do/).

CCM Orchestra

[中文说明](./README.zh-CN.md)

`ccm-orchestra` is a control plane for running persistent, interactive Claude Code agents in `tmux` and coordinating visible collaboration between code agents through `kitty`. Together they form a paired operating model: `tmux` keeps an agent alive and reusable, `kitty` makes the collaboration visible and relay-capable.

The core loop is simple: start an agent in a detached tmux pane, send it prompts, and read its transcript. Sessions are isolated by working directory, so the same agent name can coexist across repos. Together, the `tmux` layer and the `kitty` layer let Claude Code, Codex, and other code agents work in parallel, hand work back and forth, and stay observable when needed.

The Two Layers

This system has two clearly different layers:

• tmux layer: the real session layer. It keeps interactive Claude Code alive, isolates it by worktree, and lets Codex reuse the same agent over time.
• kitty layer: the visible collaboration layer. It lets humans and other agents see selected sessions, list visible peers, and exchange messages with receipt-friendly envelopes.

If you remember only one thing, remember this:

• tmux and kitty are two distinct capabilities, and they can work independently or together
• the default agent loop is in the tmux layer: start -> send -> read
• the kitty layer makes visible coordination, relay, and human observation possible

The wakeup model is different across the two layers:

• tmux layer is poll-based. ccm read --wait-seconds ... keeps checking Claude transcript output.
• kitty layer is push-based. ccm relay injects a message into another visible tab so that peer can wake up and answer later.

Do not mix those up. Waiting on `read` will not wake another agent tab for you.

Why Interactive Sessions In `tmux` Instead of `claude -p`

The main reason is operational, not philosophic