Troupe in VS Code¶
The VS Code extension opens the terminal client in a VS Code terminal rooted at the folder you are working in: by default a tab in the editor area, which you split and tile beside your files as you would a file's. It is a door to the TUI and nothing more: the sessions, the approvals and the settings are the TUI's, and the TUI is the same program it is in any other terminal. Its side bar shows the folder's settings as Troupe resolves them, and the models there are to choose from.
Installing it¶
The extension is not on the Visual Studio Marketplace or Open VSX yet. Every release and
pre-release attaches it as troupe.vsix, covered by the release's SHA256SUMS, and the
installers install it with --vscode (-VSCode on Windows): they download it with the
rest, check it, and hand it to VS Code's own code --install-extension. Asked which
clients to install, they ask about it too where VS Code is. This installs the daemon, the
TUI and the extension from one release:
curl -fsSLO https://github.com/it-minds/troupe/releases/download/<tag>/install.sh && sh install.sh --tui --vscode
irm https://github.com/it-minds/troupe/releases/download/<tag>/install.ps1 -OutFile install.ps1; if ($?) { powershell -ExecutionPolicy Bypass -File .\install.ps1 -Tui -VSCode }
The installer is downloaded whole and then run, never piped into a shell, and it shows its
plan and asks before it changes anything (Decision 682). The if ($?) is not decoration:
PowerShell runs the next statement on a line after irm fails, which would run an older
install.ps1 left in the directory. code is found on the PATH, then where VS Code's
setups put it; TROUPE_VSCODE_CLI names another. A VS Code window open already may need
Developer: Reload Window. --uninstall (-Uninstall) removes the extension as well.
The .vsix by itself installs with Extensions: Install from VSIX… in the command
palette, or code --install-extension troupe.vsix. Building it yourself is in
its README.
troupe itself has to be installed where the terminal runs
(quick start); the extension does not install it.
Opening Troupe¶
Each of these opens Troupe:
- The Troupe mask in an editor's title bar, at the top right of the editor group, beside the other tools' icons there: Troupe at that file's folder. It is not on a Troupe terminal's own tab, nor in a window with no folder open.
- The Troupe mask in the activity bar: Troupe at the folder you are working in, as the side bar opens.
- Troupe: Open in the command palette, or the Troupe item in the status bar.
- Shift+Alt+T on Windows, Ctrl+Shift+Alt+T on Linux, Cmd+Shift+Alt+T on macOS. Windows has no Ctrl+Alt key of its own: Ctrl+Alt is AltGr there, and on a layout that gives the key a character with AltGr (US-International's Þ, for one), VS Code types the character. The left Alt it is, then; on such a layout the right one is AltGr. With a terminal in front, the key goes to the terminal, as any key does.
It opens a terminal named Troupe: <folder> whose working directory is the folder, and
types one line into it:
troupe --workspace <folder>
--workspace roots the TUI's session at the folder whichever directory troupe starts
in, so the line says where the work is even when the shell's start-up files change
directory. troupe --workspace DIR does the same from any terminal.
- Where it opens. A tab in the editor group in front, with Troupe's mask on it. It
drags to another group, splits and tiles as a file's tab does. The
troupe.openInsetting makes itbeside, a group beside the one in front (opening one when there is none), orpanel, the terminal panel below the editors. A terminal already open stays where it is. - Which folder. From an editor's title bar or a row of the side bar's list, that file's or that folder's. Otherwise the folder of the file in the active editor; in a workspace of several folders that is the one being worked on. With no editor open, the folder of the Troupe terminal in front, then the only folder there is. With several folders and nothing to go by, the command palette and the key ask which, once, and the activity bar leaves the choice to the side bar's list. With no folder open it says to open one.
- One terminal per folder. Pressing it again shows that folder's terminal rather than opening a second one.
- Quitting the TUI closes its terminal, and so its tab. The line ends with
exitwhentroupeends with status 0. When it fails to start, the terminal stays open with the reason above the shell's prompt, and the next press runs it again there; that takes VS Code's shell integration, which tells the extension when the line has finished (PowerShell, bash, zsh and fish have it). Without it, a press shows the terminal and you run the line again yourself. - The line is typed for the terminal's shell: PowerShell, Command Prompt, bash, zsh,
sh or fish, with the program's full path and the folder quoted for that shell. A shell
it does not know how to quote for (nushell, or WSL's own shell as the default profile on
Windows) gets a terminal that runs
troupedirectly instead, which closes whentroupeexits, whatever its status.
Troupe's other commands¶
Four more commands in the command palette type one of troupe's other command lines into
the same terminal, Troupe: <folder>, for the folder chosen as above (Decision 808):
| Command | Types |
|---|---|
| Troupe: Resume Last Session Here | troupe resume --workspace <folder>: the session last worked in there, with the session picker open |
| Troupe: Run a Task… | asks for the task, then troupe run --workspace <folder> -- "<task>": a session started on it, in the TUI |
| Troupe: Doctor | troupe doctor --workspace <folder>: the setup checked, one line a check |
| Troupe: Open Settings | troupe config --workspace <folder>: the providers and models resolved there, or their setup on a first run |
- The terminal. When there is none, it is opened as Troupe: Open opens it. When one is there and idle (a report ended, or the TUI failed to start), the line is typed into it. When something runs in it, the TUI most likely, it is shown and nothing is typed into it, since the keys would go to the TUI, and a message says so. Telling idle from busy takes the shell's integration, as above; without it, a terminal that has had a line is taken for busy.
- Which close it. Resume and Run open the TUI, and
troupe.argsis added to them as to Open; quitting the TUI closes the terminal. Doctor's and Open Settings' line has noexit: the terminal stays with the report in it, the shell's prompt under it. - The task comes after
--, so a task that starts with a dash is the task. It is quoted for the terminal's shell, quotes,&,%and$included. A key bound totroupe.runcan give the task as itsargs. A line break goes through as one in PowerShell, bash, zsh, sh and fish; Command Prompt cannot carry one in a command line, and a space stands for it there.
Ask Troupe about a file¶
Ask Troupe About This File is on a file's menu in the explorer, in an editor (a right-click in the text) and on its tab. It opens Troupe at the folder the file is in, as Troupe: Open would, with the file's path in the TUI's prompt and the cursor after it, not yet sent:
troupe --workspace <folder> --prompt "@src/app.ts "
Type the question and press Enter. The path is written as the TUI's own @ completion
writes it: from the folder, with forward slashes. One with a space in it is put in double
quotes (@"docs/release notes.md"). A folder in the explorer has Ask Troupe About This
Folder instead, which writes @src/. In the command palette, the file is the one in the
active editor.
When Troupe already runs in that folder's terminal, nothing can be typed into it from outside: the terminal is shown, and the message says what to type into it.
Troupe in the terminal's profile menu¶
Troupe is one of the integrated terminal's profiles (Decision 816): in the menu of the
arrow beside the terminal panel's +, and in Terminal: Create New Terminal (With
Profile). It opens a new terminal named Troupe: <folder> whose program is troupe
itself:
troupe --workspace <folder>
with troupe.args after it, in the folder.
- Which folder. As Troupe: Open chooses it: the active editor's, then the folder of the Troupe terminal in front, then the only folder; with several and nothing to go by, it asks which. In a workspace of several folders, Create New Terminal (With Profile) asks for a folder of its own first, which VS Code does not hand to an extension's profile, so Troupe still goes by the editor, or asks.
- Where it opens. Where the menu was: the panel from the panel's menu, the editor area
from a terminal tab's there.
troupe.openInis for Troupe: Open. - A new terminal each time. Picking it opens another Troupe even where the folder has one, as any profile opens another shell. Troupe: Open and the other commands go on using the folder's first.
- No shell under it. Quitting the TUI closes the terminal. A TUI that fails to start closes it too, and VS Code says only the exit code: Troupe: Open runs the same line in your shell, which keeps the reason.
troupeis found as for Troupe: Open, and run as it is. A.cmdor.batruns throughcmd.exe, quoted as the Settings view's call is. When none is found, the same sentence says so, and no terminal opens.
Opening Troupe with the folder¶
troupe.openOnFolderOpen, off by default, opens Troupe as Troupe: Open would when VS
Code opens a folder or a workspace (Decision 816):
- The folder is chosen as for Troupe: Open: the file in front, otherwise the only folder; a workspace of several folders with no file open asks which, once.
- Not again after a reload. VS Code keeps a terminal, and the TUI in it, across a
window reload, but gives it back under its shell's name (
pwsh), notTroupe: <folder>. So the extension keeps the process id of each folder's terminal in VS Code's storage for the workspace, and knows the terminal by it: when one is there as the window opens, nothing more is opened, and Troupe: Open shows it. After VS Code is closed and opened again, the old TUI has ended with it, and Troupe opens afresh. - Not in a workspace you have not trusted. A program started because a folder was opened is what VS Code's Restricted Mode holds back, as it holds back a task set to run when a folder opens. Trusting the workspace, at VS Code's question as it opens or later, opens Troupe then. Troupe: Open works in either.
- Only yours to turn on. Like the other settings it is a user or remote setting, so a
repository's
.vscode/settings.jsoncannot start Troupe for whoever opens it.
There is no "ask" value: an answer per folder would have to be kept somewhere, and the extension keeps nothing. A folder added to the workspace later does not open Troupe.
The Troupe side bar¶
The Troupe mask in the activity bar opens Troupe, as above, and a side bar of two views.
Folders lists the workspace's folders, those with a Troupe terminal marked open. A click on one opens Troupe there, or shows its terminal. In a workspace of several folders with no file open, this list is where you choose.
Settings is what Troupe says its settings are for the folder you are working in (the
active editor's, then the Troupe terminal's in front, then the first), from
troupe config --explain --json run on the machine the terminal runs on. The extension
reads no config file itself, so what the view shows is what a session there would get,
layers merged and untrusted keys left out as Troupe decides
(configuration.md).
- Model: the provider, the endpoint, whether a key is set, the default, cheap and
expensive models, and the named providers. Each says which layer set it:
default,org,user,project,local,env,cliorenforced. - Models: the models there are to choose from, with their
windows and prices, from
troupe models --json. - Changed from the defaults: every other key a file or the environment sets.
- Files: your organisation's managed file and, signed in, its plane's document; the
user file, the project's
.troupe/config.yamland the local.troupe/config.local.yaml. A click opens one; one that is not there opens as a new file, which saving makes. Under them, whether the workspace is trusted: until it is, its own files cannot set the keys that page lists, the provider, endpoints and keys, approvals, watch, MCP servers and paths among them. - Problems, when there are any: the files' warnings and refusals. A click opens the file at the line.
- All settings, folded: every key and the layer it came from.
When the configuration does not load, the view says so in place of those groups,
The configuration did not load, with each error troupe config --explain reports under
it: what is wrong and the file and line it is at, which a click opens. The Models group
is still there, saying why troupe models could not list them.
Hover a row for the value each layer gave it, and why a repository's value was ignored. A click on a row opens the file that set it. The view asks again when the folder you are working in changes, when one of those files is saved in VS Code, and on Refresh in its title bar; never while it is hidden. A key is never shown, masked or not: the view says only whether one is set.
The Models group¶
Under the model in use, Models is what troupe models --json --workspace <folder>
says that folder's configuration can address (Decision 794): what each named provider
declares, the models the config names or prices, and what each provider's own list has.
- Each model with its window and its price in dollars a million tokens, in/out, as
troupe modelsprints them, and where they came from: the provider's list or your config (a price frommodels.pricessays so).no keywhen its provider has none. - The default, cheap and expensive models are starred and say which they are. A role you have not set is the default model's, so that one says all three.
- A model its provider does not serve has a warning and says so, with what the
provider does serve on hover. It shows no window:
troupe modelsgives it none. A turn on it would fail. - Each provider's list: how many models it listed and when, or, when it did not answer, why, and what is still kept from before.
Hover a row for the whole of it. Long lists (more than 20 models) start folded.
The group asks with the rest of the view, without --refresh: troupe models asks the
providers again itself when what it keeps is stale (missing, a day old, not from the
providers the config now names, or without a model the config sets), and asks again a
provider that did not answer last time. The button on the group's own row,
Ask the Providers for Their Models, runs troupe models --refresh, which asks every
provider now, with your keys. When troupe models fails (a config that does not load, a
troupe older than 0.8.3, which has no --json), the group is one line saying why, the
rest on hover; a key is never in it, even where a reason would quote one.
Finding troupe¶
In this order:
- The
troupe.pathsetting, when it is set: a path (~/is your home directory), or a name looked up on thePATH. - The first
troupeon thePATH. - Where the installer puts it:
%LOCALAPPDATA%\Programs\troupe\troupe.exeon Windows,~/.local/bin/troupeon Linux and macOS. A VS Code started before the installer changed thePATHdoes not see the change until it is restarted; this finds it anyway.
On Windows only a .exe, .cmd or .bat is run, and troupe.exe is preferred. A file
named troupe with no extension is never run: Windows cannot run one, and handing it to
the shell opens it in whatever program is associated with it, which is how an editor once
opened instead of Troupe (#231). Relative entries on the PATH are skipped.
When none is found, one sentence says so, with a How to install button that opens the install instructions, and no terminal is opened. The Settings view says the same sentence.
Settings¶
| Setting | Default | |
|---|---|---|
troupe.path |
empty | The troupe program to run: a path, or a name looked up on the PATH. |
troupe.args |
[] |
More arguments for troupe: ["--no-mouse"] lets the terminal's own selection work, ["--watch"] starts in watch mode. |
troupe.openIn |
editor |
Where the terminal opens: editor, a tab in the editor group in front; beside, a group beside it; panel, the terminal panel. |
troupe.openOnFolderOpen |
false |
Open Troupe when VS Code opens a folder or a workspace. |
All four are user and remote settings only (machine scope). A repository's
.vscode/settings.json is not yours to trust, and it cannot choose the program the
terminal runs, add --auto-approve or --full-send to it, nor start Troupe as it is
opened.
The shell Troupe: Open types into is VS Code's default terminal profile (Terminal: Select Default Profile); the extension has no setting of its own for it.
Remote development¶
In a WSL, SSH, dev container or Codespaces window, the integrated terminal runs on the
remote host. So does the extension (it is a workspace extension), and VS Code offers to
install it there; it then looks for troupe on that host, the TUI it opens works on
that host's files, and the Settings view is that host's configuration. The Troupe profile
runs that host's troupe, and troupe.openOnFolderOpen, as a remote setting, opens it
there. When troupe is
missing there, the message names the host as VS Code's remote indicator does:
Troupe isn't installed in WSL: Ubuntu (no troupe on the PATH, nor where the installer puts it).
Install it on that host with install.sh and press Troupe: Open again.
What it does not do¶
It collects nothing and sends nothing anywhere: no telemetry, no network request of
its own. It reads its four settings, looks for troupe on the disk, types a troupe
command line into a terminal or starts troupe as a terminal's program, keeps the process
id of each folder's Troupe terminal in VS Code's storage for the workspace (to know it
after a window reload), and runs troupe config --explain --json on the same machine for the
Settings view, which reads the config files and sends nothing, and troupe models --json
for its Models group, which asks your providers what they serve when its list is stale,
or when you press the group's button, as troupe models does in a terminal.
Not yet: changing a setting, or trusting the workspace, from the Settings view; and a version check against the TUI. The panel that would show a session inside VS Code over the daemon's Agent Client Protocol is a later version.