The Problem

Claude Code is powerful, but it works blind. It doesn't remember what it decided last session. It can't roll back a bad edit. It doesn't know if its CSS change broke your layout. And when it gets stuck in a loop editing the same file over and over, it has no idea.

Claude Loop fixes all of that.

It runs as a lightweight local worker that listens to Claude Code's hook system. Every edit gets a safety snapshot. Every frontend change gets a before/after screenshot. Decisions, failures, and patterns are extracted and remembered across sessions. And everything is visible in a real-time dashboard.

No cloud. No API keys. No telemetry. Everything runs on your machine and stays on your machine.

Quick Start

Requirements: Node 18+, Claude Code

$ npx claude-code-loop init       # Install hooks + start worker
$ npx claude-code-loop start      # Start the background worker
$ npx claude-code-loop status     # Show worker health & sessions

That's it. init is the only command you need — it:

1. Installs hooks into your Claude Code settings (~/.claude/settings.json)
2. Starts the worker in the background on localhost:37200
3. Opens the dashboard in your browser

Now open any project with Claude Code and start editing. Claude Loop activates automatically.

Dashboard: claudeloop.sh

How It Works

You open Claude Code
        │
        ▼
Claude edits a file (Edit / Write / MultiEdit)
        │
        ├── PreToolUse hook fires ──▶ Claude Loop captures a snapshot of the file
        │                             Checks if it's a frontend file → takes "before" screenshot
        │                             Injects relevant memories from past sessions
        │
        ▼
Claude's edit completes
        │
        ├── PostToolUse hook fires ─▶ Runs related tests automatically
        │                             Takes "after" screenshot
        │                             Detects loops (same edit 3x in 60s)
        │                             Records everything to local SQLite DB
        │
        ▼
Session ends
        │
        └── SessionEnd hook fires ──▶ Compresses session into durable memories
                                      Extracts decisions, failures, patterns
                                      Prunes stale context (dream cycle)

Everything is powered by Claude Code hooks — the official event system that fires before and after every tool use. Claude Loop doesn't patch, proxy, or intercept anything. It just listens.

Features

Safety Net

