tmux-agents

English | 简体中文

Your sub agents shouldn't disappear when the task ends. Built-in sub agents run out of sight. You get a summary at the end, and the work behind it is gone.

tmux-agents runs each Claude or Codex sub agent in its own tmux window instead. Watch its work in a live preview, or switch in to give direction.

Agents send tasks and updates to each other. Their panes stay until you close them, and their conversations remain afterward: in Codex you can find them in codex resume, in Claude in claude --resume.

See the work. Keep the history. Pick it up again.

• Real sessions, not black boxes. Every sub agent is a full Claude or Codex session with its whole history on screen. Approve a prompt, ask a follow-up, or correct it mid-task.
• One glance to know who needs you. A line above your status bar shows each sub agent working, done, waiting for permission or waiting for you.
• Agents that talk to each other. Tell Claude "connect codex and have it review this diff", and the reply comes back to Claude as a new message.
• Stays out of your way. Sub agents live in a hidden session per project. Nothing is added to your layout, and a message never lands while you're typing in that pane.
• Just tmux and bash. No server to run: the state lives on the tmux panes.

Screenshots

Claude asks Codex for a review, and the reply comes back as a new message.

prefix + a lists your sub agents with a live preview. Open one in a popup to answer it or give direction.

Status bar: a line above your status bar keeps count, and turns red or amber when an agent needs you:

      ⠹ auth-review: reading src/auth.ts  │  api ⠹ 2 ✓ 1 · blog ⠹ 1

Design notes, protocol details and known pitfalls: DESIGN.md.

Install

The easy way: ask Claude Code or Codex to do it.

Install tmux-agents for me by following https://github.com/TheClooneyCollection/tmux-agents/blob/main/skills/tmux-agents-setup/SKILL.md

It checks what you have, runs the installer, shows you each config change before making it, and then walks you through a quick start. Later, say "tmux-agents quick start" to any agent to take the tour again.

For user-level skill installation, use the skills CLI below or ./install.sh in the manual steps. After using the CLI, tell your agent "set up tmux-agents" to install the commands and configure tmux:

npx skills add TheClooneyCollection/tmux-agents -g

To list the available skills without installing them, add --list. This previews discovery only; ./install.sh --dry-run previews the checkout installer.

By hand

Needs tmux 3.2+ and bash. The agent list (prefix + a) also requires fzf: install it with brew install fzf (macOS) or apt install fzf (Debian/Ubuntu). Other commands work without it.

git clone https://github.com/TheClooneyCollection/tmux-agents.git
cd tmux-agents
./install.sh            # --dry-run to see what it does first

install.sh:

• links the tmux-* commands into ~/.local/bin (BIN_DIR to change)
• links the tmux-agents, tmux-agents-setup, tmux-agents-perf and agent-chain skills into ~/.claude/skills/ and your Codex home
• copies the Codex rules (Codex skips symlinked .rules files)
• preserves real files and directories at link destinations unless --force backs them up as DEST.bak.YYYYmmddHHMMSS before linking

Then add these to your own config (install.sh prints them with your paths):

tmux	source-file ~/path/to/tmux-agents/tmux/tmux-agents.conf in ~/.tmux.conf, then reload
PATH	~/.local/bin
Claude	the allow rules from integrations/claude/settings.json, into ~/.claude/settings.json
Codex (optional)	identity-only wrapper: integrations/fish/functions/ or integrations/sh/codex.sh

What each one is for

• tmux: prefix + a (agents), prefix + A (connect), the sub agent chip, and hooks for border refresh, bell alerts and queued messages. If you linked the commands somewhere other than ~/.local/bin, put %hidden TMUX_AGENTS_BIN="/that/dir" before the source-file line.
• Claude: agents can message, peek, spawn, report, rename themselves or descendants, and close their own sub agents without prompting. tmux-connect (without --from), tmux-disconnect, plain tmux-dismiss and plain tmux-rename stay yours and still prompt.
• Codex: use tmux-agents start codex (or a configured profile) for identity pins and turn tracking. The optional wrapper only pins identity when you type codex directly; it does not add tracking. Copy the fish functions into ~/.config/fish/functions/, or source the sh file from ~/.bashrc / ~/.zshrc. Launch hooks are passed per process; no global Claude or Codex hook configuration is changed.
• Optional: tell your agents to use tmux-spawn for every sub agent, in CLAUDE.md / AGENTS.md. The skill explains how.

