CLI reference

The tmux-ide command opens the app, adds tmux chrome to existing sessions, reports agent state, messages and waits on agents, and rebuilds sessions after a tmux crash. This page lists every public command in 2.9.3, matching tmux-ide --help. Scripting commands that list --json below print JSON; interactive commands do not.

Open tmux-ide

app.detachable in ~/.tmux-ide/config.json makes detachable mode the default.

Sessions and recovery

Restore does not replay recorded commands unless --run-commands is present. --resume-agents uses captured conversation IDs and each supported agent's native resume command (Claude Code, Codex, opencode, Cursor and Copilot). See Restore and resume.

Inspect and edit a workspace

Row and pane indexes are zero-based. Config mutations preserve WorkspaceConfigV1 and refuse legacy-only fields rather than silently losing them.

Agent status and messaging

See Agent detection for how agent states are decided.

team assign and team unassign take --socket-name or --socket-path to select another tmux server; see Multi-agent teams. serve defaults to ~/.tmux-ide/control.sock. The wait commands use it when requested and otherwise fall back to direct polling.

Claude integration status distinguishes registration, script freshness and user-settings readiness from runtime delivery. Check /hooks in the affected Claude session, then use tmux-ide agent explain <pane> --json on that machine to inspect its actual state stamp. Project or managed settings may override user settings. Repair preserves unrelated hooks and an explicit disableAllHooks preference. Permission/input notifications report blocked; idle notifications do not override a completed turn.

Agent automation

These commands require a running daemon of the same version.

Persist the reserved handle before executing when delivery recovery matters. An uncertain response is not permission to send again with a new handle. See Agent automation for request formats, source credentials, retry rules, and SDK usage.

tmux chrome: adopt existing sessions

These commands drive tmux chrome for plain tmux clients; see that page for the matching tmux bindings.

Saved SSH machines

Profiles do not grant SSH access or copy credentials. Review aliases on the receiving computer before applying an import. An ordinary SSH connection expects the remote daemon to be running; package installation remains explicit.

Multiple tmux servers

tmux-ide can register several tmux servers on one machine. List registrations to get the opaque server ID, then use it to select a server:

tmux-ide servers list --json
tmux-ide servers add --socket-name work --name Work --json
tmux-ide servers add --socket-path /absolute/path/to/socket --name Custom --json
tmux-ide servers sessions <server-id> --json
tmux-ide servers create <server-id> --session-name Work --dir /project/path --json
tmux-ide app --server <server-id> [session]
tmux-ide servers remove <server-id> --json

Add --ssh HOST to manage a remote machine's registrations or open its app. Socket names and paths are resolved on that remote machine. Registration does not create a native tmux server, and removing a registration does not kill its sessions. An offline server remains visible until removed.

The app groups sessions by machine and server. A single server uses a compact view. Saved tabs retain the exact server and session incarnation; a replacement session requires selecting it again. Explicit --server opens in foreground mode and cannot be combined with hosted or headless mode. An older daemon without the server API reports an unsupported capability instead of selecting its default server.

Worktrees

Removal refuses a dirty worktree unless --force is explicit.

Rich pane content

File-backed widgets refresh when their source changes. Ctrl+C restores the ordinary terminal surface.

Updates

Prerelease installs follow the beta channel; stable installs follow latest. Automatic updates require a verified npm, pnpm or Bun global installation and a matching active package-manager destination. Homebrew, Yarn, npx, development checkouts and unknown origins receive instructions for their installation method. A dry run reports the plan without installing or synchronizing skills.

Daemon and server entry points

These are integration surfaces for process hosts, not the normal way to open the app.

The headless owner publishes ~/.tmux-ide/daemon.json with owner-only permissions. A host should wait until both /identity matches that record and /health reports a compatible protocol before considering the child ready. Stop it with SIGINT or SIGTERM; do not wrap it in a second daemonizer.

Restart versus upgrade

tmux-ide daemon restart --json replaces the runtime generation inside the existing daemon process. It preserves the listening configuration, process PID and tmux sessions, and verifies the replacement identity. It does not load newly installed code. A missing daemon is an error.

tmux-ide restart instead stops and relaunches a tmux session, including its pane commands.

Identity and log provenance

tmux-ide daemon service install <absolute-stable-launcher> --json opts into a launchd or systemd user service. Use daemon service status --json to inspect it, daemon service restart --json to load the activated installation in a new process, and daemon service remove --yes --json before uninstalling the launcher. See supervised daemon upgrades for namespace ownership, failure recovery and session preservation.

tmux-ide daemon info --json reports the current daemon instance id, version, pid and liveness, how it was launched (manual, launchd, systemd or embedded in a host) and where its stdout/stderr actually go. The destination is stamped into the daemon record by the running process at startup, so the report does not guess from file names. Any other log-like file discovered under the state home is listed with its last write time and the pid it mentions, labeled historical or unattributed; only the live destination is current. The report never contains the auth token. tmux-ide doctor shows the same summary as one row.

Upgrade the local daemon

tmux-ide update --daemon starts or upgrades the local daemon to the installed version, preserving tmux sessions. Add --if-running to leave fresh installs idle, and --json for structured status. This command does not update a remote machine; install the same version there and run the command in its shell.

Global flags

Command-specific flags are documented with their command above.

See also

• Getting started — install and first run
• Troubleshooting — the command for each common problem
• Configuration — the files these commands read and write