botctl docs

botctl helps you keep Claude Code, Codex CLI, OpenCode, Pi, and Antigravity sessions visible and controlled inside tmux.

Claude Code panes get the full guarded automation path. Codex CLI panes are classified from captured terminal screens and can use YOLO for command permission approval. OpenCode panes are discovered passively for dashboard visibility, recent-message context, state classification, and tmux window status. Pi panes are discovered passively from ~/.pi/agent/sessions for dashboard visibility, recent-message context, state classification, and tmux window status. Antigravity (agy) panes are discovered passively for dashboard visibility, state classification, and pane-scrape last-message extraction.

Use botctl when you want to:

start one local runtime that owns observation and automation
open a live dashboard and see what Claude Code, screen-detected Codex CLI, resolvable OpenCode panes, Pi panes, and Antigravity panes are doing
turn on yolo for guarded Claude and Codex permission approval
run serve for a runtime-backed foreground event stream or localhost HTTP API
export the latest persisted assistant reply with last-message

Choose a command

Need	Start with	Then read
Watch all known panes and toggle YOLO	`botctl dashboard`	Workflows
Babysit one pane or workspace	`botctl yolo --pane %19`	Automation
Stream live observations	`botctl serve --session demo --format jsonl`	Serve mode
Submit or stage a prompt	`botctl submit-prompt ...`	Prompt handoff
Recover from a blocker	`botctl approve --pane %19`	Troubleshooting
Export the latest assistant reply	`botctl last-message --pane %19`	Command reference

Provider support

Provider	Dashboard	Classification	YOLO	Prompt submission	`last-message`
Claude Code	yes	yes	yes	yes	yes
Codex CLI	yes, from screen capture	yes, from screen capture	command permission approval only	no	yes
OpenCode	yes, after safe title plus cwd resolution	limited passive state from SQLite	no	no	yes
Pi	yes, from JSONL session matching	limited passive state from JSONL	no	no	yes
Antigravity	yes, from process-name plus state-dir detection	passive state from frame capture	no	no	yes, via pane-scrape when rule boundaries are visible

Main commands

`runtime`

The command that owns the live control plane.

holds the authoritative pane snapshots in memory
runs the shared observation and guarded action loop
supervises yolo centrally instead of letting each client invent its own view
listens on <state-dir>/runtime.sock
starts in a hidden tmux session by default, with runtime stop to shut it down and runtime --foreground for direct ownership

`dashboard`

Use this first when you have multiple tmux panes open.

Shows Claude Code panes, screen-detected Codex CLI panes, passively resolvable OpenCode panes, Pi panes, and Antigravity panes across workspaces.
Shows state, age, branch, recent context, pane PID, CPU, memory, observed Cook time, and safe actions.
Lets you jump into a pane and toggle YOLO for Claude Code and Codex panes.
Can run persistently inside a tmux popup.

`yolo`

Use this when a pane is safe to babysit.

Acts only after classification finds a supported state.
Scopes automation to one pane, all panes, or one workspace.
Approves Claude permission dialogs, dismisses Claude surveys, and approves Codex command permission dialogs.
Refuses ambiguous targets and unsupported states.

`serve`

Use this when another tool needs live state.

Streams human-readable or JSONL events for one tmux session.
Can expose a localhost HTTP API while the foreground process runs.
Reads shared runtime state instead of owning an independent observation loop.

Start here

Getting started — fastest path to a useful first run
Workflows — the main operator loop with dashboard, yolo, and serve
Command reference — syntax and flags, with the important commands first
HTTP API reference — routes, payloads, response shapes, and current safety limits

Install

cargo install botctl

Quick start

botctl dashboard
botctl yolo --pane 0:6.0
botctl serve --session demo --format jsonl

Those commands auto-start a managed runtime when needed. Use --unmanaged if you want them to require an existing runtime instead.

More detail when you want it

Serve mode — how the runtime-backed facade behaves today
HTTP API reference — the localhost control surface exposed by serve --http
Prompt handoff — prompt staging and editor flow
Automation — guarded workflows and keybinding behavior
Troubleshooting — when a pane is weird or blocked

Deeper docs

Plans and scope

Keep docs here aligned with shipped behavior.
If a flow is not implemented yet, link to the plan instead of describing it as current behavior.

Planning docs still live in the repo root:

These remain the source of longer-term plans:

Choose a command​

Provider support​

Main commands​

runtime​

dashboard​

yolo​

serve​

Start here​

Install​

Quick start​

More detail when you want it​

Deeper docs​

Plans and scope​