The terminal client¶
troupe is the terminal client of the Troupe harness. Every session runs in the troupe
daemon (the troupe-daemon on this machine, or, when none is running, the same daemon
started inside troupe itself) or on a plane's worker pod, and the TUI speaks to all of
them over PROTOCOL.md: a remote session looks exactly like a local
one. It ships as one self-contained executable per platform (Linux, macOS, Windows) built
with Burrito; users need no Erlang or Elixir
installed. Every release carries one, troupe-<version>-<target> (.exe on Windows),
which the installers put on the machine with --tui (-Tui)
(quick start), and troupe update installs a newer one
(updating). Building it is in its README.
A session opens in command mode: not a chat with an agent, but one screen over
everything the session has going. A line that does not start with / is work: Enter starts
the default agent (build) on it in your checkout, as a branch (a session of its own),
and returns control at once; Ctrl-N chooses the agent instead, with its instruction on
screen, and whether it works in a worktree of its own. /plan look at the parser or
/worktree add rate limiting start one too. Every branch is a window. Branches run
concurrently; a window that needs you (an approval, a question) blinks; you activate it,
answer, and go back to what you were doing. When nothing is running the harness is truly
idle: no model calls, no tokens.
Command mode, the screen with no window activated, lists what waits on you first (the
start's questions, a window's approval or question, in the reserved colour), then a row
per branch (its agent, state, how long it has run, the last line it produced, what it used
and cost) and a row per worktree of the repository (its branch, ↑ ahead of and ↓
behind the checkout's, the lines + added and − removed, dirty or clean, whose session
and whether it is alive), under the session's model, goal, watch and budget. The session's
own lines (what its start said, what ! printed) sit above the branches; its own agent is
listed with them only once it has work of its own (troupe run's task, a loop, a watch
trigger, a session on a plane). Enter on a line starts it on build in the checkout, or on
the agent Ctrl-N chose (↑↓ the agents, PgUp/PgDn its instruction, Enter, then w a
worktree of its own or c the checkout); with nothing typed, Ctrl-N's choice waits for the
task on the command line. On a session on a plane, which runs one agent, a line is said to
it. Its keys and pages are on the terminal client's screen, and every
command line and command on the command reference.
Use¶
troupe run --headless prints the transcript, a line per event prefixed with the agent
that wrote it, the harness's notes among them (done: and the summary, a compaction, a
reply cut or empty) and each turn's cost line (turn: 3 calls · ↑ 300 sent · ...), and
exits when the agent comes to rest: when its turn ends, whether or not the model called
finish. An approval is refused, since nobody is there to answer it: pass
--auto-approve for a task that writes files or runs commands, or set auto_approve,
which --auto-approve, --watch and --full-send beat only when given. A headless run
starts no librarian: the project brief is refreshed by itself only for a session a person
opens, in a git repository, with a model to ask (memory_auto_refresh), and not again
within memory_max_age_days of a librarian that built nothing; a session that starts
none, for want of a model, because the daemon did not start it, or while a try is waited
out, says so in one line. The exit code says how the run ended:
| code | the run |
|---|---|
0 |
ended its turn, or the agent finished |
1 |
stopped short: the agent ran out of budget, refused, or gave a cut or empty reply; its last model request failed; a tool kept failing and the harness stopped the turn; the agent kept crashing and its session stopped; the turn was cancelled; the session could not start; or the connection to the daemon went and did not come back within a minute. The last line says which, and for a crash what the agent raised |
2 |
never started: the command line did not parse |
3 |
was refused an approval, with nobody to ask. Run it again with --auto-approve, or troupe resume the session to carry on by hand |
130 |
was interrupted with Ctrl-C |
troupe resume ID --headless "message" (or latest, or --private, in place of the id)
does the same for one turn of a session that already has a history: it prints that turn
alone, its turn line included, and exits with the same codes. troupe --resume is
troupe resume. A session another device holds (it sealed it last, and it is that
device's until you claim it here), or one that is erased or being erased, is refused in a
sentence that says so and suggests /new; a dormant one, asleep or archived, is opened,
and the next line wakes it. The terminal UI needs a terminal: troupe, troupe resume
and troupe run without --headless, with standard output sent to a file or a pipe, say
so in one line and exit 1 rather than draw into it.
Remote sessions¶
A session can run on a plane, a Troupe deployment, instead of this machine: a plane that knows who you are and hands out sessions, and workers that run them. Sign in once per plane:
troupe login https://plane.example
It reads the plane's /.well-known/troupe, runs the OAuth device flow against the issuer
it names, and prints a code to enter in a browser. The refresh token lands in
credentials.json in your config directory (where),
readable by your account alone (0600 on Unix, an ACL naming only you on Windows). The
file is the machine's sign-in, not the terminal's: the desktop app reads and renews the
same token, and whichever program renews it holds credentials.lock beside it meanwhile,
so the other spends the renewed token rather than a retired one. troupe whoami says who
you are and which teams you are in; troupe logout forgets one plane, troupe logout
--all every one, for the desktop app as well. What the sign-in gives the daemon is on
sessions; a daemon somebody else linked is left as it is.
troupe --remote opens HQ: the teams you are in, the profiles each can run with their
health and free capacity, and the sessions on the plane, with this machine's own in the
same list, labelled local. ↑↓ moves, ←/→ or Tab changes column, Enter opens a session,
n creates one (profile, source, visibility, prompt) and attaches to it, r refreshes.
An open remote session looks exactly like a local one: the same window, transcript,
approvals and keys. What is different:
- Browsing never wakes anything. Opening a dormant session reads it; the first thing you do (input, an approval, a todo edit, a profile switch) activates it, once, and follows the worker it is given.
- Your input appears before the server has seen it, and is reconciled when the worker accepts it. Someone else's appears when it is queued.
- What your token does not allow is disabled, with the reason on the input box: a
read-only session, or a token with only the
observescope. - If the plane goes down, attached sessions keep streaming. HQ says that creating and activating are unavailable, and still lists what it knows.
/filesand/uploadwork against the worker's checkout over the session's mount, and refresh themselves when the worker says files changed.
TLS is verified against your operating system's trust store. For a deployment behind a
private CA, TROUPE_CA_FILE=/path/to/ca.pem adds it to the trust store, never in place of
it.
Persistence¶
Every session is an append-only JSONL event log, sessions/<workspace-hash>/<session-id>/events.jsonl
in the state directory (where).
Agent and window state are folds over that log, so a crash restarts from it and troupe
resume continues running branches. Tool calls that started but never completed are run
again on resume (at least once); completed calls are never run twice.
The directory decides what you can come back to: sessions are keyed by a hash of the
workspace path, so /resume (or troupe resume with no id) lists what this directory
has (each session that said something to a model or started a branch, when it was last
touched, its branches and which of them need you or have stopped), and Enter replays the
one you pick into the window you are looking at.