CC Tmux Agents
phuongduyphan/cc-tmux-agents
Orquestre múltiplos agentes de código via tmux com primitivos composáveis
Ver no GitHubAgent orchestrador que permite ao Claude Code delegar tarefas para outros agentes de código (opencode, pi, codex, etc.) via tmux. Controla execução remota, interrupção, verificação de progresso e revisão de resultados, otimizando custos ao usar modelos mais baratos para implementação enquanto Claude foca em planejamento e revisão.
Instalação
npx convez-ai phuongduyphan/cc-tmux-agents1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Delegar implementação para agentes baratos enquanto Claude Code faz revisão
- Controlar múltiplos agentes de IA em paralelo e em sequência
- Executar workflows de coding autônomos ou semi-autônomos com interrupção manual
Veredito

Solução técnica sofisticada para orquestração multi-agente com foco em eficiência de custos. Exige tmux, perl e CLI autenticados dos agentes, mas oferece primitivos composáveis poderosos e funciona localmente ou remoto via SSH.
README
A tradução para o português deste README ainda está na fila.
cc-tmux-agents
Let Claude Code talk to your other coding agents.
Like Claude Code subagents, but the subagents are codex, opencode, pi, etc. Delegate a task, watch it work, send follow-ups, interrupt it, and have Claude review the result. Steer it yourself, or hand the whole thing off and walk away.
https://github.com/user-attachments/assets/824acaf6-e4ba-461c-bed9-cc6775d43233
Why
- Pay top rates only for the thinking. A strong model earns its price on planning and review, which are light on tokens. Implementation is the token-heavy part, so running it on a cheaper agent is where the real savings are, without giving up the decisions.
- Minimal setup, basic primitives, build your own workflows. One mechanism (tmux) drives any agent, no per-vendor API, so a handful of composable primitives (start, check, tell, interrupt, wait, kill) is the whole surface. Steer a run by hand, or compose those primitives into something fully autonomous:
/autopilotis one such workflow, and you can build your own. - Works everywhere, from your laptop to your phone. It's all tmux over SSH. Kick off a run at your desk, then check on it, steer it, or start a new one from your phone.
Quick start
git clone <this-repo> ~/code/cc-tmux-agents
cd ~/code/cc-tmux-agents
./install.sh # all skills; or: ./install.sh --skills "pi opencode autopilot"
./doctor # verify the setup
./doctor --smoke opencode # optional ~30s live end-to-end test
install.sh copies the skills into place (it touches only its own skill folders, so your other skills are left alone). Re-run it after a git pull to refresh them, or pass --link to symlink instead so pulls update them live with no re-run. Then, in Claude Code:
/opencode what is this project about?
That starts a tmux session running opencode, types the task, and (by default) arms a background wait so Claude is pinged the instant the worker finishes.
- tmux (any reasonably modern version; the dispatchers avoid the tmux ≥ 3.2
-eflag) - perl (strips ANSI codes from captured panes; preinstalled on macOS and almost every Linux distro)
- Claude Code as the orchestrator
- The agent CLIs you want to drive, installed and authed (
pi,opencode,codex, cursor'sagent,copilot,droid,agy). Skills for tools you don't have are inert; install only what you use with--skills.
Works on macOS and Linux (the dispatchers are bash, with BSD/GNU fallbacks). On Linux servers, the agent CLIs' own OAuth flows may need a browser, so auth each tool once before relying on the skills.
The installer also creates ~/.config/cc-agents/env (chmod 600). Put the model-provider API keys your workers need there (e.g. ZAI_API_KEY=...). The pi dispatcher sources this file instead of your shell rc, so workers get only those keys, not your whole environment. If the file is absent it falls back to your login shell.
What you can do
| You say | What happens |
|---|---|
/opencode <task> | starts a tmux session running opencode, types the task, arms a backgrounded wait |
| "check opencode" | captures the pane, shows the tail, gives a one-line diagnosis |
| "tell opencode: X" | queues a follow-up into the same session |
| "interrupt opencode" | sends Escape |
| "tell me when it's done" | the default for plain delegation; Claude is pinged on completion |
| "kill opencode" | tears the session down |
/autopilot opencode <task> | fully autonomous: checkpoints every 10 min, course-corrects, final review, decision log |
Semi-auto: delegate, then watch and steer. You can always look over an agent's shoulder with tmux attach -t cc-opencode (detach with ctrl-b d), from any machine that can SSH in.
Fully auto: /autopilot <agent> <task> hands the whole job to Claude. It arms two wake sources, checkpoints the worker every 10 minutes (interrupt, read progress, course-correct), breaks thinking loops, ground-truths progress against the actual diff, reviews the result, and logs every autonomous decision to /tmp/cc-autopilot-<agent>-decisions.md.
Supported workers: pi, opencode, codex, cursor, copilot, droid, agy (plus claude as a worker when another agent is the boss, see below).
How it works
Every coding agent is just a TUI in a terminal, so the whole integration is a handful of tmux commands against the agent's pane. No per-vendor API, no SDK: if a tool runs in a terminal, Claude can drive it.
| What Claude does | How (tmux) |
|---|---|
| Type the task or a follow-up | send-keys into the pane |
| Read what the agent is doing | capture-pane, with ANSI codes stripped |
| Interrupt a wrong turn | send-keys Escape |
| Start or tear down a run | new-session / kill-session |
| Know the instant it finishes | a per-tool completion hook, falling back to watching the spinner |
A small bash dispatcher (bin/<name>-agent) wraps these into verbs, and a SKILL.md tells Claude which verb to use when. Claude decides what to do; the cheaper model inside the agent does the typing.
Two skill trees let either side be the boss:
skills/→~/.claude/skills(Claude Code as boss): skills invoked as/name.waitruns as a backgrounded command, so the harness pings Claude the moment the worker goes idle. This powers/autopilot.agents-skills/→~/.agents/skills(codex, opencode, or pi as boss): the same dispatchers in the cross-agent format, invoked as$name. These harnesses can't background-and-wake, sowaitruns in the foreground, and there's no/autopilot.
Install both and use whichever boss you're in.
skills/<name>/SKILL.md the contract Claude reads (verbs + rules)
skills/<name>/bin/<name>-agent the tmux dispatcher that implements it
skills/autopilot/ the autonomous orchestrator (wraps the dispatchers)
agents-skills/<name>/ same dispatchers, cross-agent format (codex/opencode/pi as boss)
hooks/ per-tool completion hooks (exact done-detection)
install.sh copies both trees, installs hooks
doctor verifies the setup; optional live smoke test
- Some dispatchers launch their tool with permissions relaxed so unattended runs don't stall: codex defaults to
--dangerously-bypass-approvals-and-sandbox, agy to--dangerously-skip-permissions, copilot to--allow-all, cursor to--force. For codex you can override viaCC_CODEX_ARGS(e.g.CC_CODEX_ARGS="--full-auto"keeps the OS sandbox on and lets the orchestrator answer approval prompts through the pane). - opencode and pi have no OS sandbox at all (their permission prompts are UX, not isolation). For overnight or autonomous runs, prefer a dedicated container or VM holding only the worktree, the toolchain, and the one API key.
- Keep workers in per-task git worktrees without push credentials, and keep secrets out of the workspace.
starttimes out /waitnever fires. The dispatchers detect TUI state with two regexes per tool (READY_RE,BUSY_RE, near the top of eachbin/<name>-agent). Tool UIs change between versions; if a tool updated and broke detection, run<name>-agent captureto see the actual screen text and adjust the regex. PRs welcome.waitreports spinner-fallback instead of the hook. Run./doctor: the hook file or its registration is missing for that tool.- pi starts but errors about API keys. Add the provider key to
~/.config/cc-agents/env. - Session already running. Each skill uses one named session (e.g.
cc-pi). Run<name>-agent stopor use--session <other-name>for parallel sessions.
Why tmux instead of headless mode
Most agent CLIs offer a headless run/exec mode. These skills deliberately drive the interactive TUI over tmux instead:
- You can watch and steer mid-run. Headless is fire-and-forget; tmux lets you or Claude read progress, course-correct, and redirect before a wrong approach burns an hour.
- Interrupting is free. A bad turn is one
Escapeaway, instead of waiting for a headless run to finish or killing the process and losing its state. - One integration for every tool. Every agent has a terminal UI; not every agent has a stable headless API. tmux works for all of them, including tools that ship next month.
- The session is durable and reachable. It lives on the host, so you can detach, close your laptop, and reattach from another machine (or your phone) with the run still going.
- Warm context instead of a cold start each turn. A headless
runspins up a fresh session every invocation, so the agent re-reads everything from scratch. A persistent tmux session stays alive across turns, so the prompt cache stays warm and follow-ups are cheaper and faster.