This page follows the public surface printed by tmux-ide --help in 2.9.0-beta.18. --json is available on the scripting commands that explicitly list it below; interactive commands do not emit JSON.

Open tmux-ide

Command	What it does
`tmux-ide`	Open the visual app when no workspace config is present; launch the project layout when one is present
`tmux-ide <path>`	Open or launch from a particular directory
`tmux-ide start [path]`	Explicitly launch the declarative project layout
`tmux-ide app [session]`	Open Home, or bypass Home and open a live session
`tmux-ide app --detachable`	Host the app in `_tmux-ide-app`; `Ctrl+Q` detaches and the viewer survives
`tmux-ide app --hosted`	Alias for `--detachable`
`tmux-ide team [--json]`	Open the classic fleet cockpit, or print fleet state as JSON
`tmux-ide --team`	Force the classic fleet cockpit for a bare invocation

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

Sessions and recovery

Command	What it does
`tmux-ide init [--template <name>] [--json]`	Scaffold `.tmux-ide/workspace.yml`; auto-detect the stack unless a template is named
`tmux-ide stop [session] [--json]`	Kill the resolved project session or the named session
`tmux-ide restart [session] [--json]`	Stop and relaunch the session
`tmux-ide attach [session] [--json]`	Reattach to a running session
`tmux-ide ls [--json]`	List tmux sessions
`tmux-ide status [session] [--json]`	Show session status
`tmux-ide restore [--dry-run] [--run-commands] [--resume-agents] [--json]`	Rebuild the fleet from the last snapshot

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. See Restore & resume.

Inspect and edit a workspace

Command	What it does
`tmux-ide setup`	Open the interactive setup wizard
`tmux-ide setup --edit`	Open the config tree editor
`tmux-ide settings`	Open the standalone config manager
`tmux-ide inspect [path] [--json]`	Show the effective config and live runtime state
`tmux-ide doctor [--json]`	Check the local installation and requirements
`tmux-ide validate [path] [--json]`	Validate the resolved workspace config
`tmux-ide detect [path] [--json]`	Detect the project stack and show a suggested layout
`tmux-ide detect [path] --write`	Write the detected layout to `.tmux-ide/workspace.yml`
`tmux-ide migrate [path] --dry-run [--json]`	Preview migration from legacy `ide.yml`
`tmux-ide migrate [path] --write [--json]`	Create `.tmux-ide/workspace.yml` from `ide.yml`
`tmux-ide config [--json]`	Print the resolved launch projection
`tmux-ide config set <path> <value>`	Set a workspace value by dot path
`tmux-ide config add-pane --row <N> --title <T> [--command <C>] [--size <percent>]`	Add a pane
`tmux-ide config remove-pane --row <N> --pane <M>`	Remove a pane
`tmux-ide config add-row [--size <percent>]`	Add a row containing a shell pane

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

Agent awareness and coordination

Command	What it does
`tmux-ide integration install claude`	Install Claude Code lifecycle hooks and refresh the bundled Claude skill
`tmux-ide integration install opencode`	Install session-ID capture for future opencode sessions
`tmux-ide integration uninstall <claude\|opencode>`	Remove only tmux-ide's integration entries
`tmux-ide integration status [--json]`	Show discovered agents, integration state, and resume-ID capture
`tmux-ide agent explain <pane\|session> [--json]`	Explain exactly how an agent state was classified
`tmux-ide send <target> <message> [--no-enter] [--json]`	Type into a pane selected by ID, title, semantic name, or supported legacy role
`tmux-ide send --to <target> <message> [--no-enter] [--json]`	Equivalent explicit target form
`tmux-ide events [--follow] [--json]`	Read recent agent-state transitions or follow them
`tmux-ide events --follow --socket[=<path>]`	Follow pushed events from a running control server
`tmux-ide wait agent-status <session> --status <state> [--timeout <ms>] [--json]`	Wait for a session status; exit 0 on match and 1 on timeout
`tmux-ide wait output <pane\|session> --match <regex> [--timeout <ms>] [--json]`	Wait until visible pane output matches
`tmux-ide serve [socket-path]`	Run the foreground, owner-only local NDJSON control socket

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.

