Claude Code Watch

A command-line tool to monitor your Claude Code subscription usage, similar to claude.ai/settings/usage.

Features

Implemented

• Real-time usage - Session (5h) and weekly limits with progress bars
• Analytics mode - Historical trends, sparklines, peak usage patterns
• Cost analysis - Compare API costs vs subscription value (Pro/Max)
• Auto-collection - Systemd timer for hourly usage tracking
• Admin API - Organization-level usage data (optional)
• JSON output - Machine-readable output for scripting
• Setup wizard - Interactive configuration
• Cross-platform - Linux, macOS, Windows
• Zero dependencies - Python stdlib only

Roadmap

• Shell prompt - Compact output for PS1/starship/oh-my-zsh
• Tmux integration - Status bar with session % and reset time
• Watch mode - Live updating display
• Notifications - Desktop alerts at usage thresholds
• Hook generator - Claude Code pre-session warnings
• Forecast - Predict when limits will be hit
• CSV export - Export history for external tools
• HTML reports - Weekly/monthly usage reports

See docs/FEATURES.md for detailed specifications.

Installation

One-liner (Recommended)

curl -fsSL https://raw.githubusercontent.com/Asi0Flammeus/claude-code-watch/main/install.sh | bash

This auto-detects and uses the best available installer (uv > pipx > pip).

Manual Install

uv (fastest):

uv tool install git+https://github.com/Asi0Flammeus/claude-code-watch

pipx:

pipx install git+https://github.com/Asi0Flammeus/claude-code-watch

pip:

pip install git+https://github.com/Asi0Flammeus/claude-code-watch

Update

ccw --update              # Check and install updates
ccw --update check        # Check only
uv tool upgrade claude-watch  # Or use uv directly

Quick Start

claude-watch           # Show current usage
claude-watch -a        # With analytics
claude-watch --setup   # Configure auto-collection
ccw                    # Short alias

Example Output

Plan usage limits

Current session      ████████░░░░░░░░░░░░░░░░░  34% used
Resets in 3 hr 25 min

Weekly limits

All models           ██░░░░░░░░░░░░░░░░░░░░░░░  9% used
Resets Tue 9:59 AM

Sonnet only          ░░░░░░░░░░░░░░░░░░░░░░░░░  1% used
Resets Mon 6:59 PM

Usage

Command	Description
claude-watch	Show current usage
claude-watch -a	Show analytics with trends
claude-watch -j	Output raw JSON
claude-watch --setup	Run setup wizard
claude-watch --config	Show configuration
claude-watch --prompt	Compact output for shell prompts
claude-watch -p minimal	Minimal prompt format
claude-watch --tmux	Output for tmux status bar
claude-watch --watch	Live updating display (30s interval)
claude-watch -w 60	Live display with 60s interval
claude-watch --forecast	Show usage projections
claude-watch --notify	Send desktop notification
claude-watch --export csv	Export history to CSV
claude-watch --install-hook	Install Claude Code hook
claude-watch --no-color	Disable colors (for piping)
claude-watch --no-record	Don't save to history
ccw	Short alias (configure in shell)

Shell Prompt Integration

Embed usage in your shell prompt with --prompt:

claude-watch --prompt              # S:45% 2h15m→ (default format)
claude-watch -p minimal            # 45%→
claude-watch -p full               # S:45% W:12%→
claude-watch -p icon               # 🟢45%→
claude-watch --prompt --prompt-color  # With ANSI colors

Exit codes for scripting:

• 0 - OK (usage < 75%)
• 1 - Warning (75-89%)
• 2 - Critical (≥90%)
• 3 - Error (no data)

Trend indicators: ↑ increasing, ↓ decreasing, → stable

Bash (PS1)

# Add to ~/.bashrc
claude_usage() {
    claude-watch -p minimal 2>/dev/null || echo "?"
}
PS1='[\u@\h \W $(claude_usage)] \$ '

Zsh

# Add to ~/.zshrc
claude_usage() {
    claude-watch -p icon 2>/dev/null || echo "?"
}
RPROMPT='$(claude_usage)'

Starship

# Add to ~/.config/starship.toml
[custom.claude]
command = "claude-watch -p minimal"
when = true
format = "[$output]($style) "
style = "blue"

Oh-My-Zsh

# Create ~/.oh-my-zsh/custom/themes/claude.zsh-theme
PROMPT='%{$fg[cyan]%}%c%{$reset_color%} $(claude-watch -p icon 2>/dev/null) %(!.#.$) '

Tmux Integration

The --tmux flag outputs usage with tmux-specific color codes:

