VS Code reaches Troupe through a door, not a second client: the extension in clients/vscode has one command that opens anything, Troupe: Open, which types troupe --workspace <folder> into a terminal it opens at that folder, by default a tab in the editor area, one terminal per folder; its side bar shows the folder's settings as troupe config --explain --json reports them; and every release attaches it as troupe.vsix, which the installers' --vscode installs, on no marketplace yet¶
Decision 765 · accepted · 2026-10-04 · issue #378
Superseded in part
In part by 816.
- Where it lives and how it ships. A pnpm project of its own, not a package of the
GUI's workspace, which shares a protocol client the extension has no use for. TypeScript
compiled by
tsc, no runtime dependencies, so the.vsixthatvsce package --no-dependenciesmakes is its own code with LICENSE and NOTICE, copied in at packaging as every release artifact carries them. The Marketplace or Open VSX, a version check against the TUI, and telemetry are not in it, as decided on the issue; the README says there is no telemetry. Its id isobjective-mj.troupe, under the desktop app's identifier (710), and its version is VERSION without the pre-release part, kept byscripts/version.exs, becausevsce publishrefuses a pre-release version as WiX does (the desktop app's reason). Dependabot moves its tools monthly;@types/vscode, the APIengines.vscodepromises (1.93, for shell integration's events), and@types/node's major, the Node that version runs, move by hand with that line. - A line typed into the person's shell, not the TUI as the terminal's program.
VS Code disposes a terminal whose program exits, and with it the one line a failed
start prints (
troupe: could not start: …, #231); and the person's shell carries their profile and environment. The line is the program's absolute path, quoted for the shellvscode.env.shellnames (PowerShell, cmd.exe, the POSIX family, fish), thenexitwhen the status is 0, so quitting the TUI closes its terminal and a failure leaves it open with the reason. A shell whose quoting is not known here (nushell, or WSL's launcher as the default profile on Windows, whose Linux shell cannot run a Windows path) getstroupeas the terminal's program instead. --workspaceand thecwdboth.troupe --workspace DIRwas already parsed for every mode and roots the TUI's session at DIR whichever directory it starts in; it was documented only fortroupe run. The extension passes it as well as setting the terminal'scwd, so a shell whose start-up files change directory does not move the work.- Which folder. The active editor's; with none, the Troupe terminal in front, so a second press from it finds it again without asking; then the only folder; with several and nothing to go by, a question, once. One terminal per folder: a press shows it again while something runs in it, and runs the line again in it once shell integration says the line ended (a failed start). Without shell integration it is only shown. A terminal from before a window reload, which VS Code keeps with its process, is found by its name and only shown.
- A tab in the editor area, by default. A terminal in the panel cannot be tiled
with the files, and the TUI is what is being worked in, so it opens where files open:
createTerminal'slocation, a tab in the editor group in front, with Troupe's mask as its icon.troupe.openIn(editor,beside,panel) keeps the panel for whoever wants it; it ismachinescoped like the other two, so one rule covers every setting read, though where a terminal opens is no risk. - Four ways in to the one command. The mask in an editor's title bar
(
editor/title,navigation, beside other tools' icons there), which hands the command the file's URI, so the file's folder. The mask in the activity bar: a view container whose Folders view opens Troupe when it is shown, since VS Code has no activity-bar item that only runs a command; its list of folders is where a workspace of several chooses, so that way in never asks. The command palette and the status bar. And the key: Shift+Alt+T on Windows, Ctrl+Shift+Alt+T on Linux and Cmd+Shift+Alt+T on macOS. On Windows Ctrl+Alt is AltGr, and unlesskeyboard.mapAltGrToCtrlAltis on, VS Code types the character a layout gives AltGr+Shift+T (Þ on US-International) instead of running a Ctrl+Alt key; Shift+Alt+T has no default binding in VS Code 1.140. A unit test keeps every Windows key off Ctrl+Alt. - The settings shown are Troupe's answer, not the extension's reading. The side
bar's Settings view runs
troupe config --explain --json --workspace <folder>where the terminal runs (half a second here) and shows its rows: the model (provider, endpoint, whether a key is set, the three models, the named providers), what else differs from the defaults and which layer set it, the three files and whether the workspace is trusted, the warnings and refusals, and every key, folded. Merging the layers and deciding which of a repository's keys apply stay Troupe's, so the view cannot disagree with a session. It asks only while shown: when the folder worked in changes, when a file the answer named is saved, and on Refresh. A key is shown as set or not set, never even masked; a unit test fails onsk-anywhere in the rows. A.cmdtroupe(the suite's fake, or a person's own wrapper) runs throughcmd.exe /d /s /cwith the line quoted as the terminal's is, since Node runs no batch file without a shell. - A release attaches it, and one line installs it to try.
release.ymlandprerelease.ymlbuild the.vsixasdev-check.ymldoes and attach it astroupe.vsix, in the release'sSHA256SUMSwith the rest.install.sh --vscodeandinstall.ps1 -VSCodedownload it with the rest, check it, and hand it to VS Code's owncode --install-extension --force:codeon thePATH, then where VS Code's setups put it, orTROUPE_VSCODE_CLI. Without one,--vscodestops before the plan. Asked which clients to install, they ask about the extension only wherecodeis, yes by default where the TUI is being installed on a fresh machine;codeis run only then, never for the summary, since a firstcodein WSL sets up VS Code's server. A failed--install-extensionis a warning, the rest being installed, and--uninstallremoves the extension too. Each release's notes open with one line per system that installs the daemon, the TUI and the extension from that release:curl -fsSLO …/install.sh && sh install.sh --tui --vscode, andirm …/install.ps1 -OutFile install.ps1; if ($?) { powershell -ExecutionPolicy Bypass -File .\install.ps1 -Tui -VSCode }. That is Decision 682's download, then run, on one line, not a pipe into a shell: the file is whole before it runs, stays to be read, and still shows its plan and asks. Theif ($?)is needed: in Windows PowerShell 5.1 and PowerShell 7 alike, the statement after a failedirmon the same line runs, which would run an olderinstall.ps1left in the directory. - Finding
troupe, where the terminal runs:troupe.path, then thePATH, then where the installers put it, which a window older than the installer's change to thePATHwould otherwise miss. On Windows only a.exe,.cmdor.bat,.exefirst, and never a file without an extension, which Windows hands to whatever opens it (#231); a relativePATHentry is never searched. The extension is a workspace extension, so in a WSL, SSH or container window it runs, and looks, on the remote host, and a missingtroupeis one sentence that names that host as VS Code's remote indicator does, with a link to the install instructions and no terminal. - Both settings are
machinescoped. A repository's.vscode/settings.jsoncould otherwise choose the program the terminal runs, or add--auto-approveto it. With nothing read from the workspace, the extension runs in untrusted workspaces too; Troupe's own trust (troupe config trust) is what governs the repository's files. - Six build tools under licences the policy does not allow, all brought by
@vscode/vsce: Microsoft's own licence for@vscode/vsce-sign, which vsce loads to package anything, and Artistic-2.0 foristextorbinaryand four of its dependencies, through vsce's secret scan. They are recorded inscripts/licences.exsas reviewed exceptions, for approval on the pull request: none ships, and none is changed. Refused, the alternative is a packager of our own; a.vsixis a zip of the extension with two XML files.
Governs: .github/dependabot.yml, .github/workflows/release.yml, scripts/version.exs