The terminal client's screen¶
What troupe, the terminal client, puts on the screen once a
session is open, and the keys and pages it has: the keys, colours, tokens and cost, the
observer, the command palette, the settings page, watch mode, the agent picker and the
new-session screen. Installing it, the command lines and sessions on a plane are on
its own page. How it draws a turn is on reading a
transcript; its pages for artifacts, memory and profiles
are on artifacts, memory and
profiles.
Keys¶
- Windows.
1–9, Enter, or a click on its row or tile activates a window; Esc returns to the command line.xx(x twice) cancels and removes the window;dddismisses a finished one, keeping its worktree. Tab chooses the agent the window runs, each with its instruction beside it (/plan→ Tab,build→ "go" is plan-then-build; the title says which agent runs). - Answering.
y/n/aanswer an approval (allow / deny / allow for the session). Where the daemon writes your own rule,wis Always allow: it asks where,wagain for this workspace (.troupe/config.local.yaml) orgfor everywhere (yourconfig.yaml), Esc back; a refusal (rules managed by the platform, a workspace not trusted, a pod, whose rules are its profile's) is said in the daemon's words. Where two or more people steer the session, an answered question says who answered it. An agent'spublish_artifactasks whom the artifact is for: the window shows the publication (its title, kind and files, whom the agent proposed it for and whose) over the audiences you have — only you, everyone at the organisation, each of your teams as the team's and as yours, each profile — the proposal picked; a digit picks another,ypublishes it for that one,ndenies. An agent that named nobody has nothing picked until you do, andais not offered for it. A new version of an artifact offers no ownership: whose it is does not change with a version. Typing and Enter sends input or answers a question; when a question offers options a digit picks one (withmultiple, digits tick and untick and Enter sends the ticked set). Alt-Enter or Ctrl-J puts a newline in the box instead of sending. - Completing. Tab on the command line completes command names and the window paths
for
/merge,/discard,/canceland/dismiss;@filecompletes paths. - Reading.
eopens the turn you are reading, every frame of it, and closes it again; Ctrl-Y copies the transcript you are reading to the clipboard. - The task list.
/todo complete <n>,/todo cancel <n>(the task's number in the side panel) and/todo add <text>edit the activated branch's. - Quitting. Ctrl-C twice,
/quit, Ctrl-D or Ctrl-Q.
Any other command typed into a window's box runs as it would on the command line, on that
window where it takes one (/copy, /merge); a line that names no command (/usr/bin is
missing) goes to the window's agent. x and d are double presses because the window
they act in is also where you type: the first press puts the letter in the box, which says
what a second would do, and anything else you type (a reply beginning "do it" or "drop
that") keeps the letter as text.
Selecting text with the mouse. Drag across the pane to highlight; releasing the
button copies it, rails and line numbers stripped, and Ctrl-Y copies the selection while
one is up (Esc clears it). Troupe owns the selection because mouse reporting, which makes
tiles clickable and the wheel scroll, takes click-and-drag from the terminal. For the
terminal's own (rectangular blocks, the tiles or the observer), hold your emulator's
modifier (Option on iTerm2 and Terminal.app, Shift on GNOME Terminal, Konsole and most X11
terminals), or turn mouse off (troupe --no-mouse, or /settings); windows are still
1–9, and the pane still scrolls with PgUp/PgDn, ↑/↓ and End. With nothing selected,
Ctrl-Y and /copy copy a whole transcript, which no drag across a scrolling pane can.
When nothing happens after a prompt¶
You typed a line, and nothing: no output, no error. The line under the turn says which of three things is going on, and the box that follows at forty-five seconds (what it says) says what to do.
the daemon has not sent the model request yet. The daemon took your line and is still preparing the turn, or is stuck before it: reading the workspace's instructions, the memory, the organisation's files, or waiting on an MCP server. Esc cancels the turn. The daemon's log says what it was doing:daemon.login the state directory,~/.local/state/troupe/daemon.logon Linux and macOS ($XDG_STATE_HOME/troupewhen that is set),%LOCALAPPDATA%\troupe\daemon.logon Windows;troupe daemon statusprints the directory asstate.no answer from <host> yet. The request went out and the model's host has sent nothing back. The daemon gives up on its own after a while and the window then saysmodel error:with the reason; before that,troupe doctorin another terminal asks the same provider for a token with your key and says in one line whether the key, the address and the network are good. A gateway or a proxy that accepts the connection and never answers looks exactly like this.model error: <sentence>. The provider refused the request: the sentence is the provider's, and the line under it says the next step where there is one (troupe configfor a missing key; the key to check for one refused).
Nothing you type is lost: a line sent while the turn waits is queued and goes next, and Esc cancels the turn and keeps the session.
Colours¶
The themes are the desktop app's, from the same design tokens: Afterglow by default, or
Signal, Footlight or Limelight, the theme setting in /settings, which is the desktop
app's appearance setting too, so a theme picked in either is the one both draw in. In
Afterglow cyan is the machine working, and pink is for one thing only, a window that needs
you: its border and title (blinking about once a second; the blink setting turns that
off), the approval or question waiting in it, and the status line's count. Each theme
keeps its own reserved colour (Signal's magenta, Footlight's amber, Limelight's lime) for
the same thing. Every window carries the mark in its top right corner, and at the start of
its row in command mode: ◐ ◓ ◑ ◒ turning while its agent works, ◑ in the reserved colour
while it needs you, ⏺ done and not yet read, ○ at rest or not yet asked anything, ✗
failed.
Troupe uses as many colours as the terminal says it has: exact colours where COLORTERM
is truecolor or 24bit and in Windows Terminal, the nearest of 256 where TERM names
256color, the terminal's own sixteen otherwise, and none under NO_COLOR. It paints no
background but a frame's, one step from the terminal's own, with exact colours and 256
(with sixteen or none the rail alone marks a frame), so it sits on whatever theme the
terminal has; a light background reported in COLORFGBG gets the light values.
TROUPE_COLORS overrides what the terminal says: truecolor, 256, 16 or none, and
light or dark (TROUPE_COLORS=256,light).
Tokens and cost¶
A tile reads ↑4.4k ↓3.1k: tokens sent and received, the whole session's, ↑ what the
provider billed at close to full price. Input served from its prompt cache is reported
apart, as cached in the side panel and the observer's detail, and budgets spend the
billed part, so re-reading a cached prompt does not exhaust max_input_tokens. What one
turn cost (what a call costs) the
side panel says under This turn, with the session's totals under Session and, once
a limit is near, how near:
This turn:
3 calls · $0.04
↑ 300 sent · 3.0k cached
↓ 120 received
Session:
41 calls · $0.61
↑ 1.2M sent · 310.0k cached
↓ 19.0k received
⚠ 82% of input tokens
While the next turn runs, This turn says said when it ends. Below 100 columns there is
no side panel, and the turn's cost is a line under the turn instead: turn: 3 calls · ↑ 300
sent · 3.0k cached · ↓ 120 received · $0.04.
Observer¶
/observer is the overview across branches: every root agent with the subagents it
delegated to nested under it, each with what it is doing now (thinking, the tool it is
running, needs you), how long it has been at it and what it has spent. The panel beside
the tree details the selected agent: its definition and depth, its branch, whether that
branch is in your checkout or a worktree (and which), the model it called, its task list,
anything it is waiting on, and its recent tool calls. ↑/↓ moves, Enter opens that
agent's branch window, Esc goes back.
Command palette¶
/ on an empty command line, Ctrl-K with nothing typed, or /help opens a popup listing
every command in sections (Session, Navigate, Workspace, Setup, Agents, one entry per
agent with its description, Custom, the commands you and the repository wrote, with the
file each came from, and Quit), each with a one-line description, and the selected one
explained beside it with an example. Typing filters by name, alias or description (mer
narrows to /merge); ↑/↓ and PgUp/PgDn move; Enter runs the command, or leaves it on
the line when it needs an argument; Tab or Space leave it on the line too, so /merge 2
types as it always did; Esc goes back. A command that cannot run now (one that acts on a
window when none is activated, or a local one in a plane session) is shown greyed with the
reason. The list is the daemon's (commands.list), so the desktop app shows the same.
Settings page¶
/settings lists every setting with its value and the file it came from, and help beside
it: what the selected setting does, and the commands, keys and concepts worth knowing.
↑/↓ moves; Enter toggles a boolean, opens a menu (the models, and the provider, each
type saying what else it needs) or edits a value; s changes which file a change goes to;
PgUp/PgDn or the wheel scrolls the help; Esc goes back. The page and the desktop app read
and write through the daemon, so they always agree
(settings in both clients).
/models opens the model menu directly (models).
Watch mode applies to the running session at once, and so do the theme, blinking and
transcript detail (quiet, tools or everything, typed), which the screen draws by
unless /detail set this session's own; everything else applies to sessions and branches
started from then on. A change is written by its current name (models.default, never the
old model). Environment variables still win over every file, so a setting masked by
TROUPE_MODEL is saved but not in effect, and the status line says so.
Watch mode¶
A comment ending in AI! is a change request and starts a quick branch; AI? is a
question and starts an answer branch, which cannot edit; bare AI comments are
collected as context. The branch works in the checkout the comment is in, its window opens
as quick-1 (and so on), and the line under the screen says which file and comment
started it; the session's own agent is told nothing. Both agents run on the cheap model
with few turns, since saving a comment is a cheap gesture and the branch it starts should
be one too. For something heavier, redefine quick or answer in .troupe/agents/ or
your own agents/, which is what /quick starts too.
Anything that writes a file can write a comment, so a branch a comment started asks before
every write, edit and shell command, whatever auto_approve says, until you set
watch_auto_approve: true. The status line says whether the workspace is watched,
whichever client turned it on, and /watch turns it off. On Linux, native watching needs
inotifywait; without it Troupe falls back to polling and says so.
Agents¶
/agents is the agent picker Ctrl-N and Tab open, at the manager's density: every agent,
the subagents too, each with where it comes from in the four words (Shipped, Your
organisation's, Yours, This repository's), its mode, model and tools, whether it is
read-only, its cap on turns, what it stands in for and which windows run it, and the files
that could not be read after them; Enter reads one's whole instruction and b starts a
branch on it. e opens it in your editor (VISUAL, then EDITOR; Notepad or vi
without either) and the daemon checks what you saved: refused, the errors are on the page
and your edit is kept for the next e; accepted, you pick where it goes, r the
repository's .troupe/agents/ or m your own agents/, after it says which tools it
would run without asking, and asks again when the save adds one. c copies one into the
repository in one key, n makes a new agent from the one selected (one Troupe ships or
your organisation's as well as your own) under a name you type, x deletes a copy and
says what answers to the name after. n is the picker's everywhere it opens. A save comes
back to the picker on what was saved, so Enter, or b, starts on it at once. A bundle's agents, and every agent on a pod, are read-only here
and say where they are changed. What a definition holds, and the built-ins, are on
agents, commands and workflows.
A new session¶
/new opens the new-session screen with the message box first. Under it one sentence
says how the session will run, Runs [on the platform] with [code] as [build (default)] ·
everyone on core can open it (or Runs [on this computer] in [folder] as [build] · only
you can open it). On the platform the agent is the profile's default until you pick one,
and the platform fills it in. Tab moves to the chips and on to CALLED, ←→ between the
chips, Enter opens the picker under the sentence: where it runs (On this computer is
greyed, with why, until the daemon link is up, and switches on by itself once troupe
daemon runs), the recent folders, the profiles with their room (FULL in amber), the
agent (on this computer the agent picker above). A line under the sentence says why the
profile was picked: the last you used while it has room, else the first with room; or
why nothing can start there: not signed in (troupe login), a sign-in run out, the
plane's error, a profile you may not use. --private is this computer's: a platform
session from this screen is the team's. @profile, #agent, /local and /platform typed in the box set the chips and are
taken out before the agent reads it; in this box @name naming a profile is not a file
path, and /local is not a command. CALLED is the first line until you edit it.
Where more than one of your teams may use the profile, the sentence ends everyone on [which team?]
can open it and the team is a fourth chip: Enter asks which team the session is for first (its
budget pays, and everyone on it can open it), the pick starts it, and Esc goes back to the form
without starting. The team is kept for that profile on this machine and shown on the chip next time,
where you can change it. troupe run --team NAME says it for a script; without it a run on such a profile stops and names the teams.
Enter starts it; Ctrl-J is a new line, as on the command line (Shift or Alt with Enter
too, where the terminal tells them from Enter; Windows Terminal does not). A typed digit
types: Tab past CALLED reaches the recent sessions, where ↑↓ and Enter, or 1-3, set
the chips like one (its where, folder, profile and agent), and the line under the
sentence says Like /sessions lists it) or why
it did not. /new --remote PROFILE and /new --private set the chips first; /new --branch
forks at once. HQ's n opens the same screen on the platform.