by clouvra
Watch your AI coding agent work as live activity on a real MRI brain: sessions, subagents, every tool call and its result. Works with Claude Code for now. Local only; uses no tokens.
Agent Brain
Watch your AI coding agent work, live, on a real brain. An Obsidian plugin that shows every agent session (prompts, thinking, tool calls, subagents, results) as activity on an MRI-derived brain, and your vault as its neurons and links. It only listens on your own computer and never calls a model, so it uses no tokens.
Works with Claude Code for now, through its hooks and telemetry. Agent Brain is an independent project, not made by or affiliated with Anthropic.
Quick start
- Install the plugin. With BRAT: add
mucahitkumlay/agent-brain. Or downloadmain.js,manifest.jsonandstyles.cssfrom the latest release into<your vault>/.obsidian/plugins/agent-brain/and enable it. Desktop only. - Connect Claude Code. Settings → Agent Brain → Claude Code hooks on this computer → Install, then restart running Claude Code sessions.
- Open the view (ribbon icon or Open Agent Brain view). No session yet? The start screen lets you play made-up sessions and see everything work.
On first start the plugin downloads the brain anatomy once (about 3 MB) from this repository's anatomy release and checks it against SHA-256 sums built into the plugin.
What it does
See the work as it happens
- Each tool call travels along a real fibre bundle to the region for that kind of work: reading, editing, running commands, web, subagents. Thinking keeps circulating in the frontal lobe; a long command keeps its path busy.
- A line at the top says whether you need to act: an approval, a session that may be stuck, or nothing.
- When a turn ends, a card shows its duration, tool calls, files, last test run, cost and warnings.
- Freeze time (Space) and click any signal: who ran it, why, where it goes, every parameter and the output. The operation tree of the turn is one tab away.
Watchers
Four checks run all the time. They only watch: nothing is ever stopped.
| Watcher | It notices |
|---|---|
| Guard | destructive commands (rm -rf, git push --force, DROP TABLE, curl | sh …) and secrets written in the open |
| Shield | outside content (a web page, a download) that tries to give the agent orders, and what the agent does next |
| Reality | the agent believing something that is not so: a file that does not exist, "it works" after a failed run |
| Stuck | the same command failing again and again, a command running for 20 minutes, no progress for 10 |
Findings are cards sorted by how much they ask of you (Needs you now, Worth a check, For the record). Each says what happened and what to do, and can copy a short note to paste into the agent, open the project's lessons, mark the finding as normal in that project, or be marked as done. See it catch things plays a short demo in which all four fire.
Your notes in the brain
Every note is a neuron, every link an axon that follows the folds of the cortex or a real white-matter bundle. Files the agent uses one after the other grow a connection, and signals follow it.
The notes view (D) switches to the Notes look: the cortex becomes a cloud of points in its regions'
colours and your notes stand out, sized by their links. Search, browse by region, or pick a note: the brain turns to it
and a signal runs along each of its links. Notes are placed by their type, kind or category, their tags or their
folder, and you can add your own rules in the settings (type:wiki=occipital).
Get better at working with it
The Use Claude Code better panel (U) compares this week with the last from your own turns and suggests what to change, each with the numbers behind it: permission rules for commands you keep approving, CLAUDE.md lines, when to start fresh. Only numbers are kept, never prompts or file contents. Copy for a review puts those numbers on the clipboard to paste into any chat for a second opinion.
And more
- Lessons per project (the test command that works, commands that are not installed), ready for CLAUDE.md.
- Autopsy, replays and comparison: a session's key moments, a shareable replay without names, paths or prompts, two sessions side by side, a project map.
- Energy from telemetry: tokens, context and cost per session, with optional spending limits.
- Looks and layers: Anatomy, Atlas (see-through) and Notes; inner structures, fibre tracts, MRI slices; themes including a colour-blind safe high-contrast one; Reduce motion.
- Daily note and an optional note per session; EEG traces; body signals of each machine.
Keys
| Key | |
|---|---|
| Space | Freeze time and inspect signals (, . slower, faster) |
| [ ], Enter | Previous / next signal, open it |
| S A T G E | Sessions, activity, timeline, regions, EEG |
| W U D ? | Watchers, use it better, notes, what can I do here |
| L M V | Layers, MRI slice, look |
| F R H I | Follow activity, reset view, hide everything, info |
Sessions on a server
Claude Code on a remote machine reaches the plugin through a reverse SSH tunnel:
- Start the tunnel on your computer:
scripts/tunnel/agent-brain-tunnel.sh user@server(macOS/Linux), or setSERVERinscripts/tunnel/agent-brain-tunnel.batand run it (Windows). Key-based SSH login must already work. - On the server, once, while the tunnel is up:
curl -s http://127.0.0.1:27182/install.sh | sh. This installs the hooks, an offline queue (events wait while the tunnel is down), a heartbeat and the telemetry settings. - Restart the tunnel and the Claude Code sessions on the server.
Other agents
Any agent can report by posting JSON (one event or a list) to http://127.0.0.1:27182/agent:
{ "agent": "my-agent", "session": "42", "cwd": "/path/to/project", "type": "tool", "tool": "Bash", "id": "c1", "input": { "command": "npm test" } }
type is start, prompt (text), tool (tool, input, id), result (id, output), error (id,
output), wait, stop (text) or end. They become the same events Claude Code's hooks send.
Coach mode (off by default)
With Coach mode on (Settings → Alerts) and the hooks installed again, guard, shield and important reality findings go back to the agent as a note on its next tool result, so it can check itself. Never a decision, never a block.
Privacy and permissions
| Network | One request, once: the anatomy files from this repository's release, checked by SHA-256. No telemetry, analytics, model calls or other servers. |
| Listener | HTTP on 127.0.0.1 only, so Claude Code's hooks can report. It answers with an empty response (except Coach mode) and refuses requests that look like they come from a web page. |
| Files outside the vault | Only Claude Code's settings.json: read by the setup check, and backed up and written when you press Install. |
| Vault | Notes are listed by path; links, frontmatter and tags come from Obsidian's own cache. Note contents are not read, except the plugin's own notes and a replay you pick. It writes only what you ask for (daily note, session notes, lessons, replays). |
| Stored on disk | Settings and short labels (file and program names, never command lines), lessons, and for Use it better one line of numbers per turn. Never prompts, file contents or paths. |
| In memory only | Full call details for the inspector (capped, gone when Obsidian closes; can be turned off). |
| Clipboard | Written only when you press a Copy button; never read. |
Use it on sessions you run or have permission to observe. The inspector shows what the agent saw, so check before you share a screenshot. Watchers are hints, not protection: keep Claude Code's own permissions and sandboxing on.
Build from source
npm ci && npm run build && npm test
dev/ runs the plugin in a browser outside Obsidian; tools/anatomy/ rebuilds the anatomy data. See
CONTRIBUTING.md.
Credits and licences
The plugin code is MIT, © 2026 mucahitkumlay. The licences below are the whole grant; nothing in this README adds rights or gives a warranty.
| What | Where | Licence |
|---|---|---|
| Plugin code, scripts, tools, tests, docs | src/, scripts/, tools/, test/, dev/, docs/, .github/, *.md | MIT |
| three.js | bundled in main.js | MIT, © 2010–2026 three.js authors |
| Brain surface, T1 volume, ventricles | assets/brain.bin.gz, t1.bin.gz, part of inner.bin.gz | MNI ICBM152 2009 template, copyright notice kept (McConnell Brain Imaging Centre, MNI, McGill University) |
| Gyrus labels, deep nuclei | assets/aal.bin.gz, part of inner.bin.gz | Derived from the AAL atlas (GIN-IMN, Bordeaux), with attribution |
| White-matter fibres | assets/tracts.bin.gz | Derived from the HCP-1065 atlas (F.-C. Yeh), CC BY-SA 4.0 |
| Source files for the data | — | the niivue project (BSD 2-Clause) |
Full texts, required notices, changes to the data and citations: THIRD_PARTY_NOTICES.md. If
you redistribute the plugin or its data, keep LICENSE and THIRD_PARTY_NOTICES.md, keep the ICBM notice, credit AAL
and HCP-1065, and keep changes to tracts.bin.gz under CC BY-SA 4.0.
Trademarks. Claude and Claude Code are trademarks of Anthropic, PBC; Obsidian is a trademark of Dynalist Inc. They are named only to say what the plugin works with; Agent Brain is not affiliated with or endorsed by either.
Not a medical or scientific tool. The brain mapping is a visual metaphor grounded in real anatomy. It does not model how a language model works and must not be used for diagnosis, treatment or research.
No warranty. Provided "as is", as stated in the licences.
Security problems: please report them privately through GitHub's Report a vulnerability (Security tab).
For plugin developers
Search results and similarity scores are powered by semantic analysis of your plugin's README. If your plugin isn't appearing for searches you'd expect, try updating your README to clearly describe your plugin's purpose, features, and use cases.