Trails for VS Code

Open Trails beside your code and toggle its terminals without stopping them. VS Code handles terminal rendering, input and resizing. There are no runtime dependencies or custom terminal renderer.

Use

These shortcuts use Control on macOS too. Both commands are available in the Command Palette; the editor title-bar Trails icon also toggles the terminals. There is no Activity Bar icon or launcher sidebar.

The first terminal opens beside your code. New Trail adds another terminal tab to the same group, initially named Trails 2, Trails 3, and so on. With the default command, each opens the Trails picker, where you can create or attach to a trail. Toggle hides all extension terminals together and restores the last-used session. Empty Trails groups are removed when their terminals hide or exit. If only one empty group remains, it is unlocked so files from Explorer can open there. Groups containing files are preserved. If a terminal is behind another editor tab, Toggle brings Trails to the front.

Hiding preserves the running processes. VS Code cannot hide editor terminals in place, so the extension moves them to the native terminal panel and hides that panel. Showing moves those same processes back to an editor group beside your code. Known limitation in v0.1.0: VS Code reveals the shared Terminal panel during these moves. It can flash briefly, hide a panel you had open, or leave the bottom panel visible after restoring Trails. Other terminal processes are not stopped. Manually opening the Terminal panel can reveal the parked sessions.

Exiting or killing the foreground command closes its terminal without leaving a shell prompt. The next Toggle starts a new one if all sessions have ended. Closing a terminal tab terminates its terminal process; Trails' agent sessions remain in tmux when its client disconnects.

These are editor terminals. Closing all other editor groups lets them expand into the available editor area. They are not a dedicated sidebar terminal.

Terminal titles

After attachment, tabs use the codebase label and stable Trails ID: trails-4552, trails-8f29, or almanac-26dd. This is the trail ID, not an agent conversation ID. Switching trails updates the title; renaming the tmux session or changing the agent's task does not replace the stable identity. Two terminals attached to the same trail receive distinct labels, such as trails-4552 and trails-4552 (2).

The picker and commands without an attached trail keep their original terminal name. The extension matches tmux clients to each terminal's process tree, so it does not guess from the working directory or from unrelated running sessions. Workspace attachments resolve through their trail metadata; maps and standalone tool windows keep a generic name because they have no single attached trail. Both current four-digit IDs and older eight-digit IDs are supported. It checks the active terminal periodically; inactive tabs keep their last title and refresh when activated, without switching tabs or stealing focus. Hide/show preserves titles and process identity.

Title lookup runs on the extension host, including Remote SSH, WSL and containers. It uses the tmux server selected by that terminal's environment. Missing tmux, missing trail metadata or ambiguous matches keep the fallback name. A transient lookup timeout preserves the last title. A custom command that SSHes to another machine, or explicitly selects a different socket with tmux -L or -S, keeps its fallback title unless that server is also selected in the terminal environment.

Preferences

Trails: Command is the single extension setting, defaulting to trails. It accepts any foreground shell command, including arguments and quoting:

{
  "trails.command": "trails"
}

For example, set it to claude --resume to launch Claude Code instead. Changes apply to new terminals. Existing processes keep running their original commands. The working directory defaults to the active file's workspace folder, then the first workspace folder. The interpreter defaults to $SHELL on macOS/Linux, or ComSpec on Windows, and runs in command mode so it exits with the command. Legacy advanced JSON settings from prototype versions are still read, but are not shown in the Preferences UI.

The shortcuts override VS Code's default Control+backslash bindings. Remap them in Keyboard Shortcuts if needed. The extension defaults add its commands to terminal.integrated.commandsToSkipShell so the shortcuts work inside terminals. If you customize that setting, include trails.toggle and trails.new in your list. terminal.integrated.sendKeybindingsToShell can also override this behavior.

Install the configured command on the machine running the extension. Trails also requires tmux and its other CLI dependencies. For Remote SSH, WSL or containers, install the extension and command on the remote host. Use an absolute command path if it is unavailable on PATH. Workspace Trust must be enabled.

Install

Install from the Visual Studio Marketplace (listed as Preview while the editor-terminal host is still evolving):

code --install-extension trails.trails-vscode

Or search for Trails for VS Code in the Extensions view. Reload VS Code if prompted. Install Trails and its CLI dependencies separately when using the default command.

GitHub Releases are for the Trails CLI only. To build a VSIX yourself from a version tag:

git checkout vscode-v0.1.0
cd integrations/editors/vscode
npm ci
npm run package
code --install-extension trails-vscode-0.1.0.vsix

Versioning

The extension version lives in package.json and CHANGELOG.md, independent of the Trails CLI. Tags use the vscode-v* prefix (for example vscode-v0.1.0). Pushing such a tag publishes to the Marketplace via Trusted Publishing; it does not create a GitHub Release.

Develop

From this directory:

npm ci
npm test
npm run test:vscode # isolated VS Code window; requires code CLI on macOS/Linux
npm run package

To launch a development window from the repo root:

code --extensionDevelopmentPath="$PWD/integrations/editors/vscode" .

The launch helper in launch.js has no VS Code dependencies and can be reused in other extensions. Branding and defaults live in package.json; the launcher does not parse Trails output or depend on its session model.

The isolated VS Code tests check single and multiple session toggles preserve the same process IDs, and successful exits, errors and kills close terminal tabs. Before publishing, check the physical shortcuts, resizing and keyboard input locally and in Remote SSH. The live title tests additionally require tmux.