Claude Loop

Safety, memory, and visual feedback for every Claude Code session.

Claude Loop is a local companion for Claude Code that runs as a small Hono worker on localhost:37200 and listens to Claude Code's hook events. It records every edit, captures safety snapshots, runs related tests, compares frontend screenshots, remembers decisions across sessions, and surfaces all of it in a local dashboard.

No network calls. No LLM round-trips. Everything is deterministic, local, and inspectable.

Status: beta. The architecture is stable and every feature described here is backed by tests (npm test). Breaking changes are still possible.

What it actually does

Every feature below is real, tested, and verifiable with claudebrain inspect <session-id>:

Safety

• Pre-edit snapshots — every Edit / Write / MultiEdit is captured as a content-addressed snapshot before the tool runs. Rollback is a single API call.
• Automatic test runs — when a file is edited, the related test file (Vitest / Jest / Pytest / Go / Rust / etc.) is detected and run in the background. Failures are linked to the action that caused them.
• Session-level rollback — roll back all files touched after a chosen checkpoint, or the entire session. Handles tombstones (new files get deleted), repeated edits (restores the earliest pre-edit state), and is exposed via both API and dashboard.
• Branch guard — warns when Claude edits files on a protected branch (main, master by default). Warning is injected once per session, not on every tool call. Degrades silently outside git repos.
• File protection — configurable glob patterns (.env, *.secret, infra/**) that warn or block edits to sensitive files. Supports warn and block modes.
• Loop detection — if Claude calls the same tool on the same file with the same arguments three times in 60s, the next PreToolUse injects a warning memory so Claude can see the loop and break out of it.

Memory (the brain)

• Typed memories per project: decision, constraint, failure, pattern, preference, bug, architecture, context.
• Relevance-ranked context packs injected on SessionStart and file-scoped on PreToolUse. Character-budgeted, score-floored, never dumps everything.
• Session compression on SessionEnd — deterministic extraction of decisions, failures, and patterns from the action log into durable memories. Includes a rule-based confidence score based on the ratio of productive edits to friction signals (failures, rollbacks, reversals, loops).
• Memory decay — old unused memories gradually lose importance so stale entries don't crowd out relevant ones. Soft and non-destructive: decayed memories recover importance when re-accessed.
• Project profile memory — package manager, test framework, and language detected once from lockfiles and remembered as a constraint.
• Dream cycle (optional) — on SessionEnd, prunes stale context memories and merges near-duplicate decisions. Defaults to rules mode (no network). Ollama mode is opt-in.

Vision (the eyes)

• Before/after screenshots for frontend edits via Puppeteer, matched against configurable dev-server ports.
• Byte-identity visual delta — the before and after PNGs are hashed; identical bytes = "no visual change", different bytes = "differs". We do not decode pixels, so we never claim to measure "how much" changed.
• Runtime error capture — console and page errors observed during each screenshot are recorded. If the after-shot has errors the before-shot didn't, a visual-regression memory is promoted.
• Honest skip reasons — every "why wasn't this captured?" (no_server, capture_failed, no_runtime, skipped) is logged and surfaced in the dashboard.

Operational self-awareness

• Context pressure — a deterministic 0..1 score blending observable session signals (action count, tool I/O bytes, distinct files, prompt bytes, duration). This is not a token count. The warning text is explicit about that. Surfaces at high / critical only.
• Capability registry — brain / snapshots / tests / eyes / dream_cycle each have ready / degraded / unavailable state verified against real observables (port connects, module resolution, file stats). Degraded capabilities are folded into the SessionStart context pack.
• Brain notes — tagged operational observations recorded when pressure transitions, capabilities degrade/recover, or loops fire. Labelled "Observed by Claude Loop (operational note, not model reasoning)".

Dashboard

• Local React dashboard at http://localhost:37200/dashboard/.
• Session timeline with linked snapshots and rollback controls.
• Memory graph per project.
• Screenshot diff view with byte-identity delta + runtime error badges.

Install

Requirements: Node 18+, Claude Code CLI

As a Claude Code plugin (recommended)

/plugin install claudebrain

From npm

npx claudebrain init

From source

git clone https://github.com/Vigan/claudebrain.git
cd claudebrain
npm install
npm run build        # build the worker + hook scripts
npm run build:dashboard
claudebrain init     # register hooks in ~/.claude/settings.json

The worker starts automatically when Claude Code fires its first hook. You can also start it manually:

claudebrain start

CLI

claudebrain init                     Install hooks into Claude Code settings
claudebrain uninstall                Remove hooks and clean up
claudebrain start                    Manually start the worker service
claudebrain status                   Check worker health, stats, and capabilities
claudebrain inspect <session-id>     Print full brain/vision/summary state
                   [--file <path>]   Optionally scope the context pack preview
claudebrain export <path>            Export database to a file
claudebrain import <path>            Import database from a file

claudebrain inspect

Prints every answerable question about a session in one place:

• Session metadata and duration
• Timeline length + last hook events
• Brain snapshot (what's remembered for this project)
• Session compression output (decisions, failures, patterns, confidence)
• Vision pipeline (captured / skipped / failed with reasons)
• Context pressure (observed, not token-based)
• Capabilities (ready / degraded / unavailable per feature)
• Brain notes (operational observations)
• Context pack that would be injected next SessionStart

claudebrain export / claudebrain import

Back up and restore the Claude Loop database:

# Export the database (sessions, memories, metadata)
claudebrain export ~/claudebrain-backup.db

# Import on another machine or after reinstall
claudebrain import ~/claudebrain-backup.db

Export includes all sessions, timelines, memories, and metadata. Snapshot file contents and screenshot images are not included (only their metadata). Import backs up the existing database to claudebrain.db.bak before overwriting.

Configuration

On first run, Claude Loop writes ~/.claudebrain/config.json with defaults. Every field is safe to edit:

{
  "worker_port": 37200,
  "db_path": "~/.claudebrain/claudebrain.db",
  "screenshots_dir": "~/.claudebrain/screenshots",
  "snapshots_dir": "~/.claudebrain/snapshots",
  "dev_server_ports": [3000, 3001, 5173, 5174, 8080, 8081, 4200, 4321],
  "test_timeout_ms": 30000,
  "idle_shutdown_minutes": 30,
  "dream_cycle": { "enabled": false, "provider": "rules" },
  "eyes": {
    "enabled": true,
    "viewport": { "width": 1280, "height": 720 },
    "frontend_extensions": [".html", ".css", ".jsx", ".tsx", ".vue", ".svelte"]
  },
  "branch_guard": {
    "enabled": true,
    "protected_branches": ["main", "master"]
  },
  "protected_files": {
    "enabled": false,
    "mode": "warn",
    "patterns": [".env", "*.secret", "infra/**"]
  }
}

What it does NOT do

Honesty is a hard constraint of the project, so this list matters:

• It does not read Claude's transcript. Hooks only expose tool inputs, tool outputs, and user prompts. The "context pressure" score is based on those observables only — it is not a real token count and the code says so explicitly in every place it's surfaced.
• It does not send anything to the network. No telemetry, no LLM calls (unless you explicitly enable dream_cycle.provider: "ollama" with a local Ollama instance).
• It does not measure pixel-level visual diffs. Screenshots are compared by SHA1 of the PNG bytes. "Differs" means the bytes differ; we never claim to know by how much.
• It does not generate reasoning. "Brain notes" are operational observations (pressure transitions, capability state changes). Every such note is labelled as an observation, not inferred thought.
• It does not modify code outside its own data directories. Snapshots, memories, and screenshots live in ~/.claudebrain/. The only file it writes outside that is ~/.claude/settings.json (only on init / uninstall, only to register hooks, with a marker so it can find and remove them cleanly later).

Architecture

~/.claude/settings.json         ← hooks registered here (marker-scoped)
         │
         ▼
hook scripts (node) ──http──▶  claudebrain worker (Hono on :37200)
                                         │
                                         ├── sql.js DB at ~/.claudebrain/claudebrain.db
                                         ├── snapshots at ~/.claudebrain/snapshots
                                         ├── screenshots at ~/.claudebrain/screenshots
                                         └── /dashboard/  (React SPA)

• src/hooks/* — Claude Code hook receivers (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, SessionEnd).
• src/worker/services/ — the brain, vision, pressure, capability registry, compression, and test/snapshot services.
• src/worker/routes/ — Hono route modules (hooks, memory, snapshot, eyes, tests, dashboard).
• src/db/ — sql.js connection, schema, migrations.
• src/cli/ — init / uninstall / start / status / inspect / export / import.
• dashboard/ — React + Vite dashboard.

Schema migrations are versioned (src/db/schema.ts, currently v3) and run automatically on worker start.

Testing

npm test

Runs the full vitest suite covering loop detection, memory promotion, selective reinjection, memory decay, compression confidence, schema migrations, snapshot rollback, screenshot pairing, visual regression, context pressure, capability registry, brain notes, and hook route integration.

License

MIT — see LICENSE.