RepoTrail

Agent-guided codebase tours inside VS Code.

RepoTrail turns a repo walkthrough JSON file into an editor-native route: your agent writes .repotrail/*.json, RepoTrail opens native git-backed diffs for change reviews or highlights tight ranges for codebase tours, shows narration, and lets you move through the route with Back/Next, CodeLens, and the sidebar.

How It Works

RepoTrail has one supported generation path: an external agent writes a complete tour JSON file.

You can use it two ways:

1. Existing workspace: open one or more project roots in VS Code, then ask your agent to write .repotrail/<tour>.json in the owning project.
2. Agent-created workspace: ask your agent to check out the needed repos or worktrees, save a .code-workspace under ~/.repotrail/workspaces/, open it in VS Code, and write the tour JSON into the owning project.

RepoTrail refreshes its sidebar library from the filesystem. Open the tour and navigate locally in VS Code.

The extension does not ship a built-in LLM provider and does not send source code to a hosted service by itself.

Author A Tour In The Current Workspace

After installing the extension, open the target workspace in VS Code, open the RepoTrail sidebar, and click Agent setup. Paste the copied prompt into your agent.

You can also run this command:

RepoTrail: Agent Setup

The copied prompt includes the complete repo-trail skill bundled with the installed extension, the open workspace roots, the tour schema, the output path, and the request to create the tour. Agents that support persistent skills can install or update it as repo-trail; other agents can apply the embedded instructions for that request. No separate download or extension server is required. Existing integrations that invoke the 0.11.0 repoTrail.copyTourPrompt command ID receive the same prompt.

Create A New RepoTrail Workspace

If you want the agent to set up the workspace too, install or paste the repo-trail skill and ask:

Use the repo-trail skill. Create a RepoTrail workspace for <repo or PR>. Check out any needed non-destructive worktrees, save the .code-workspace under ~/.repotrail/workspaces, open it in VS Code if possible, then write a RepoTrail JSON tour into the owning repo's .repotrail/ directory.

The global workspace directory is only a launch registry:

~/.repotrail/workspaces/<workspace-slug>.code-workspace
~/.repotrail/workspaces/<workspace-slug>.manifest.json

Tours still live in the project that owns them:

<project>/.repotrail/<tour>.json

Tour JSON Files

Shared tours live in the repo that owns them:

<project>/.repotrail/architecture.json
<project>/.repotrail/pr-walkthrough.json

RepoTrail accepts exported envelopes, stored records, and bare TourPlan JSON. The preferred envelope is repoTrailTour: 2 with plan.roots aliases and per-step root values for multi-root tours. Older workspaceFolder steps still work.

Features

• Full-route tours for architecture, PR/diff walkthroughs, file walkthroughs, request lifecycle traces, and bug investigation paths.
• Cross-repo tours in multi-root VS Code windows via plan.roots aliases or legacy per-step workspaceFolder addressing.
• Tight highlighted ranges with auto-captured anchors that detect code drift.
• Native git-backed full-file diff steps for PRs, commits, branch comparisons, and other change reviews. Highlight-only code stops stay available for codebase/subsystem tours unrelated to a change window.
• Sidebar route list with seen-state dimming and current-step narration.
• CodeLens controls above highlighted stops.
• Keyboard navigation with Alt+Left and Alt+Right.
• Optional narration via system speech, local Kokoro, macOS/Linux command TTS, ElevenLabs, or OpenAI TTS.
• Repository tour library backed by .repotrail/*.json across every open workspace root.
• Automatic reload when the active tour JSON changes, with the current stop preserved when possible.
• Agent-created VS Code workspace flow backed by ~/.repotrail/workspaces/*.code-workspace.
• Export to Markdown, JSON, or standalone animated HTML with browser playback, embedded code/diff frames, and standalone TTS controls.
• Automatic restoration of a tour that was still active when VS Code closed. Stopping a tour prevents it from returning on the next reload.

Security And Privacy

• RepoTrail has no local network listener. Tour authoring happens through files in .repotrail/.
• Tour step files must be workspace-relative and cannot escape their selected workspace folder.
• Hosted TTS providers are opt-in and require your own API key. Keys are stored in VS Code SecretStorage; audio requests are made by the extension host, not the webview.
• RepoTrail itself does not collect telemetry.

See PRIVACY.md for the longer policy.

Commands

• RepoTrail: Agent Setup - copy workspace details and the JSON schema for your agent.
• RepoTrail: Copy Tour From Here Prompt - copy a prompt scoped to the active file or selection.
• RepoTrail: Export Tour - export Markdown, re-importable JSON, or a browser-playable animated HTML walkthrough.
• RepoTrail: Import Tour - open a one-off JSON file stored outside an open project's .repotrail/ directory. Repo-local tours are discovered automatically.
• RepoTrail: Rename Tour - change the visible tour title without renaming the .repotrail/*.json file.
• RepoTrail: Save Tour to Repo (.repotrail/).
• RepoTrail: Manage TTS Credentials - securely store, replace, or clear an OpenAI or ElevenLabs API key.

Development

pnpm install
pnpm build
pnpm package
pnpm install-local

The primary validation gate is pnpm build. The packaged VSIX is installed locally with pnpm install-local.

Animated HTML Export

RepoTrail: Export Tour -> Animated HTML (.html) writes a standalone browser player for the active tour. The file embeds the tour route, narration, bounded code snapshots, and diff frames, so it can be opened outside VS Code or shared as a single artifact.

The exported player includes Back/Next, Play, Speak, and TTS settings. It carries non-secret VS Code TTS defaults such as provider, model, and voice. API keys from VS Code SecretStorage are not embedded; hosted OpenAI or ElevenLabs speech requires entering a key in the browser, where it is stored only in that browser's local storage. Command-based voices such as macOS say cannot run from a browser page, so exports configured for Command narration start with System speech.

Limitations

• RepoTrail plays tours; it does not generate them. Use an external agent or write the JSON file yourself.
• RepoTrail is read-only. It navigates and explains code; it does not refactor files.
• Open VSX publishing is not currently part of the release flow.