claude-watch --tmux    # #[fg=green]S:45% 2h15m #[fg=green]W:12%#[default]

Exit codes match --prompt for conditional coloring in tmux:

• 0 - OK (green)
• 1 - Warning (yellow, 75-89%)
• 2 - Critical (red, ≥90%)
• 3 - Error

Tmux Status Bar

# Add to ~/.tmux.conf
set -g status-right '#(claude-watch --tmux 2>/dev/null)'
set -g status-interval 60  # Update every 60 seconds

For more control, use a script:

# ~/.local/bin/tmux-claude-usage
#!/bin/bash
claude-watch --tmux 2>/dev/null || echo "#[fg=yellow]?#[default]"

# In ~/.tmux.conf
set -g status-right '#(~/.local/bin/tmux-claude-usage)'

Claude Code Hook Integration

Automatically check usage before each Claude Code operation with a pre-tool hook:

# Generate hook script (prints to stdout)
claude-watch --generate-hook > ~/.claude/hooks/usage-hook.sh
chmod +x ~/.claude/hooks/usage-hook.sh

# Or install automatically
claude-watch --install-hook

The --install-hook command:

1. Creates ~/.claude/hooks/claude-watch-hook.sh
2. Adds hook to ~/.claude/settings.json (PreToolUse)

Configuration (environment variables):

Variable	Description	Default
CLAUDE_USAGE_THRESHOLD	Warning threshold %	85
CLAUDE_WATCH_SILENT	Suppress non-critical output	0
CLAUDE_WATCH_BLOCKING	Block operations at 95%+	0

Example - Stricter limits:

export CLAUDE_USAGE_THRESHOLD=75
export CLAUDE_WATCH_BLOCKING=1  # Prevent operations at 95%+

To uninstall, remove the hook entry from ~/.claude/settings.json.

Environment Variables

Variable	Description
CLAUDE_WATCH_NO_COLOR	Disable colors when set to any non-empty value
CLAUDE_WATCH_CACHE_TTL	Cache TTL in seconds (default: 60)
CLAUDE_WATCH_HISTORY_DAYS	History retention in days (default: 180)
CLAUDE_USAGE_THRESHOLD	Hook warning threshold (default: 85)
CLAUDE_WATCH_SILENT	Hook: suppress non-blocking output
CLAUDE_WATCH_BLOCKING	Hook: block at 95%+ usage

Setup Wizard

First run prompts for optional configuration:

1. Admin API Key - For organization usage data (requires admin role)
2. Auto-collection - Hourly systemd timer for analytics
3. Subscription plan - Pro ($20), Max 5x ($100), or Max 20x ($200)

Re-run anytime with claude-watch --setup.

Analytics Mode

With -a flag, shows:

• Sparkline trends - 24h and 7d usage patterns
• Peak analysis - Busiest days/hours
• Usage prediction - Estimated time to limits
• Cost comparison - API equivalent vs subscription value
• Recommendations - Optimal plan based on usage

Shell Completions

Tab completion is available for Bash, Zsh, and Fish shells.

Bash

Add to ~/.bashrc:

source /path/to/claude-watch/completions/claude-watch.bash

Or copy to system completions:

sudo cp completions/claude-watch.bash /etc/bash_completion.d/claude-watch

Zsh

Add to ~/.zshrc (before compinit):

fpath=(/path/to/claude-watch/completions $fpath)
autoload -Uz compinit && compinit

Or copy to a directory in your $fpath:

cp completions/claude-watch.zsh /usr/local/share/zsh/site-functions/_claude-watch

Fish

Copy to Fish completions directory:

cp completions/claude-watch.fish ~/.config/fish/completions/

Completions also work for the ccw alias.

Requirements

• Python 3.8+
• Claude Code authenticated (claude login)

Credentials read from:

• ~/.claude/.credentials.json (Linux/Windows)
• macOS Keychain (macOS)

Data Storage

File	Purpose
~/.claude/.usage_config.json	Configuration
~/.claude/.usage_history.json	Usage history (180 days)

API Reference

OAuth API (default)

• Endpoint: https://api.anthropic.com/api/oauth/usage
• Auth: Bearer token from Claude Code credentials
• Data: Current session and weekly utilization

Admin API (optional)

• Endpoint: https://api.anthropic.com/v1/organizations/usage_report/messages
• Auth: Admin API key (sk-ant-admin-...)
• Data: Historical token usage with model breakdown

Troubleshooting

"Credentials not found" - Run claude login

"Authentication failed" - Run claude logout && claude login

Colors not showing - Terminal must support ANSI; use --no-color for pipes

License

MIT