Fix common tmux-ide problems with one command each: tmux version errors, missing keys, wrong agent states, Claude hooks, SSH and restore.

Most problems have one command that shows what is wrong. Start with tmux-ide doctor, then find your symptom below.

Run the doctor first

tmux-ide doctor
tmux-ide doctor --json   # for a bug report

It checks the tmux version, Node.js, your terminal's color support, the app runtime, the daemon and your agent integrations. When you report an issue, include this output and the shortest sequence that reproduces it.

"tmux 3.7 or newer is required"

tmux-ide refuses tmux servers older than 3.7. It never kills or replaces a running server for you. Sessions you create from tmux-ide use its bundled tmux 3.7c. Start new sessions from the app (press n on Home, or Ctrl+N in Sessions) and move your work over when you're ready.

`tmux-ide: command not found`

The installer puts the launcher in ~/.local/bin and prints a PATH instruction if your shell doesn't include it. Add that directory to your PATH and open a new shell.

The app does not start after an interrupted download

Download and verify this version's runtime again:

tmux-ide update --tui-binary
tmux-ide app

⌥ keys do nothing in tmux chrome sessions

Some agents, Claude Code among them, switch the terminal to a key encoding that tmux can't match against ⌥ bindings. Use the prefix form instead: prefix h, prefix j, prefix k and so on. See tmux chrome keys.

If keys misbehave inside the app itself, set app.kittyKeys to false in ~/.tmux-ide/config.json.

An agent shows the wrong state

Ask tmux-ide how it classified the pane:

tmux-ide agent explain %3

The output shows the agent's own @agent_state stamp and its age, which manifest matched, and the screen lines it read.

A working or blocked stamp older than 10 minutes is ignored, and the screen is read instead. Agents that report their own state should re-stamp while they work.
If the wrong manifest matched, pin the right one with tmux set-option -p @agent_hint <id>.
To change how an agent is recognized, add a manifest. See Override detection for a tool.

Claude Code status is not exact

Check the integration:

tmux-ide integration status

Hooks are read when a Claude Code session starts, so restart sessions that were running before you installed the integration. Project or managed Claude Code settings can override user settings. See the Claude Code integration.

A remote machine won't connect

The app connects with SSH BatchMode=yes, so it can't type a password or accept an unknown host key. Set up key authentication and connect once with ssh to trust the host.
The remote machine must run its own daemon. Start it with tmux-ide --headless there, or with tmux-ide machines start <alias> --write from your machine.
tmux-ide on the remote machine must be on the non-interactive SSH PATH.

See Remote machines over SSH.

`restore` finds no snapshot

Snapshots are written by the background updater about every 30 seconds while any session is adopted or was created from the app. Without one, there is nothing to restore. Preview what a restore would do before running it:

tmux-ide restore --dry-run

See Restore and resume.

`events` prints nothing

The event log is written by the same background updater, so it needs an adopted session or one created from the app. See Notifications and events.

Troubleshooting