| Feature | What it does | |---------|-------------| | Pre-edit snapshots | Every file is captured before Claude touches it. Content-addressed, deduplicated. Rollback is one click. | | Session rollback | Roll back every file touched after a checkpoint — or the entire session. Handles new files (deletes them), repeated edits (restores earliest state). | | Automatic test runs | Detects related test files (Vitest, Jest, Pytest, Go, Rust, etc.) and runs them after every edit. Failures are linked to the action that caused them. | | Branch guard | Warns when Claude edits files on main or master. One warning per session, not per edit. | | File protection | Block or warn on edits to .env, *.secret, infra/**, or any glob pattern you define. | | Loop detection | If Claude calls the same tool on the same file with identical arguments 3x in 60 seconds, it gets a warning injected into context. |

Memory (The Brain)

Claude Code forgets everything between sessions. Claude Loop doesn't.

• 8 memory types: decision, constraint, failure, pattern, preference, bug, architecture, context
• Smart injection: Memories are ranked by relevance and injected at session start. File-scoped memories are injected when Claude opens specific files. Character-budgeted — never dumps everything.
• Session compression: When a session ends, Claude Loop extracts decisions, failures, and patterns from the action log and stores them as durable memories for next time.
• Memory decay: Old unused memories gradually lose importance. Stale entries don't crowd out relevant ones. Non-destructive — re-accessed memories recover.
• Project detection: Package manager, test framework, and language are detected from lockfiles and remembered automatically.

Vision (The Eyes)

See what Claude's edits actually look like.

• Before/after screenshots via Puppeteer for every frontend file edit (.html, .css, .tsx, .vue, .svelte, etc.)
• Visual delta detection — PNGs are SHA1-hashed. Same hash = no visual change. Different hash = something changed. No pixel decoding, no false claims.
• Runtime error capture — Console errors and page crashes are recorded during each screenshot. If the "after" shot has errors the "before" didn't, a visual regression memory is created.
• Configurable dev server ports — Works with Vite (5173), Next.js (3000), Angular (4200), or any port you specify.

Self-Awareness

Claude Loop monitors its own health so you don't have to.

• Context pressure — A 0–1 score based on action count, file count, I/O volume, and session duration. Warns at high and critical levels. Explicit that this is an estimate, not a token count.
• Capability registry — Each subsystem (brain, snapshots, tests, eyes, dream_cycle) reports ready, degraded, or unavailable based on real checks (port connectivity, module resolution, file stats).
• Operational notes — Automatically logged when pressure changes, capabilities degrade/recover, or loops are detected.

Dashboard

The dashboard runs at claudeloop.sh and gives you full visibility into every session.

• Session timeline — Every action Claude took, with timestamps, tool names, and file paths
• Snapshot rollback — Click to roll back any file to its pre-edit state
• Memory graph — Visualise what Claude Loop remembers about your project
• Screenshot comparison — Before/after slider view with visual delta badges
• Test results — See which tests passed or failed after each edit
• Vision status — How many screenshots were captured, skipped, or failed (and why)
• Session summary — Decisions, failures, and patterns extracted from the session

Install

From npm (recommended)

npx claude-code-loop init

As a Claude Code plugin

/plugin install claude-code-loop

From source

git clone https://github.com/neilhtennek/ClaudeLoop.git
cd ClaudeLoop
npm install
npm run build              # build the worker + hook scripts
npm run build:dashboard    # build the dashboard UI
npx claude-code-loop init  # register hooks and start the worker

CLI Reference

npx claude-code-loop init                       # Install hooks + start worker
npx claude-code-loop uninstall                   # Remove hooks and clean up
npx claude-code-loop start                       # Start the background worker
npx claude-code-loop status                      # Check worker health & capabilities
npx claude-code-loop inspect <session-id>        # Full brain/vision/summary dump
npx claude-code-loop inspect <id> --file <path>  # Scoped context pack preview
npx claude-code-loop export <path>               # Export database to file
npx claude-code-loop import <path>               # Import database from file

inspect — Debug any session

Prints everything about a session in one place: metadata, timeline, brain snapshot, compression output, vision pipeline, context pressure, capability states, brain notes, and the context pack that would be injected on next start.

export / import — Portable memory

npx claude-code-loop export ~/backup.db    # Back up sessions + memories
npx claude-code-loop import ~/backup.db    # Restore on another machine

Export includes sessions, timelines, memories, and metadata. Screenshots and snapshot files are not included (only metadata). Import backs up the existing database before overwriting.

Configuration

Claude Loop writes ~/.claude-loop/config.json on first run. Every field is safe to edit:

{
  "worker_port": 37200,
  "dev_server_ports": [37200, 3000, 3001, 5173, 5174, 8080, 8081, 4200, 4321],
  "test_timeout_ms": 30000,
  "idle_shutdown_minutes": 30,
  "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/**"]
  },
  "dream_cycle": { "enabled": false, "provider": "rules" }
}

| Field | What it controls | |-------|-----------------| | worker_port | Port the worker listens on (default 37200) | | dev_server_ports | Ports to check for a running dev server before taking screenshots | | eyes.enabled | Toggle screenshot capture on/off | | eyes.viewport | Browser viewport size for screenshots | | eyes.frontend_extensions | File extensions that trigger screenshot capture | | branch_guard.protected_branches | Branches that trigger a warning when edited | | protected_files.patterns | Glob patterns for files that should warn or block on edit | | dream_cycle.enabled | Enable memory pruning/merging on session end |

Architecture

~/.claude/settings.json           ← hooks registered here
         │
         ▼
hook scripts (node) ──http──▶  Claude Loop worker (Hono on :37200)
                                         │
                                         ├── SQLite DB (sql.js, in-process)
                                         ├── Content-addressed snapshots
                                         ├── Puppeteer screenshots
                                         └── React dashboard (SPA)

| Directory | Contents | |-----------|----------| | src/hooks/ | Hook receivers — SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, SessionEnd | | src/worker/services/ | Core services — memory, snapshots, tests, screenshots, compression, pressure, capabilities | | src/worker/routes/ | Hono API routes — hooks, memory, snapshot, eyes, tests, dashboard | | src/db/ | sql.js connection, schema, versioned migrations (currently v3) | | src/cli/ | CLI commands — init, uninstall, start, status, inspect, export, import | | dashboard/ | React + Vite dashboard |

Data lives in ~/.claude-loop/. The only file Claude Loop writes outside that directory is ~/.claude/settings.json (only during init/uninstall, only to register hooks, with a unique marker so it can find and remove them cleanly).

What It Does NOT Do

• Does not read Claude's conversation. Hooks only see tool inputs, outputs, and user prompts — not the model's reasoning.
• Does not phone home. Zero network calls. No telemetry. No analytics. Everything is local.
• Does not measure pixel diffs. Screenshots are compared by file hash. "Differs" means the bytes differ — we never claim to measure how much.
• Does not generate reasoning. Brain notes are operational observations, not inferred thoughts. Every note is explicitly labelled.
• Does not touch your code. All data lives in ~/.claude-loop/. Your project files are only read (for snapshots), never written.

Testing

npm test

Full Vitest suite covering loop detection, memory promotion, reinjection, decay, compression, schema migrations, snapshot rollback, screenshot pairing, visual regression, context pressure, capability registry, brain notes, and hook integration.

Links

• npm: claude-code-loop
• GitHub: neilhtennek/ClaudeLoop
• X: @ClaudeLoop
• Pump.fun: D8ruKrfHfSgTroqeFWBCQga5yZQ9nyM7sffK4rw7pump
• Dashboard: claudeloop.sh

License

MIT — see LICENSE.