Claude Guardian

Claude Guardian

  A living mascot that floats above your windows, guards your Claude Code sessions, and lets you approve or deny actions without leaving your flow.

  v2.2 — Always Allow button · keyboard shortcuts · hide/show mode · stop notifications

Each terminal session gets its own mascot — every active session spawns an independent mascot on screen, handling its own permission requests. Click the menubar icon to see live usage stats, costs, token breakdowns, and trends.

How It Works

Install

Homebrew (recommended)

This installs the app to /Applications/, sets up Claude Code hooks, copies the default config to ~/.config/claude-guardian/, and launches Guardian automatically.
macOS Gatekeeper note: Since the app isn't notarized, macOS may show "app is damaged" or block it on first launch. Run this once to fix it:

Then open the app normally. You only need to do this once.

Upgrading

From Source

This will:
1. Build the .app bundle
2. Install PreToolUse, SessionStart, SessionEnd, PermissionRequest, and Notification hooks into ~/.claude/settings.json
3. Copy the default config to ~/.config/claude-guardian/guardian.config.json
4. Create a LaunchAgent so Guardian starts on login
5. Launch the app

Manual Start

Features

Analytics Dashboard (v2)
Click the menubar icon → Stats tab to see a full analytics dashboard powered by your local ~/.claude/ data:
- Today — cost, sessions, messages, tokens, token breakdown by type, rate limits (5-hour & 7-day), recent sessions
- All Time — lifetime totals, average daily cost, active days, model breakdown (Opus/Sonnet/Haiku)
- Projects — cost ranked by project with visual progress bars
- Trends — 7-day cost chart + 30-day daily history table
- Auto-syncs on file changes, 100% local — no data leaves your machine

Stop…