CLI reference#
optimus with no arguments opens the terminal dashboard. Everything else is a subcommand. This page is generated from the binary's own help on every docs build. optimus <command> -h (or optimus help <command>) shows one command and its flags.
optimus — the tmux of AI coding agents
Usage:
optimus open the dashboard (TUI)
Multiplexer
optimus claude|codex|… [dir] start that agent here and attach (-p PROMPT, -d to stay detached,
-w own git worktree, --name N)
optimus new [agent] [dir] start an agent (default: config default_agent)
--name N --prompt P --attach --worktree (own git worktree + branch)
optimus fanout "task" same task to several agents, each in its own worktree (--agents claude,codex)
optimus compare agents in worktrees side by side: state, changes, branch
optimus wt diff|merge|rm W review, merge (--commit) or discard (--force) an agent's worktree
optimus wt pr W push an agent's branch and open a pull request (--title, --draft)
optimus ps list running agents (optimus windows + other live sessions)
optimus fleet one-line summary: agents, waiting, busy, today's spend (--json, --tmux)
optimus attach [window] attach to a window (Alt-q to come back)
optimus peek <window> [-n 40] print the bottom of a window's screen
optimus send <window|all> TEXT type a prompt into one or all agents (--no-enter)
optimus kill <window> stop an agent window
optimus next [--switch] the agents waiting for you (Alt-n jumps to the next one)
optimus answer <window> KEY… answer a prompt without attaching (e.g. 1, y, Enter, Escape)
optimus watch notify on input / finished turns (also runs inside web and the TUI)
optimus resume <session> reopen a past session in the multiplexer (--attach)
optimus takeover <pid|session> move an agent running outside optimus into it (stops it, resumes
the same session here; --force if it's mid-turn, --attach)
Remote
optimus web browser dashboard with live terminals (--bg, --open, --url, --stop,
--addr 0.0.0.0:7777 for phone/LAN)
Sessions & context
optimus ls list sessions (-a agent -p project -n 30 --live --all --json)
optimus show <session> print a transcript (--tail N)
optimus search TEXT find sessions whose transcripts mention TEXT (-n 20 --json)
optimus handoff <session> build a context document from a session and
--to AGENT …start AGENT primed with it
--into WINDOW …send it into a running window
--copy | --print …copy to clipboard / print it (default: save + print path)
--note TEXT --summarize --dir DIR --edit (review in $EDITOR first)
Costs & limits
optimus usage spend report (--by day|month|model|agent|project|session --since 7d --json)
optimus blocks 5-hour usage blocks (-n 10)
optimus limits quota windows (Claude/Codex) and your budgets
optimus projects per-project sessions and spend
optimus statusline Claude Code status line command (records rate limits)
Setup
optimus agents detected agents and where their data lives
optimus config [init|path|edit] manage ~/.config/optimus/config.json
optimus config set KEY VALUE e.g. budgets.daily_usd 50
optimus config statusline --install let Claude Code report quota to optimus
optimus reindex drop the parse cache and rescan
optimus version
optimus help [command] this list, or one command's flags (also: optimus <command> -h)
Agent shortcuts#
Any agent name is also a command. It starts that agent in the multiplexer and attaches:
optimus claude # here
optimus codex ~/dev/web # in a folder
optimus opencode . -p "fix the build"
optimus gemini -d # start detached
Times and filters#
--since accepts 7d, 12h, 2w, 3m, today, week, month, all or a date (2026-09-01).
Session arguments accept a full id, a unique prefix (3f2a) or last.
Window arguments accept the number shown by optimus ps (3), the name, or the tmux id (@3).
JSON output#
ls, usage and projects accept --json, for scripts and status bars: