CLI — agentop

agentop is a single binary. The full reference is always one command away:

agentop --help
agentop --version

The cockpit

agentop                  # opens the cockpit (same as agentop start)
agentop start --lang pt  # force Portuguese for this run
agentop tui              # alias for agentop start

Tabs, in order: Services, Sessions, Backup, the metrics tab, Hardware, Logs, Cheat sheet, Help and Contribute. The metrics tab needs no browser and has the Overview, Projects, History, Costs, Harnesses and Hardware screens, switched with 1 to 6; f filters by harness.

Key	Does
← / →	change tab
tab	change pane
enter	actions for the selected row
q	quit

Without an interactive terminal (a pipe, a systemd unit), agentop behaves like agentop server.

Local server

agentop server              # web on :47292, API and MCP on :47291
agentop server --port 4000  # API on 4000, web on 4001
agentop server --bg         # in the background, logging to ~/.agentistics
agentop status              # services and health, without opening anything
agentop restart             # restarts the service installed by autostart
agentop watch               # only the OpenTelemetry metrics daemon

Sessions

Background sessions run in tmux, on their own socket (-L agentop): they survive agentop exiting and never mix with your own tmux sessions.

agentop session <harness> [-p "prompt"] [--bg] [--model <id>] [--effort <level>] [--cwd <path>] [--name "label"] [--task "<name>"]
agentop session ls [--all] [--group <dimension>] [--json]
agentop session attach <id|name>
agentop session kill   <id|name>
agentop session rename <id|name> "label"
agentop session note   <id|name> "text"

• ls shows only what is running, grouped by project. --all adds finished, lost and closed sessions. --group takes project, tree, repo, task, harness, model, status, marked and none.
• Without --bg, the session takes over your terminal; the key to detach is printed first.
• --effort applies to claude (low, medium, high, xhigh, max) and antigravity (low, medium, high).

Several sessions at once, all under the same task:

agentop session batch --task "landing page" \
  --session "claude: write the hero" \
  --session "codex: write the tests"
agentop session open "landing page"   # reopens the whole task later

Tasks (Agentask)

agentop task                    # lists tasks with their summed cost
agentop task show <id|name>     # one task, its attempts side by side
agentop task deliver <ref>      # marks it done and attaches the git evidence
agentop task abandon <ref>      # marks it abandoned

All of them accept --json.

Claude Code in parallel

agentop hooks install     # installs a skill and a SessionStart hook into Claude Code
agentop hooks status
agentop hooks uninstall   # removes exactly what install wrote

The skill teaches Claude Code to propose splitting work across several sessions with agentop session batch; the hook tells it which sessions are already running. Nothing is written to ~/.claude before you run install, and Claude always asks for your yes before starting sessions.

Session alerts

agentop events watch --desktop   # notifies when a session waits, asks for permission or exits
agentop events status

Backup

agentop backup             # metrics plus a manifest that rebuilds your repositories
agentop backup --plan      # shows what would be written, writes nothing
agentop backup schedule daily
agentop restore <archive>

Credentials are never included in a backup.

Updates and autostart

agentop upgrade                     # updates to the latest version
agentop check-update                # speaks up only when there is a new version
agentop autostart server enable     # starts the server with the system
agentop autostart status
agentop autostart server disable