Commands

Command overview

Command	Purpose
`preflight`	Scan Claude project logs, report oversized dirs/files, optionally auto-fix
`doctor`	Generate a diagnostics bundle (zip) with system info, log tails, journal
`run -- <cmd>`	Launch any command with watchdog monitoring, auto-bundle on crash/hang
`status`	One-shot health check: disk free, log sizes, warnings
`watch`	Background daemon: continuous monitoring, incident tracking, budget enforcement
`budget`	View and manage the concurrency budget (show/acquire/release)
`mcp`	Start MCP server (8 tools) for Claude Code self-monitoring

preflight

Scans ~/.claude/projects/ for oversized log directories and files.

# Report only
claude-guardian preflight

# Auto-fix: rotate + trim oversized logs
claude-guardian preflight --fix

# Aggressive mode: shorter retention, lower thresholds
claude-guardian preflight --fix --aggressive

Rotation compresses old logs with gzip (reversible). Trimming keeps the last N lines of oversized files. No files are deleted.

doctor

Creates a zip bundle 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

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

run

Spawns a child process with watchdog monitoring.

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

The watchdog uses three independent signals (log mtime, CPU activity, grace window) to detect hangs. No single false positive can trigger a hang declaration.

status

Quick one-shot health check.

claude-guardian status
claude-guardian status --banner

Reports disk free space, log sizes, and a summary banner.

watch

Background daemon for continuous monitoring.

claude-guardian watch
claude-guardian watch --verbose

Tracks incidents through an ok → warn → critical lifecycle with automatic bundle capture and deduplication.

budget

Manage the concurrency budget.

claude-guardian budget show
claude-guardian budget acquire --slots 2 --reason "build"
claude-guardian budget release --lease <id>

Deterministic cap transitions (4 → 2 → 1 slots) prevent dogpiling when under pressure.