CLI reference

Every command accepts --json for structured output. Run tmux-ide --help for the built-in version of this list.

Sessions

The dock

Agent status

See Agent detection and Notifications & events.

Restore

--resume-agents revives Claude conversations via claude --resume. See Restore & resume.

Worktrees

See Worktrees.

Config & inspection

Setup & settings

Pane messaging

send also reads from stdin: echo "msg" | tmux-ide send <target>.

Server

Native and desktop handoff

--headless is the config-free daemon entry point for the native app and other process hosts. Launch the installed executable directly with an argv array:

executable: /resolved/path/to/tmux-ide
argv:       ["--headless"]

Resolve executable to the installed root package's tmux-ide bin (not a workspace source file or the private @tmux-ide/daemon package). Pass every argument as its own argv element. Use an existing directory as the child working directory, inherit HOME unless you deliberately isolate daemon state, and retain the returned child PID. Stdio may be piped or redirected to null, but do not wrap the invocation in a shell, append &/nohup, or add a second daemonizer. Readiness is established by the probes below, not by the spawn call returning and not by parsing stdout.

tmux-ide --headless stays in the foreground; the spawned process is the daemon owner even when the host detaches its stdio. It does not open a TUI, launch a tmux workspace, require a project config, install anything, or inherit remote-access authentication. --port N is optional; omitting it selects a free loopback port. Treat a non-zero child exit before readiness as launch failure and surface its stderr/structured error to the user.

The owner first atomically acquires a process-lifetime claim, then publishes this versioned discovery shape with owner-only permissions. The claim spans record inspection, socket binding, publication, and the daemon's full lifetime; concurrent cold-start losers wait for and reuse the winner instead of binding or publishing another daemon:

{
  "pid": 4312,
  "port": 4010,
  "protocolVersion": 1,
  "productVersion": "2.8.0",
  "instanceId": "9bcf33b0-c837-4a94-b5e8-c0977f54464f",
  "startedAt": "2026-07-21T00:00:00.000Z",
  "bindHostname": "127.0.0.1",
  "authToken": null
}

Startup is ready only when all checks succeed:

1. ~/.tmux-ide/daemon.json exists (or the directory selected by TMUX_IDE_DAEMON_INFO_DIR) and names the child PID and port.
2. The unauthenticated GET /identity response exactly matches the record's pid, protocolVersion, instanceId, and startedAt. This binds the endpoint before the host sends any credential. productVersion is reported as a diagnostic and may differ when the wire protocol remains compatible.
3. GET /health succeeds and reports the compatible daemon wire protocol and its diagnostic productVersion. /healthz reports that same value.

Construct probe URLs with a URL API or bracket an IPv6 literal ([::1]); never interpolate an unbracketed IPv6 hostname into http://host:port.

A second tmux-ide --headless never takes over a healthy daemon. If its wire protocol is compatible, the second process reports already-running and exits zero; a product-version difference is diagnostic only. An incompatible wire protocol or disagreement between discovery and health exits non-zero so the host can ask the user to restart or upgrade. Only a dead PID is stale state and may be removed. A live PID whose health endpoint is unavailable still owns the slot: the contender exits non-zero without clearing the record or starting another daemon.

Publication is create-if-absent and cleanup is generation-safe: an owner removes only the record carrying its own instanceId. It never deletes a record that a concurrent process replaced while cleanup was in progress.

An existing record that is protocol-less, malformed, oversized, symlinked, owned by another user, or not owner-only is invalid, not missing. Do not delete it or start another owner. The CLI only removes a securely read invalid record when its positive recorded PID is explicitly proven dead; otherwise the host should ask the user to inspect or remove the record after verifying the owner process.

Send SIGINT or SIGTERM to stop the owner. The daemon shutdown action follows the same idempotent path. Both close HTTP/WebSocket/PTY resources, remove the canonical record, and let the owner exit zero; a cleanup failure exits non-zero.

Flags

Key discovery

Once a session is adopted, the whole UI is a keystroke or two away. Each surface has a prefix twin (prefix then a letter) that works under every keyboard protocol, plus an ⌥ fast-path when your terminal allows it — lead with the prefix.

Rebind any of them in ~/.tmux-ide/config.json (keys.*) — the prefix twin follows the fast-path key. See Theming & config.