Quickstart

Install the Claudium hub on localhost, point the watcher at your Claude Code projects directory, and watch your brain light up.

This walkthrough takes about five minutes. By the end you'll have the Claudium hub running on http://localhost:4242 and the visualization driven by your actual Claude Code activity.

Prerequisites

Node 18 or newer.
A clone of the claude-brain-watcher repo.
Claude Code installed and writing session logs to the default location (~/.claude/projects/).

1. Install

git clone https://github.com/Austinjh1234/claudebrain.git
cd claudebrain/claude-brain-watcher
npm install

2. Run the hub

npm start

You should see:

[hub] listening on http://localhost:4242
[hub] watching ~/.claude/projects/

Open http://localhost:4242 in a browser. The top-bar status indicator switches from SIMULATING (amber) to ● LIVE · CLAUDE CODE (green) once the page connects to the hub.

3. Trigger a session

In a separate terminal:

claude

Run any small Claude Code task — read a file, edit something, run a test. Within a half-second the visualization fires:

The matching brain region glows (visual cortex for reads, motor cortex for shell, cerebellum for edits).
Your agent name (the directory name, lowercased) appears in the left panel.
A token counter ticks up on the right.

If nothing happens, see the troubleshooting section below.

What just happened

When Claude Code emits a tool call, it appends a line to a .jsonl file under ~/.claude/projects/<dashed-path>/. The hub tails those files via chokidar, parses each new assistant message for tool_use blocks, classifies the tool into one of eight brain regions (see region mapping), and broadcasts the event to every connected viewer over WebSocket. The viewer is the same brain visualization you've been looking at — landing/components/Brain*.tsx plus a small driver that listens on the socket.

No code, no prompts, no model outputs are ever transmitted. Only metadata: tool name, region label, token count, file path. The PII filter on the hub drops anything that looks like a key, token, or password before any other viewer can see it.

Optional flags

PORT=8080      npm start   # custom port
VERBOSE=1      npm start   # log every event to stdout
POLLING=1      npm start   # fall back to polling when fsevents doesn't fire (WSL, Docker, NFS)
CLAUDE_DIR=…   npm start   # non-default Claude install

Troubleshooting

Status stuck on SIMULATING. The page never reached the server. Confirm you opened the URL the hub printed (default http://localhost:4242), not the raw index.html file from disk.

Status stuck on RECONNECTING. The page connected once and lost the socket. Check the terminal where npm start is running for crashes or restarts.

No events appear. Confirm ~/.claude/projects/ exists and contains .jsonl files. On macOS, Claude Code writes there by default. Run with VERBOSE=1 to see what's being parsed. If files exist but aren't detected, try POLLING=1 — your filesystem probably doesn't emit inotify events (Docker, WSL2, NFS-mounted homes).

Only one region fires. That's accurate. If your session is mostly reads (browsing code, planning), the visual cortex should dominate. Try a task that requires editing or shell commands to see motor + cerebellum activity.

Integrate your own sender — drive the brain from any tool-using agent, not just Claude Code.
Self-host on Render — same setup, public domain, shared with your team.