Update the actual installed checkout: on a branch, use git pull --ff-only; for a detached/tag install, use git fetch --tags and git checkout <new-tag> with your chosen tag. Then re-run ./install.sh there to refresh rules and rebuild skill links, including links to the old skill folders.

Using more than one Codex account? See the guide.

If popups feel slow

tmux-agents is fast (a list build takes about 0.1s), but tmux runs every popup and every new agent's window through your default-shell, which reads its config first. Check:

tmux show -gv default-shell
time fish -c true        # use your shell; compare with --no-config / --norc / -f

Hundreds of milliseconds there are paid on every prefix + a (the list itself draws its prompt first and loads the rows right after). See docs/performance.md for the fix, or ask your agent to "find out why tmux-agents is slow" (the tmux-agents-perf skill).

Configuration

See Configuration for tmux settings, defaults and environment overrides.

Quick start

1. Run tmux-agents start claude or tmux-agents start codex in tmux. Tell it: "use tmux-agents to open a Codex to your right". It uses tmux-spawn --split to open a connected agent beside itself.
2. Tell your original agent: "ask the Codex you just opened to review this diff". The request lands in Codex's pane, and the reply comes back to your original agent.
3. Tell your original agent: "spawn a sub agent to add tests for the parser". It runs in a hidden window, and a line above your status bar shows how it's doing.
4. Press prefix + a to watch it. Enter opens it in a popup, prefix + d goes back.
5. Tell your original agent: "start the chain". It becomes the main agent you talk to, with a secondary that coordinates and a Codex worker that implements, side by side in your window (the agent-chain skill).

From a shell, tmux-agents start chain [DIR] [--worker AGENT] opens a new window in DIR (default: the current directory), named after its basename, and starts Claude with the initial prompt "start the chain" and your worker choice. For another independent agent, split the pane manually and run tmux-agents start codex in the new pane, then ask either agent to connect them. See Starting agents for names, profiles, arguments and exit behavior.

Or let your agent show you: say "tmux-agents quick start".

Keys

Key
prefix + a	The agent list, with a live preview
prefix + A	Connect this pane to another one (ctrl-a: any window)
prefix + d	In a popup: back to the list. In the list: close it

The list opens on this window and its descendants, with sub agents and members needing you pinned from every window.

In the list: enter open · ctrl-o jump there · ctrl-x dismiss · ctrl-d close all finished · ctrl-a all panes / sub agents · ctrl-t this window / all windows

Long-lived team members use tmux-spawn --member. They stay out of the default sub-agent list, ordinary chip counts and ctrl-d / --done cleanup. ctrl-a shows them as member of <owner>; attention still pins them. Explicit dismissal still closes their subtree, and reopening preserves membership.

Closed sub agents and members stay in a closed section at the bottom for 7 days: enter reopens one with its whole conversation. Or ask its parent to reopen it.

Status: ⠹ working · ○ idle (no task yet) · ✓ done · ⚠ waiting for permission (red) · ◆ needs you (amber) · ✉ message waiting for you to stop typing or scrolling · ✗ exited · - untracked (no worked time; messaging still works)

Commands

Agents run these for you; each takes --help.

Command
tmux-connect	Name this pane and link it to another
tmux-rename	Change an agent's label while keeping its identity, history and links
tmux-ask	Send a message to a connected agent
tmux-spawn	Start a sub agent, or a long-lived --member, hidden or with --split
tmux-agents	The agent list (prefix + a); start launches a tracked agent or chain
tmux-peers, tmux-peek	Show connections; read another pane
tmux-dismiss, tmux-disconnect	Close a sub agent; unlink panes
tmux-agent-report	Report progress for the status line

Live commands still use names; IDs are only needed to select an ambiguous saved conversation. Names are labels: reusing a closed agent's name keeps both histories. The list distinguishes same-named closed agents by time, parent and project; IDs stay out of its rows but can appear in the closed preview. For scripts and agents, tmux-peers --ids and tmux-spawn --list-closed expose IDs; --resume-id ID reopens one exact conversation when --resume NAME is ambiguous.

How messages flow, sub agent details, settings and how it works: the guide.

License

MIT, see LICENSE.