Skip to content

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; dd dismisses 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/a answer an approval (allow / deny / allow for the session). Where the daemon writes your own rule, w is Always allow: it asks where, w again for this workspace (.troupe/config.local.yaml) or g for everywhere (your config.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's publish_artifact asks 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, y publishes it for that one, n denies. An agent that named nobody has nothing picked until you do, and a is 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 (with multiple, 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, /cancel and /dismiss; @file completes paths.
  • Reading. e opens 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.log in the state directory, ~/.local/state/troupe/daemon.log on Linux and macOS ($XDG_STATE_HOME/troupe when that is set), %LOCALAPPDATA%\troupe\daemon.log on Windows; troupe daemon status prints the directory as state.
  • 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 says model error: with the reason; before that, troupe doctor in 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 config for 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 : …</em>. The page scrolls to keep the box's or the picker's cursor on screen. On a full profile Enter queues it: the curtain line says <em>waiting for a free place in code</em>, the plane is asked again as it says, and the session screen opens once it is placed. Esc on the casting steps goes back to the form and the start goes on: the form says <em>Starting <title> on <profile>…</em>, Enter there starts nothing a second time, and if you close the screen the curtain line says when it started (<code>/sessions</code> lists it) or why it did not. <code>/new --remote PROFILE</code> and <code>/new --private</code> set the chips first; <code>/new --branch</code> forks at once. HQ's <code>n</code> opens the same screen on the platform.</p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type="button" class="md-top md-icon" data-md-component="top" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../terminal-client/" class="md-footer__link md-footer__link--prev" aria-label="Previous: The terminal client"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class="md-footer__title"> <span class="md-footer__direction"> Previous </span> <div class="md-ellipsis"> The terminal client </div> </div> </a> <a href="../cli-reference/" class="md-footer__link md-footer__link--next" aria-label="Next: Command reference"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> Command reference </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> Made with <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener"> Material for MkDocs </a> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"annotate": null, "base": "../..", "features": ["navigation.tabs", "navigation.sections", "navigation.indexes", "navigation.top", "navigation.footer", "search.suggest", "search.highlight", "content.code.copy"], "search": "../../assets/javascripts/workers/search.a7633da7.min.js", "tags": null, "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}, "version": null}</script> <script src="../../assets/javascripts/bundle.c21346df.min.js"></script> <script> (function () { var box = document.querySelector(".troupe-app"); if (!box) return; var version = box.getAttribute("data-version") || "any"; var KEY = "troupe.appBanner.dismissed"; var store = null; try { store = window.localStorage; } catch (e) { store = null; } var dismissed = false; try { dismissed = !!store && store.getItem(KEY) === version; } catch (e) { dismissed = false; } if (dismissed || window.__TAURI__ || window.__TAURI_INTERNALS__) return; var ua = navigator.userAgent || ""; var phone = /Android|iPhone|iPad|iPod|Mobile/i.test(ua) || (/Macintosh/i.test(ua) && navigator.maxTouchPoints > 1); var line = box.querySelector(".troupe-app-line"); var openIt = box.querySelector(".troupe-app-open"); var install = box.querySelector(".troupe-app-install"); var copy = box.querySelector(".troupe-app-copy"); if (phone) { line.textContent = "Troupe's app is for a computer. Send yourself the link to this page to open it there."; openIt.hidden = true; install.hidden = true; openIt.nextSibling.textContent = " "; copy.hidden = false; copy.addEventListener("click", function () { if (navigator.clipboard) navigator.clipboard.writeText(location.href).then(function () { copy.textContent = "Copied"; }); }); } // Whether the app opened is a guess: an app that opens takes the focus, which the page // hears; a browser that knows no handler keeps it (or shows its own line), and Chrome's // "Open Troupe?" question takes it too, so a person who cancels that is offered nothing. openIt.addEventListener("click", function (e) { e.preventDefault(); var settled = false; var left = function () { if (settled) return; settled = true; window.removeEventListener("blur", left); }; window.addEventListener("blur", left); document.addEventListener("visibilitychange", function () { if (document.visibilityState === "hidden") left(); }); setTimeout(function () { if (settled) return; left(); line.textContent = "The app did not open, so it may not be installed here."; install.textContent = "Install it from the release page"; }, 1500); location.href = openIt.getAttribute("href"); }); box.querySelector(".troupe-app-dismiss").addEventListener("click", function () { try { if (store) store.setItem(KEY, version); } catch (e) { /* kept nowhere: shown next time */ } box.hidden = true; }); box.hidden = false; })(); </script> </body> </html>