CodeTrail VS Code Extension
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
.md doc 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's OpenCodeService to generate walkthrough plans
- Both sources (Markdown + AI) produce the same
WalkthroughPlan schema
- Error handling: VS Code notifications for all failure cases (not installed, timeout, invalid JSON, cancellation)
- Logging: dedicated "CodeTrail" OutputChannel
| |
