Skip to content
claude-guardian

Getting Started

Install

Section titled “Install”

Install globally via npm:

Terminal window
npm install -g claude-guardian

Or run directly without installing:

Terminal window
npx claude-guardian preflight

First health check

Section titled “First health check”

Run status to see how your environment looks:

Terminal window
claude-guardian status

This prints disk free space, total Claude project log size, per-project breakdowns, and any issues found (oversized logs, low disk). The one-line banner at the bottom gives you a quick summary.

Auto-fix log bloat

Section titled “Auto-fix log bloat”

If the status report shows warnings about oversized logs, auto-fix them:

Terminal window
claude-guardian preflight --fix

This rotates old logs (gzip compression, reversible) and trims oversized .jsonl and .log files to their last N lines. Every action is logged to a journal file for traceability.

Generate a crash report

Section titled “Generate a crash report”

If something went wrong and you need evidence for a bug report:

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

The bundle contains system info, log file tails, and the guardian’s own action journal.

Run with watchdog

Section titled “Run with watchdog”

Wrap any command with the watchdog to get automatic hang detection and crash bundles:

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

The watchdog monitors stdout/stderr for activity. If no output appears for the configured timeout, it captures a doctor bundle. If the process crashes, it captures a bundle and optionally restarts with backoff.