# tmux-ide — manual for AI agents tmux-ide 2.9.3. Docs: https://tmux-ide.com/docs · Index for LLMs: https://tmux-ide.com/llms.txt · Full text: https://tmux-ide.com/llms-full.txt ## Quick reference ```bash tmux set-option -p @agent_state "working:$(date +%s)" # report state: working|blocked|done|idle tmux-ide team --json # every session, window and per-pane agent state tmux-ide send "message" # type into another pane and press Enter (--no-enter to stage) tmux-ide wait agent-status --status done --timeout 600000 # exit 0 on match, 1 on timeout tmux-ide agent explain --json # why a pane has its state tmux-ide validate --json # after any workspace.yml change ``` tmux-ide is an open-source (MIT) agent workspace built around tmux, by Prototyper. tmux keeps owning processes, PTYs, sessions, windows and panes; tmux-ide adds a terminal app with live agent status, named agents and panes, and exact pane navigation, plus an optional status-bar chrome for plain tmux clients. If tmux-ide stops, every session is still ordinary tmux. ## Install ```bash curl -fsSL https://tmux-ide.com/install.sh | sh # macOS and glibc Linux; installs under ~/.local, no sudo npm install -g tmux-ide # alternative when Node.js 20+ is already installed tmux-ide doctor # check tmux version, runtime and integrations ``` The installer prints a PATH instruction if `~/.local/bin` is not on PATH. Existing tmux sessions are preserved. ## Set up a project ```bash tmux-ide app [session] # open the app (bare `tmux-ide` does the same outside a configured project) tmux-ide adopt # add the status-bar chrome to an existing tmux session tmux-ide adopt --all # adopt every live session; `unadopt ` reverts tmux-ide integration install claude # Claude Code hooks: ground-truth agent status + skill tmux-ide integration install opencode # capture opencode session ids for restore --resume-agents tmux-ide integration status --json # what is detected and wired up ``` The app has two surfaces: Home (F1: agents across local and SSH machines, search, needs-attention filter) and Terminals (F2: the live session, window tabs, pane headers). F5 opens Commands; Ctrl+Q quits and leaves every session running. A `.tmux-ide/workspace.yml` layout is optional. To create one: `tmux-ide detect --json`, propose two or three layouts to the user, then `tmux-ide detect --write` or the `tmux-ide config` commands, and always finish with `tmux-ide validate --json`. ## Report your own state (the agent contract) If you run inside a tmux pane, set pane-local options. A fresh self-report is the authoritative signal; screen scraping is only the fallback. ```bash tmux set-option -p @agent_state "working:$(date +%s)" # working | blocked | done | idle tmux set-option -p @agent_status_text "refactoring auth" # optional, plain text, max 32 chars tmux set-option -p @agent_display_name "reviewer" # optional name shown in the UI tmux set-option -p @agent_hint # force a detection manifest (e.g. claude, codex) tmux set-option -p @agent_session_id "" # set only to your harness's real resume id; restore --resume-agents uses it ``` The status text and display name are honored only while `@agent_state` is fresh. The value of `@agent_state` is `:`. A working or blocked report older than about 10 minutes is treated as stale, so re-stamp while you work. Claude Code gets this automatically after `tmux-ide integration install claude` (new sessions only). ## Observe and coordinate Commands that list `--json` in `tmux-ide --help` return structured output; prefer it. ```bash tmux-ide team --json # every session, pane and agent status tmux-ide agent explain --json # how a pane's status was detected tmux-ide send "message" # type into another pane's agent (%id, title or name) tmux-ide wait agent-status --status done # block until a session reaches a status tmux-ide wait output --match "" [--timeout ] # block until a pane prints a match tmux-ide events --follow --json # stream agent-status transitions tmux-ide serve # local control socket for long-running loops tmux-ide team assign <%pane> "" # group panes into a named team; team unassign <%pane> removes tmux-ide automation panes --json # scoped, attributed pane reads/sends with retry-safe handles tmux-ide mcp # the same automation tools over MCP stdio ``` Both waits exit 0 on match, 1 on timeout. Use `send`/`wait` for quick messages; use `automation` or `mcp` when you need exact pane identity, attribution and retry-safe handles (https://tmux-ide.com/docs/automation). Claude Code agent teams: set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` and `teammateMode` `"tmux"` (or `"auto"` inside tmux) in `~/.claude/settings.json`; releases after 2.9.3 set this up in the installer; split-pane teammates then appear in tmux-ide grouped under their team, named as the lead named them, with normal agent status. tmux-ide reads `~/.claude/teams//config.json` read-only; Claude Code owns spawning, tasks and messaging. Docs: https://tmux-ide.com/docs/claude-code-agent-teams ## Recover and branch ```bash tmux-ide restore --dry-run --json # preview rebuilding the fleet after a tmux server crash tmux-ide restore --resume-agents # rebuild and resume agent conversations tmux-ide worktree create # git worktree on a new branch with its own session ``` ## Rules for agents - Never kill, unadopt or rename a user's sessions unless asked; use scratch sessions for tests. - Do not present task or mission orchestration as available; it is not part of this release. - Use `tmux-ide send`, not raw `tmux send-keys`, so the target resolves by id, title or name and long messages go through a dispatch file. - When unsure about a command, run `tmux-ide --help` or read https://tmux-ide.com/docs/commands. - Docs for depth: https://tmux-ide.com/docs/agent-detection · https://tmux-ide.com/docs/multi-agent-teams · https://tmux-ide.com/docs/restore-resume · https://tmux-ide.com/docs/automation