Working from the terminal
The daemon always runs headless: it logs to stderr and serves the dashboard.
To see what your agents are doing from a terminal, run itervox watch in
another shell, a tmux pane or over SSH. To act, use the
quick actions
(pause, resume, dispatch, workers, reply, approve).
itervox watch is read-only. It never takes keystrokes, never reads stdin and
never changes the terminal’s mode, so it behaves the same in a local terminal,
in tmux, over SSH and in a pipe, and Ctrl-C always stops it cleanly.
The live panel
Section titled “The live panel”itervox watch14:02:11 itervox watch · Ctrl-C to quit · feed #1842itervox · 2/2 running · 0 queued · 0 retrying · 2 waiting for you · 1 waiting for a slot · 0 blocked by dependencies · 0 pausedslot-bound: every slot is busy and work is waiting (itervox workers N adds slots)
● ENG-142 Fix the login race in the session s… coder · claude 1m05s turn 3 12.0k tok $0.42 › [Bash] go test ./internal/auth/... — Running the auth tests● ENG-139 Add a response cache codex reviewer 5s turn 1 900 tok
NEEDS YOU ! ENG-140 approval: Agent wants to run: `vercel --prod` → itervox approve ENG-140 to refuse it: itervox reply ENG-140 "<why not>" ? ENG-137 question: Which database should the migration target? → itervox reply ENG-137 "<your answer>"
EVENTS 14:01:58 #1840 ENG-131 finished: succeeded (coder · claude) 14:02:03 #1841 ENG-140 wants approval to run a held command → itervox approve ENG-140 14:02:09 #1842 ENG-139 started (codex · reviewer)- The header counts running agents against slots, queued automation
runs, retries, requests waiting for you, issues waiting for a slot and
issues blocked by dependencies. A
slot-boundline means more slots would help;dependency-boundmeans slots are free but the waiting work is blocked by its dependencies.ALL DISPATCH PAUSEDappears while all dispatch is paused, and ahub:line when this daemon serves the hub. - Each lane is one running issue: title, profile and backend, elapsed time, turn, tokens, estimated cost, and the latest activity — the last tool call (its name and target, never its output) and the agent’s current step. The activity is redacted like every other log surface.
- NEEDS YOU lists the input requests and the guardrail approvals waiting for a human, each with the command that answers it. Copy it; watch never answers by itself.
- EVENTS are the latest entries of the event feed.
Colours follow the state (running green, reviewers cyan, what needs you bold
yellow, failures red). Set NO_COLOR=1 (or TERM=dumb) for plain text.
Answering an agent
Section titled “Answering an agent”itervox reply ENG-137 "Postgres, the same instance as the app"itervox approve ENG-140 # the held command runs onceitervox reply ENG-140 "not today, the release is frozen" # refuses it, with a reasonapprove only answers an approval: when the issue is waiting for an ordinary
answer it refuses and sends nothing. GitHub identifiers start with #, which
a shell treats as a comment; the commands watch prints are already quoted
(itervox reply '#12' "…").
Following one issue
Section titled “Following one issue”itervox watch --issue ENG-142Prints the issue’s lane, then its full run log as it grows (redacted, like
itervox logs -f), interleaved with its feed events. With --once it prints
the log so far and exits.
Pipes, scripts and resuming
Section titled “Pipes, scripts and resuming”Without a terminal, watch prints plain text: the status block again (with a time stamp) only when something other than the ticking times, tokens and costs changed, and each event exactly once.
# Just the events, one per line:itervox watch --events-only | grep --line-buffered failed
# One JSON object per line, for jq or another program:itervox watch --json | jq -c 'select(.type == "event" and .kind == "input_required") | .command'Events come from the feed by cursor. When watch stops it prints where it
was, and --since continues from there — nothing missed, nothing twice:
itervox watch: stopped at feed cursor 1842; resume with: itervox watch --since 1842itervox watch --events-only --since 1842 # replay what happened since, then followitervox watch --events-only --since 1842 --once # replay and exitA dropped connection or a restarted daemon is handled the same way: watch
retries and continues after the last event it printed. If events left the
daemon’s feed window before watch read them, it says so
(… events 1843–1900 left the daemon's feed before they were read).
Over SSH and in tmux
Section titled “Over SSH and in tmux”ssh build-box 'cd ~/src/app && itervox watch' # the panel, redrawn in placessh build-box 'cd ~/src/app && itervox watch --once' # one snapshottmux split-window -h 'itervox watch' # a pane beside your editorWatch finds the daemon from .itervox/dashboard_url in the project and its
token from ITERVOX_API_TOKEN, .itervox/.env or <logs-dir>/api-token;
--workflow and --url point it elsewhere.
Every project, through the hub
Section titled “Every project, through the hub”When several projects run on one machine, the hub reaches each of them. Watch one by its hub name with a hub token:
itervox hub # the hub URL and the project namesexport ITERVOX_HUB_TOKEN=… # from: itervox token create --hub --name me --scope operatoritervox watch --project apiitervox reply --project api ENG-7 "yes" # the commands watch prints carry --project tooA viewer hub token can watch; replying and approving need an operator one.
Coming from the terminal UI
Section titled “Coming from the terminal UI”The full-screen terminal UI (itervox --tui) was deprecated in v0.2.4 and
removed in v0.3; --tui now prints a pointer to itervox watch and exits.
| Terminal UI | Instead |
|---|---|
| The running list and log pane | itervox watch, itervox watch --issue ID |
x (stop an agent) | itervox pause ID |
r (resume) | itervox resume ID |
d (dispatch from the backlog) | itervox dispatch ID |
+ / - (workers) | itervox workers N |
| Answering an agent | itervox reply ID "…", itervox approve ID |
p (project picker), w (dashboard URL) | the dashboard |