Adopt ordinary tmux sessions

Command	What it does
`tmux-ide adopt <session>`	Add tmux-ide's server-side status bar and agent tracking
`tmux-ide adopt --all`	Adopt every live non-internal session
`tmux-ide unadopt <session>`	Remove tmux-ide chrome without killing the session
`tmux-ide switcher [--client <name>]`	Open the compact session picker
`tmux-ide cheatsheet`	Print the complete key sheet
`tmux-ide menu [--client <name>]`	Open the contextual tmux actions menu
`tmux-ide popup <explorer\|changes\|config>`	Open a widget in a tmux popup
`tmux-ide sidebar-toggle [--session <name>]`	Toggle the app navigation column

See The dock & keys for the matching tmux bindings.

Saved SSH machines

Command	What it does
`tmux-ide machines ls [--json]`	List saved machine profiles
`tmux-ide machines export [--json]`	Print the portable profile registry
`tmux-ide machines import <file> [--write] [--json]`	Preview an add-only import, then save explicitly with `--write`
`tmux-ide machines add <alias> [--write] [--json]`	Preview or save an SSH target
`tmux-ide machines start <alias> [--write] [--json]`	Preview or explicitly start the already-installed remote daemon

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.

Worktrees

Command	What it does
`tmux-ide worktree create <branch> [--from <ref>] [--dir <path>] [--no-session]`	Add a worktree and, by default, open an adopted session in it
`tmux-ide worktree open <branch>`	Open or switch to the worktree's session
`tmux-ide worktree list [--json]`	Join git worktrees with their live session status
`tmux-ide worktree remove <branch> [--force]`	Remove the worktree, then kill only its derived session

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

Rich pane content

Command	What it does
`tmux-ide show <file>`	Select Markdown or raster-image rendering from the file type
`tmux-ide widget markdown [file]`	Render Markdown from a file or stdin
`tmux-ide widget image <file>`	Render PNG, JPEG, GIF, WebP, or AVIF content
`tmux-ide widget card [file]`	Render the structured card JSON contract from a file or stdin

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

Updates

Command	What it does
`tmux-ide update [--dry-run] [--json]`	Update according to the detected install method, or print the plan
`tmux-ide update --tui-binary [--json]`	Download and verify the matching compiled OpenTUI runtime
`tmux-ide update --manifests [--json]`	Refresh the agent-detection manifest pack; local overrides still win
`tmux-ide skill-sync [--json]`	Refresh the managed Claude Code skill in `~/.claude/skills/tmux-ide`

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.

Command	What it does
`tmux-ide --headless [--port <N>] [--json]`	Own the canonical daemon in the foreground without opening tmux or a TUI
`tmux-ide daemon reserve-supervisor <id> [--json]`	Explicitly reserve a stopped daemon namespace before installing a supervisor
`tmux-ide --headless --supervised <id>`	Run the foreground owner only with a matching preinstalled reservation
`tmux-ide daemon release-supervisor <id> --yes [--json]`	Release the reservation after removing the service and proving its owners stopped
`tmux-ide daemon restart [--json]`	Reset the existing daemon runtime in its supervising process; preserve tmux panes
`tmux-ide daemon info [--json]`	Identity, supervisor and actual log destination of the daemon; labels stale logs
`tmux-ide command-center [--port <N>]`	Start the command-center HTTP API (default port 4000)
`tmux-ide server [--port <N>]`	Deprecated loopback-only PTY server; use `--headless`

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.

Global flags

Flag	Meaning
`-h`, `--help`	Print built-in help
`-v`, `--version`	Print the installed version
`--verbose`	Log tmux commands; `TMUX_IDE_DEBUG=1` is equivalent
`--json`	Request structured output where the command lists JSON support
`--headless`	Run only the canonical daemon in this process

Command-specific flags are documented with their command above.

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 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 beta there or run the command in its shell.

CLI reference