Interactive AI walkthroughs for any codebase.
Features
- AI Walkthroughs — Ask OpenCode CLI to analyze your repo and generate a step-by-step walkthrough
- Markdown Walkthroughs — Parse a
.mddoc into an interactive walkthrough - Interactive Playback — Open files, jump to symbols, highlight lines, narrate
Getting started
Prerequisites
- OpenCode CLI installed and authenticated (for AI walkthroughs)
- VS Code 1.95+
Installation
cd apps/vscode-extension
pnpm build
pnpm package # produces codetrail-0.1.0.vsix
Install the .vsix in VS Code:
code --install-extension codetrail-0.1.0.vsix
Usage
- Open a workspace folder
- Click the CodeTrail icon in the Activity Bar
- Click Start Walkthrough
- Choose AI (OpenCode)
- Enter a feature name (e.g. "Key Rotation", "Login", "Checkout")
- The walkthrough plan appears in the sidebar with all steps
Configuration
Open Settings > Extensions > CodeTrail:
| Setting | Type | Default | Description |
|---|---|---|---|
codetrail.openCodePath |
string | "opencode" |
Path to the OpenCode CLI binary |
codetrail.openCodeArgs |
string | "" |
Extra args before run (e.g. for nix: nix run ~/repos/oc#... --) |
codetrail.openCodeEnv |
object | {} |
Environment variables to pass to OpenCode CLI |
codetrail.timeoutMs |
number | 60000 |
Timeout in ms for CLI invocations |
codetrail.logLevel |
string | "info" |
Log level: debug, info, warn, error, silent |
Nix-based OpenCode
If you use OpenCode via nix run:
{
"codetrail.openCodePath": "nix",
"codetrail.openCodeArgs": "run ~/repos/oc#opencode-juspay-oneclick --"
}
Architecture
The extension:
- Registers a webview view in the Activity Bar sidebar
- Uses
@codetrail/ai'sOpenCodeServiceto generate walkthrough plans - Both sources (Markdown + AI) produce the same
WalkthroughPlanschema - Error handling: VS Code notifications for all failure cases (not installed, timeout, invalid JSON, cancellation)
- Logging: dedicated "CodeTrail" OutputChannel