CLI reference
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.
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.5, matching
tmux-ide --help. Scripting commands that list --json below print JSON;
interactive commands do not.
Version 2.9.21 added the plugin, action and lua commands and
worktree create --plain. Version 2.9.22 added servers upgrade,
restore --from and Markdown files in tmux-ide open. Versions 2.9.23 to
2.9.27 add no commands. See the
2.9.27 release notes.
Open a browser pane
tmux-ide open # Browser start page beside the current pane
tmux-ide open http://localhost:3000 # URL in a new pane
tmux-ide open ./preview.html --split down --size 40
tmux-ide open https://example.com --session Website --windowThe command requires terminal-browser on PATH. It creates and selects a new
pane in the current tmux session, leaving the original terminal running. Outside
tmux, select an existing session with --session NAME; --pane %ID selects an
exact split target. --window creates a separate tmux window instead of a split.
The default split is right, using 50% of the available space. --size accepts
10–90 percent. URLs and file paths are passed as literal arguments.
With the native-capable terminal-browser development build and a compatible
local macOS GUI, the browser automatically connects its pixel surface to the new
pane. The standard browser and remote sessions retain terminal graphics rendering.
Native-capable browser distribution is still separate from the npm package.
Set TMUX_IDE_TERMINAL_BROWSER_BIN to an absolute executable launcher path to
select a different browser build. No browser is downloaded automatically.
--json returns { "pane": "%3", "session": "$0", "window": "@1", "status": "created" }.
This confirms pane creation, not completion of page loading or native rendering.
Missing executables and invalid targets fail before creating a pane.
Open a Markdown file
tmux-ide open notes.md # Reader pane beside the current pane
tmux-ide open docs/README.markdown --split down --size 40An argument that ends in .md or .markdown (in any case), has no scheme://
and names an existing file opens in a reader pane instead of the browser. The
pane runs tmux-ide show <file>, so a plain terminal shows the terminal
rendering, and the Mac app paints its native Markdown reader
over the pane. A missing Markdown file fails with FILE_NOT_FOUND and creates no
pane. --split, --size, --pane, --session and --window work as they do
for the browser. The reader shows files up to 4 MiB and takes the pane's keys
while it is shown; see Markdown reader.
--json returns { "pane": "%3", "session": "$0", "window": "@1", "status": "created", "kind": "reader" }.
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 fleet home from tmux chrome, or print fleet state as JSON |
tmux-ide --team | Force the fleet home 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 [--from FILE] [--dry-run] [--run-commands] [--resume-agents] [--json] | Rebuild the fleet from the last snapshot, or from FILE |
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
| 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 status and messaging
See Agent detection for how agent states are decided.
| 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 integration agent-teams [enable|disable|status] [--json] | Turn Claude Code agent teams on or off in ~/.claude/settings.json |
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 team assign <%pane> <team> [--json] | Group a pane under a named team in Home and the sidebar |
tmux-ide team unassign <%pane> [--json] | Remove a pane's manual team membership |
tmux-ide serve [socket-path] | Run the foreground, owner-only local NDJSON control socket |
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.
| Command | What it does |
|---|---|
tmux-ide automation panes --json | Discover scoped pane endpoints |
tmux-ide automation reserve --json | Reserve the read or send intent supplied on stdin |
tmux-ide automation execute --json | Execute a saved handle and intent supplied on stdin |
tmux-ide automation read --json | Reserve and execute a read intent from stdin |
tmux-ide automation send --json | Reserve and execute a send intent from stdin |
tmux-ide automation status GENERATION OPERATION_ID --json | Query an existing operation without repeating it |
tmux-ide mcp | Serve the same automation API over MCP stdio |
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
| 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 chrome without killing the session; also removes the server-wide chrome keys for every adopted 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 tmux chrome sidebar column |
These commands drive tmux chrome for plain tmux clients; see that page 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 edit <id-or-label> [--name <label>] [--ssh <alias>] [--write] [--json] | Preview or edit an existing profile, preserving its ID |
tmux-ide machines start <alias> [--write] [--json] | Preview or explicitly start the already-installed remote daemon |
tmux-ide machines enable|disable|remove <id-or-label> [--write] [--json] | Preview or apply enabling, disabling or removing a saved profile |
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> --jsonMove a running server onto tmux-ide's own tmux. The command snapshots every session, asks, restarts the server and restores the sessions. See Move to tmux-ide's own tmux.
tmux-ide servers upgrade [--socket-path PATH|--socket-name NAME] [--ssh HOST] [--yes] [--end-running-agents] [--no-resume-agents] [--dry-run] [--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
| Command | What it does |
|---|---|
tmux-ide worktree create <branch> [--from <ref>] [--dir <path>] [--no-session] [--plain] | 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.
Plugins and the command catalog
| Command | What it does |
|---|---|
tmux-ide plugin list [--json] | Show the plugin host and each plugin's state |
tmux-ide plugin reload [name] | Discover plugins again and reload all, or one |
tmux-ide plugin logs [name] [-n <lines>] [-f] | Show or follow the plugin log |
tmux-ide plugin consent <name> [--yes] | Review a plugin's capabilities and allow it to run |
tmux-ide plugin revoke <name> | Stop a plugin and withdraw consent |
tmux-ide plugin example [name] | List the example plugins, or copy one into ~/.tmux-ide/plugins |
tmux-ide action list [--json] | List built-in and plugin commands |
tmux-ide action run <id> [--arg name=value]… [--yes] | Run a plugin command; dangerous ones ask to confirm |
tmux-ide action run <id> --input '<json>' | Run a built-in command with its JSON input |
tmux-ide lua run <file> / -e <code> | Run Lua against the daemon, with init.lua's permissions |
tmux-ide lua api / tmux-ide lua describe <name> | List the plugin API, or describe one function |
See Plugins for consent, capabilities and limits.
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 --daemon [--if-running] [--json] | Start or upgrade the local daemon to the installed version, keeping tmux sessions |
tmux-ide update --tui-binary [--json] | Download and verify the matching compiled app 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.
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
| 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.
See also
- Getting started — install and first run
- Troubleshooting — the command for each common problem
- Configuration — the files these commands read and write
Change the tmux-ide theme
Change the tmux-ide app's theme: follow your terminal, force dark or light, set a preset in the picker or config.json, and control text contrast in panes.
Markdown reader
tmux-ide open notes.md shows a Markdown file in a native, read-only reader pane in the Mac app, with live reload, find and safe links and images.