# tmux-ide

> tmux for coding agents: run Claude Code and Codex in the terminal multiplexer you already use, see each agent's status and jump to the one that needs you.

tmux-ide is an open-source Prototyper project (MIT license), current version 2.9.15. tmux keeps owning processes, panes, and sessions; tmux-ide adds an agent-aware workspace on top, so sessions keep running if tmux-ide closes.

Install: `curl -fsSL https://tmux-ide.com/install.sh | sh` — then run `tmux-ide app`.

AI agents: read https://tmux-ide.com/agents.md first — install, status reporting, and coordination commands in one page.

Claude Code agent teams: set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` and `teammateMode` `"tmux"` (or `"auto"` inside tmux) in `~/.claude/settings.json` (2.9.4 and later 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/<team>/config.json` read-only; Claude Code owns spawning, tasks and messaging. Docs: https://tmux-ide.com/docs/claude-code-agent-teams

Every documentation page is also available as Markdown: append `.md` (or `.mdx`) to its URL (for example https://tmux-ide.com/docs/getting-started.md), or request the page with `Accept: text/markdown`. Each Markdown page opens with `---` frontmatter: title, description, canonical URL and last update. The homepage is https://tmux-ide.com/index.md.

## When to use tmux-ide

- Several coding agents run in tmux and you need to know which one is working, blocked or done, and which one needs the user: `tmux-ide team --json`.
- You run inside a tmux pane and want to report your own state: `tmux set-option -p @agent_state "working:$(date +%s)"`.
- You need to wait for another agent or type into its pane: `tmux-ide wait agent-status`, `tmux-ide wait output`, `tmux-ide send`.
- The tmux server crashed and the sessions need rebuilding: `tmux-ide restore --resume-agents`.
- You want a git worktree on a new branch with its own session: `tmux-ide worktree create <branch>`.

It does not run on native Windows (use WSL), Alpine or other musl Linux, or Intel Macs. A tmux server you started yourself must be tmux 3.7 or newer. Task or mission orchestration is not part of this release.

## Docs

- [What is tmux-ide? Docs overview](https://tmux-ide.com/docs): tmux-ide is an open-source terminal app for running Claude Code, Codex and other coding agents in tmux, locally and over SSH. See what ships in 2.9.3.
- [Install tmux-ide on macOS and Linux](https://tmux-ide.com/docs/getting-started): Install tmux-ide with one command on macOS or Linux, no sudo. Open your first agent-aware tmux session and learn the keys that move between agents.
- [Terminal app for tmux and coding agents](https://tmux-ide.com/docs/app-surfaces): Tour the tmux-ide terminal app: Home lists coding agents across machines, Terminals mirrors live tmux panes, plus Commands, Sessions and Attention.
- [Native macOS alpha: install and update](https://tmux-ide.com/docs/native-alpha): Install the tmux-ide native macOS alpha: requirements, daemon compatibility, installation, updates, rollback and reporting problems.
- [Run coding agents on remote machines over SSH](https://tmux-ide.com/docs/remote-machines): Run coding agents on remote machines over SSH with tmux-ide: start the remote daemon, open its sessions from your app, and keep agents running.
- [tmux agent status for Claude Code and Codex](https://tmux-ide.com/docs/agent-detection): tmux agent status: see if Claude Code, Codex or any agent in a pane is working, blocked, done or idle, from hooks, a self-report or a screen fallback.
- [workspace.yml and config.json reference](https://tmux-ide.com/docs/configuration): Reference for the optional .tmux-ide/workspace.yml layout file and the global ~/.tmux-ide/config.json settings file, with every field and default.
- [Themes: 22 presets, dark, light and contrast](https://tmux-ide.com/docs/theming): Pick System, Dark, Light or one of 22 tmux-ide theme presets such as Tokyo Night, Dracula or Catppuccin, and control automatic text contrast in panes.
- [tmux-ide CLI reference: commands and flags](https://tmux-ide.com/docs/commands): Every tmux-ide command and flag: open the app, adopt tmux sessions, restore after a crash, send to and wait on agents, with JSON output for scripts.
- [Animated tmux-ide app demo](https://tmux-ide.com/docs/demo): An animated tour of the tmux-ide app, showing Home, an agent-aware Terminals workspace and Commands, rendered from the production components.
- [Troubleshooting: common problems and fixes](https://tmux-ide.com/docs/troubleshooting): Fix common tmux-ide problems with one command each: tmux version errors, missing keys, wrong agent states, Claude hooks, SSH and restore.

## Agents & automation

- [Agent automation: CLI, MCP and SDK](https://tmux-ide.com/docs/automation): Let agents and scripts read and type into specific tmux panes through the tmux-ide CLI, MCP server and SDK, with operation handles for safe recovery.
- [Run multiple coding agents together in tmux](https://tmux-ide.com/docs/multi-agent-teams): Run Claude Code, Codex and other agents side by side in tmux and coordinate them: team groups, a shared status bus, direct messages and wait commands.
- [Claude Code agent teams in tmux: setup and status](https://tmux-ide.com/docs/claude-code-agent-teams): Run Claude Code agent teams in tmux split panes: enable them in settings.json, then see each teammate by name, grouped by team, with live status.
- [tmux agent notifications and event streams](https://tmux-ide.com/docs/notifications-events): Get a desktop notification when Claude Code or Codex is blocked or done: tmux toasts, macOS banners, sound, a JSONL event stream and wait commands.
- [tmux resume: restore sessions and agent chats](https://tmux-ide.com/docs/restore-resume): Resume tmux sessions after a crash or reboot. tmux-ide restore rebuilds windows, layouts and directories and reopens Claude Code and Codex chats.
- [Git worktrees for parallel coding agents](https://tmux-ide.com/docs/worktrees): Run parallel agents on parallel branches: tmux-ide worktree creates a git worktree and a ready tmux session in one command, then lists and removes them.
- [tmux layout templates for coding agents](https://tmux-ide.com/docs/templates): The workspace templates shipped with tmux-ide 2.9.5, what each layout contains, and how to start a project from one with tmux-ide init --template.

## tmux chrome

- [tmux status bar and sidebar for agents](https://tmux-ide.com/docs/the-dock): A tmux status bar and sidebar for coding agents: tmux-ide adopt adds live agent status glyphs, prefix keys, menus and alerts to plain tmux sessions.

## Release notes

- [What's new in 2.9.4](https://tmux-ide.com/docs/release-2-9-4): tmux-ide 2.9.4, the current release: the installer sets up Claude Code agent teams, a new agent-teams command, and corrected CLI help.

## Project

- [Contributing: setup, checks and releases](https://tmux-ide.com/docs/contributing): How to contribute to tmux-ide: the development workflow, the checks every change must pass, release quality gates and open source project conventions.
- [tmux for coding agents](https://tmux-ide.com/tmux-for-coding-agents): Claude Code, Codex and other agents in tmux: status, teams, and restore and resume
- [Manual for AI agents](https://tmux-ide.com/agents.md): install, the agent status contract, and the commands agents use to coordinate
- [Source code on GitHub](https://github.com/wavyrai/tmux-ide): issues, releases, and the MIT license
- [npm package](https://www.npmjs.com/package/tmux-ide): the published `tmux-ide` CLI
- [Prototyper](https://www.prototyper.co): the team that builds tmux-ide
- [AGENTS.md](https://github.com/wavyrai/tmux-ide/blob/main/AGENTS.md): instructions for AI coding agents working in the tmux-ide repository
- [Agent skill](https://github.com/wavyrai/tmux-ide/tree/main/skill): `skill/SKILL.md`, how an agent uses tmux-ide (status contract, fleet, send, restore); install with `npx skills add wavyrai/tmux-ide`

## Agent discovery

- [Agentic Resource Discovery catalog](https://tmux-ide.com/.well-known/ard.json): the MCP server, the agent skill, agents.md and llms.txt
- [AI Catalog](https://tmux-ide.com/.well-known/ai-catalog.json): the same entries in the AI Catalog 1.0 format
- [MCP server card](https://tmux-ide.com/.well-known/mcp/server-card.json): the local `tmux-ide mcp` stdio server
- [API catalog (RFC 9727)](https://tmux-ide.com/.well-known/api-catalog): links to the automation docs
- [Agent skills index](https://tmux-ide.com/.well-known/agent-skills/index.json): the skill's URL and sha256 digest

## Markdown

- [Docs index](https://tmux-ide.com/docs/llms.txt): every docs page in sidebar order
- [Homepage as Markdown](https://tmux-ide.com/index.md): what tmux-ide is, install, and the FAQ

## Optional

- [Full documentation as one file](https://tmux-ide.com/llms-full.txt): every docs page in Markdown
- [What's new in 2.9.12](https://tmux-ide.com/docs/release-2-9-12): Direct Rust terminal delivery for the native GUI, changed-row updates and stable resize input.
- [What's new in 2.9.11](https://tmux-ide.com/docs/release-2-9-11): Native frame delivery, pane-switch typing, and stable terminal sizing.
- [What's new in 2.9.10](https://tmux-ide.com/docs/release-2-9-10): Improve native GUI typing over SSH.
- [What's new in 2.9.9](https://tmux-ide.com/docs/release-2-9-9): Keep terminal pane dimensions stable when the native app loses focus.
- [What's new in 2.9.8](https://tmux-ide.com/docs/release-2-9-8): Reliable pane discovery and improved kitty graphics compatibility for the native macOS alpha.
- [What's new in 2.9.7](https://tmux-ide.com/docs/release-2-9-7): Compatibility with stock tmux 3.8, images in the native alpha, and installer upgrades that move a running daemon without replacing existing tmux sessions.
- [What's new in 2.9.6](https://tmux-ide.com/docs/release-2-9-6): tmux-ide 2.9.6: terminal delivery, guarded resizing, shared discovery and separate native alpha integration.
- [What's new in 2.9.5](https://tmux-ide.com/docs/release-2-9-5): tmux-ide 2.9.5: terminal ordering, Unicode paste, redraw recovery and bundled tmux discovery fixes.
- [What's new in 2.9.3](https://tmux-ide.com/docs/release-2-9-3): tmux-ide 2.9.3: more reliable remote connections, window resizing, installation, updates and recovery for the Home and Terminals app.
- [What's new in 2.9.2](https://tmux-ide.com/docs/release-2-9-2): tmux-ide 2.9.2 brings the Home and Terminals app to the stable channel: agents across machines, a calmer workspace, smoother resizing, a simple installer.
- [2.9 beta archive](https://tmux-ide.com/docs/release-2-9-0-beta-1): Archived highlights from the tmux-ide 2.9.0 beta series, kept for reference. The betas are superseded by the stable 2.9 releases.