Agent Brain
A VS Code extension that draws your workspace as a 3D graph of folders and files, then shows coding agents moving through it live. When an agent searches, the core pulses and the matching files light up. When it reads or edits a file, the cursor flies there and a terminal types out the contents.
What it watches
| Agent |
Log it reads |
| Claude Code |
~/.claude/projects/<workspace path>/**/*.jsonl |
| Codex |
~/.codex/sessions/**/*.jsonl (only sessions whose working folder is this workspace) |
| GitHub Copilot Chat |
chatSessions/ in VS Code's storage folder for this workspace |
Only tool calls that touch files inside the workspace are shown. Nothing is sent anywhere: the extension reads local log files and draws them. When no agent has been active for 30 seconds, a demo tour takes over.
In VS Code the graph honors your files.exclude and search.exclude settings: excluded files and folders never appear, and agent activity that names them is not shown. The browser preview has no VS Code settings and only skips the built-in folders below.
Graph edges come from folders, [[wikilinks]], Markdown links and relative import/require paths. Up to 1500 files are mapped; node_modules, .git, dist, out, build and similar folders are skipped.
Each top-level folder is drawn as its own cluster. The Big bang button scatters every file across the sphere ignoring folders, and back again; the choice is remembered. The page records the last 1000 agent steps, and Replay plays them back (the r key does the same) before returning to the demo tour; the recording survives a rescan reload but not closing the tab or window. Cinema mode and the orbit rings were removed, and terminals now use only the right-hand column.
Press / to search files (arrow keys and Enter, or click, pick a result), or click a node to open a detail card with its links and, in VS Code, an Open file button. Click a folder in the legend to isolate its cluster; Only what needs attention dims everything agents have not touched since the page loaded. While a replay runs, a slider jumps to any step. The TOUCHED stat counts files agents have touched since the page loaded. The ? button lists the controls.
Install and run
- Sidebar: click the Agent Brain icon in the activity bar. Start runs one local server on 127.0.0.1 and Stop frees its port. While it runs, Open in VS Code, Open in Browser and Copy URL all show the same live graph. Show Logs opens the Agent Brain output channel with the server log and one line per agent event.
- Port: the setting
agentBrain.port (default 5173) is the first port tried. If it is busy, the next ports are tried, up to 10.
- From this repo: open the
second-brain folder in VS Code, press F5 ("Run Agent Brain"), then run Agent Brain: Open in VS Code from the Command Palette in the new window.
- Install a package: from the
extension folder, run npm run package:vsix, then code --install-extension dist/agent-brain-0.1.0.vsix. Use --force only to reinstall the same version during local testing.
- In a browser, live:
npm run brain from the repo root. It serves http://127.0.0.1:5173/, opens your browser and shows agents live. For another folder, run node extension/scripts/preview.mjs <folder>. Add --port 8080 or --no-open if needed; a busy port falls over to the next one.
- In a browser, one file:
npm run brain:export writes agent-brain.html, a self-contained page that opens with a double-click. It plays the demo tour only, because a plain file cannot receive live events.
Develop
Run these from the extension folder. Packaging uses @vscode/vsce, which currently requires Node.js 22 or later. Install exact locked dependencies with npm ci (or use npm install when intentionally updating the lockfile).
| Script |
What it does |
npm test |
Unit tests for the graph builder and the agent log parsers. |
npm run check |
Syntax-checks every source file and the webview's inline script, then runs the tests. |
npm run preview |
Live browser view of the parent folder at http://127.0.0.1:5173/. |
npm run preview:export |
Writes dist/agent-brain.html, a self-contained demo page. |
npm run package:vsix |
Runs check, packages only the runtime files into dist/agent-brain-<version>.vsix with @vscode/vsce, then tests the package contents. |
To debug, open the extension folder in VS Code and press F5 ("Run Agent Brain Extension"); it opens the parent folder in the new window.
From the repo root, npm run check and npm run package:vsix forward to the same scripts.
Release artifact
Push a tag named v<extension-version> (for example, v0.1.0) to run the Package VS Code extension workflow. It validates that the tag matches extension/package.json, runs the checks, packages the VSIX, and uploads it as a GitHub Actions artifact. It does not publish to any marketplace or create a GitHub release.
This project is licensed under the MIT License; the VSIX includes a copy. Before Marketplace publication, create or select a Marketplace publisher and replace local, then configure the publisher's supported authentication. The current repository metadata points to this repository; no publisher identity or credentials are stored here.
