Claude Guardian

Flight computer for Claude Code — log rotation, watchdog, crash bundles, and MCP self-awareness.

Claude Guardian is a local reliability layer that keeps Claude Code sessions healthy. It detects log bloat, disk pressure, and hangs before they cause problems, captures evidence when things go wrong, and exposes an MCP server so Claude can self-monitor mid-session.

What it does

Install

npm install -g @mcptoolshop/claude-guardian

Or run directly:

npx @mcptoolshop/claude-guardian preflight

Quick start

Check your environment

claude-guardian status

=== Claude Guardian Preflight ===

Disk free: 607.13GB [OK]
Claude projects: C:\Users\you\.claude\projects
Total size: 1057.14MB

Project directories (by size):
  my-project: 1020.41MB

Issues found:
  [WARNING] Project log dir is 1020.41MB (limit: 200MB)
  [WARNING] File is 33.85MB (limit: 25MB)

[guardian] disk=607.13GB | logs=1057.14MB | issues=2

Auto-fix log bloat

claude-guardian preflight --fix

Rotates old logs (gzip), trims oversized .jsonl/.log files to their last N lines. Every action is logged to a journal file for traceability.

Generate a crash report

claude-guardian doctor --out ./bundle.zip

Creates a zip containing:

• summary.json — system info, file size report, preflight results
• log-tails/ — last 500 lines of each log file
• journal.jsonl — every action the guardian has ever taken
• process.json — snapshot of running Claude processes at bundle time
• timeline.json — reconstructed chronological event timeline
• state.json — current daemon state (if daemon was running)
• incidents.jsonl — incident history (if any)

Run with watchdog

claude-guardian run -- claude
claude-guardian run --auto-restart --hang-timeout 120 -- node server.js

The watchdog:

1. Spawns your command as a child process
2. Monitors stdout/stderr for activity
3. If no activity for --hang-timeout seconds → captures a doctor bundle
4. If the process crashes → captures a bundle, optionally restarts with backoff

MCP Server (the real unlock)

Register the guardian as a local MCP server so Claude can self-monitor:

Add to ~/.claude.json:

{
  "mcpServers": {
    "guardian": {
      "command": "npx",
      "args": ["@mcptoolshop/claude-guardian", "mcp"]
    }
  }
}

Then Claude can call:

This lets Claude say: "Attention is WARN. Running guardian_nudge, then reducing concurrency."

Preview reliability

The guardian_preview_ready and guardian_preview_recover tools solve the race condition where preview_start returns success before the dev server is actually listening — which causes the browser to land on chrome-error:// and get stuck.

Workflow: preview_start → guardian_preview_ready (wait gate) → preview_snapshot

For non-web projects (Tauri, .NET MAUI, CLI tools), guardian_preview_recover detects the project type and returns "skip preview" guidance, avoiding false positives from the built-in preview verification hook.

Configuration

Three knobs (everything else is hardcoded with sane defaults):

Plus one hardcoded guardrail:

• Disk free < 5GB → aggressive mode auto-enabled (shorter retention, lower thresholds)

Trust model

Claude Guardian is local-only. It has no network listener, no telemetry, and no cloud dependency.

What it reads: ~/.claude/projects/ (log files, sizes, modification times), process list (CPU, memory, uptime, handle counts for Claude-related processes via pidusage).

What it writes: ~/.claude-guardian/ (state.json, budget.json, journal.jsonl, doctor bundles). All files are under the user's home directory.

What it collects in bundles: System info (OS, CPU, memory, disk), log file tails (last 500 lines), process snapshots, and guardian's own journal. No API keys, tokens, credentials, or user content.

Dangerous actions — what Guardian will NOT do:

• Kill processes or send signals (no SIGKILL, no SIGTERM)
• Restart Claude Code or any other process
• Delete files (rotation = gzip, trimming = keep last N lines)
• Make network requests or phone home
• Elevate privileges or access other users' data

If process killing or auto-restart is ever added, it will be behind an explicit opt-in flag, documented here, and off by default.

Reliability

Guardian is hardened for continuous daily use:

• Async mutexes — withStateLock and withBudgetLock serialize concurrent file I/O, preventing TOCTOU races between the daemon and MCP tools
• Overlap guard — daemon polls are protected by a pollInProgress flag so slow polls can't stack
• Clock skew protection — all time deltas clamped with Math.max(0, ...) to handle system clock adjustments
• Reverse-seek tail — large log files (>1MB) are tailed by reading chunks from the end, avoiding OOM on 500MB+ logs
• Corruption recovery — corrupt state.json or budget.json files are backed up and reset with a journal entry for forensics
• Process enumeration tracking — enumeration failures are captured in lastEnumerationError instead of silently swallowed
• Full UUID lease IDs — budget leases use full UUIDs for reliable identification
• Lease expiration journaling — expired leases are logged to the action journal for auditability

Design principles

• Evidence over vibes — every action writes a journal entry; crash bundles capture state, not guesses
• Deterministic — no ML, no heuristics beyond file age and size. Decision table you can read in 60 seconds
• Safe by default — rotation = gzip (reversible), trimming = keep last N lines (data preserved), no deletions in v1
• Boring dependencies — commander, pidusage, archiver, @modelcontextprotocol/sdk. That's it.

Development

npm install
npm run build
npm test

Scorecard

License

MIT

Built by MCP Tool Shop