AgentReplay for VS Code

Record, inspect, safely replay and compare AI agent runs inside VS Code. Runs stay on the machine running the extension host. The extension includes its Go runtime; users do not need Go, Node.js, Docker or Python unless their own agent uses them.

Install and use

Install the matching platform VSIX using Extensions: Install from VSIX..., then open the AgentReplay activity-bar view.

The Actions section keeps the offline demo, comparison, process recording and runtime terminal accessible above Runs, even after your first run. These actions are also available from the Command Palette and the Runs view menu.

1. Run AgentReplay: Run Offline Demo to create a sample run and replay without network calls or model credentials.
2. Select a run to inspect its trace. Right-click for Open Event Timeline, Replay Safely, or Analyze Run.
3. Run AgentReplay: Compare Runs to view the behavioral report and native editor diff.
4. Run AgentReplay: Record Agent Process and supply an executable plus a JSON array of arguments, such as python and ["agent.py"]. Recording runs as a VS Code task with visible output and the normal task Stop control.
5. Use AgentReplay: Open Runtime Terminal for the complete CLI (agentreplay help), SDK/proxy workflows, archive import/export, policy analysis and licensing.

The run tree and run pickers load 100 runs at a time with a Load More action. Recording completion refreshes the tree; refresh after external CLI operations. Comparison opens the behavioral report beside a native diff of both event timelines. Timelines paginate events and reject incomplete results above 50,000 events or 32 MiB; use CLI export for larger runs. Analysis results are read-only JSON documents. This version replaces the web dashboard with native views; it does not reproduce its graphical charts, live browser controls or prompt editor.

Local runtime and data

The runtime starts on demand, binds to a random 127.0.0.1 port and requires a random per-session API key. It exits when the extension closes its input pipe, including an Extension Host crash. Stop Runtime stops the managed server; recording tasks and user terminals have their own VS Code lifecycle controls.

Each workspace uses a separate runs-data directory under VS Code's extension workspace storage, and the runtime terminal opens there. With no workspace, global extension storage is used. Existing repository data/ and .env files are preserved but are neither loaded by the managed server nor included in the package. To bring existing runs across, export/import .areplay archives using the CLI. Existing data formats and server-side license checks remain unchanged.

Recording uses the selected workspace folder as its working directory. In an empty VS Code window, recording tasks and runtime terminals start in your home directory, as required by VS Code; AgentReplay data still goes to extension storage.

Runtime terminals receive AGENTREPLAY_ENDPOINT, AGENTREPLAY_SERVER_URL and the session API key for SDK and live CLI access to the managed local server. Open a new runtime terminal after stopping and restarting the server so it receives the new port. Run agentreplay help there to discover the complete CLI. The recorder passes trace scope to the recorded child; it keeps the existing credential filtering for child processes.

Workspace Trust is required. Desktop VS Code and a native remote Extension Host (SSH, WSL, containers) are supported; install the package matching the extension host, not the desktop client. Browser-only vscode.dev and virtual workspaces are not supported. Runtime API credentials are never placed in workspace settings or editor documents. Only explicitly requested recording tasks execute an agent process.

Build and test

Development requires Node.js 22+ and the Go toolchain declared in go.mod.

npm.cmd ci --ignore-scripts
npm.cmd run build
npm.cmd test
npm.cmd run test:integration
npm.cmd run test:vscode
npm.cmd run package

Press F5 to launch an Extension Development Host; the launch configuration builds the runtime first. The host test opens a separate VS Code test window and tests activation, demo, native run tree, trace/timeline documents, replay, comparison/diff, analysis, terminal environment, recording output and task Stop.

npm run package -- linux-x64 builds a platform-specific VSIX. Supported build targets: win32-x64, win32-arm64, linux-x64, linux-arm64, darwin-x64, darwin-arm64. Cross-compilation alone is not runtime verification; CI exercises Windows x64, Linux x64 and macOS arm64.

Packages contain only the manifest, extension JavaScript, icon, documentation/licenses and one stripped Go executable. .vscodeignore uses an explicit allowlist; source trees, SDKs, development dependencies, caches, test data and credentials are excluded. Packaging fails above 20 MiB compressed. Generated Go dependency licenses are included. JavaScript has zero production dependencies.

The Marketplace publisher is SharifulIslam, and the extension ID is SharifulIslam.agentreplay. Publishing requires access to that publisher account. This repository does not publish automatically.

Source layout

• src/, media/, .vscode/: native extension and development launch configuration.
• cmd/agentreplay/, internal/, pkg/: retained runtime implementation and tests.
• scripts/extension/, test/: build, packaging and extension validation.
• sdk/, examples/, schemas/, proto/, migrations/: instrumentation and runtime compatibility sources, excluded from VSIX.
• docs/: core feature reference and migration evidence. Older dashboard/self-hosted instructions are historical; use this README for extension setup.

See migration details and cleanup inventory. The runtime is retained to preserve existing replay and analysis behavior. This migration does not constitute a new security audit or production certification of that runtime.