wkh237-tmux-team

tmux-team

Coordinate AI agents (Claude, Codex, Gemini) running in tmux panes. Send messages, wait for responses, broadcast to all.

Install

npm install -g tmux-team

Requirements: Node.js >= 18, tmux

Alias: tmt (shorthand for tmux-team)

Quick Start

# 1. Go to working folder and register agents (run inside each agent's pane)
tmt this claude      # registers current pane as "claude"
tmt this codex       # registers current pane as "codex"
# Alternatively, register a specific panel to the session
tmt add gemini 10.1  # register a panel 10.1 as "gemini"

# 2. Talk to agents
tmt talk codex "Review this code"    # waits for response by default

# 4. Update or remove an agent
tmt update codex --pane 2.3
tmt rm codex

# List panels in the session
tmt ls 

Tip: Most AI agents support ! to run bash commands. From inside Claude Code, Codex, or Gemini CLI, you can run !tmt this myname to quickly register that pane.

How scopes work

Registrations live in tmux pane metadata, not in a JSON file you have to track. By default they are scoped to the current workspace — the nearest Git root, or the current folder when you are not inside a Git repo. So tmt this, tmt add, tmt rm, tmt update, tmt preamble, and tmt list all act on the workspace you are currently in.

Reach for --team <name> only when you want an explicit shared team that spans folders (see Shared Teams).

Cross-Folder Collaboration

Agents don't need to be in the same folder to collaborate. From your current workspace you can add an agent whose pane lives in another project:

# In project-a folder, add an agent that's running in project-b
tmt add codex-reviewer 5.1    # Use the pane ID from the other project

Find pane IDs with: tmux display-message -p "#{pane_id}"

This still uses the default workspace scope: the registration is visible from project-a, not from project-b. For long-running collaboration that should be visible on both sides, use a shared team.

Commands

Command	Description
install [claude|codex]	Install tmux-team for an AI agent
this <name> [remark]	Register current pane as an agent
talk <agent> "msg"	Send message and wait for response
talk all "msg"	Broadcast to all agents
check <agent> [lines]	Read agent's pane output
list [team|pane]	Show current workspace agents, one shared team, or one pane's registrations
migrate [--dry-run] [--cleanup]	Move legacy tmux-team.json entries into tmux pane metadata
team	List shared team names
team ls <team>	List members of a shared team
team add <team> <name> [pane]	Add current or specified pane to a shared team
team panes [--json]	Inspect tmux panes grouped by scope
team rm <team> --force	Remove a shared team registration from every pane
learn	Show educational guide

Options for talk:

• --timeout <seconds> - Max wait time (default: 180s)
• --lines <number> - Lines to capture from response (default: 100)

Run tmt help for all commands and options.

Message Delivery

tmux-team uses tmux buffers + paste, then waits briefly before sending Enter. This avoids shell history expansion and handles paste-safety windows in CLIs like Gemini.

Config: pasteEnterDelayMs (default: 500)

tmt config set pasteEnterDelayMs 500

Managing Your Team

Agent registrations live in tmux pane metadata, scoped per workspace by default. The same-folder workflow never needs --team.

List agents and status:

tmt ls              # agents in this workspace
tmt ls myproject    # members of a shared team
tmt ls 10.1         # registrations on a pane
tmt ls main.10.1    # shorthand for main:10.1

Manage shared teams with the team namespace:

tmt team                         # list shared team names
tmt team ls myproject            # list team members
tmt team add myproject claude    # add current pane to a team
tmt team add myproject codex 1.1 # add a specific pane to a team
tmt team rm myproject --force    # remove a team from every pane

A single pane can belong to multiple teams. Commands never guess across teams: tmt talk codex uses the current workspace, while tmt talk codex --team myproject uses only that shared team. If an agent name appears in multiple shared teams and is not in the current workspace, tmux-team asks you to specify the team.

Inspect every tmux pane with tmt team panes. Output is grouped by scope — shared teams first, then workspaces, then unregistered panes — and each section's title lists the agents living there:

Team: acme-app (codex, gemini)
PANE   TARGET             CWD              CMD
%12    main:1.0           ~/acme/frontend  node
%17    main:2.0           ~/acme/backend   python