Claude Governor

August 30, 2026 · View on GitHub

Automated capacity governor for Claude Code subscription usage.

Overview

Claude Governor monitors Claude Code subscription usage in real time and predicts whether running worker processes will be stopped by hitting a usage window limit before that window resets. When the forecast shows workers will exhaust a window early, the governor scales down the fleet to a safe level; when capacity remains, it allows or adds workers.

This system replaces the fragile capacity-governor.sh (TUI screen-scraping, stateless, incomplete off-peak logic) with a reliable, accurate, and extensible Rust daemon.

Key Features

Direct API polling — Uses /api/oauth/usage endpoint instead of screen-scraping
Exhaustion prediction — Forecasts whether each usage window will hit 100% before reset
Off-peak awareness — Accounts for 2x promotion windows when forecasting capacity
Adaptive burn rate — Learns actual per-worker consumption empirically (p75 EMA)
Graceful scaling — Never kills workers mid-task; only scales down idle workers
Multi-agent support — Supports Sonnet, Opus, and pay-per-token providers
Zero runtime dependencies — Single statically-linked binary

Installation

Option 1: Pre-built binary (recommended)

curl -fsSL https://raw.githubusercontent.com/jedarden/claude-governor/main/install.sh | bash

Option 2: Build from source

cargo build --release
cp target/release/cgov ~/.local/bin/
chmod +x ~/.local/bin/cgov

Quickstart

# Initialize configuration and directories
cgov init

# Edit configuration (set agents, pricing, etc.)
cgov config --edit

# Run health check
cgov doctor

# Enable and start daemon services (systemd or tmux)
cgov enable

Directory Structure

~/.config/claude-governor/
├── governor.yaml        # Main configuration file
~/.local/share/claude-governor/
├── governor.log         # Governor daemon logs
└── collector.log        # Token collector logs
~/.needle/state/
├── heartbeats/          # Worker heartbeat files (managed by NEEDLE)
└── ...                  # Other state files

Configuration

The governor reads configuration from ~/.config/claude-governor/governor.yaml:

agents:
  sonnet:
    launch_cmd: needle run --agent=claude-anthropic-sonnet --workspace={workspace} --force
    session_pattern: needle-claude-anthropic-sonnet-*
    heartbeat_dir: ~/.needle/state/heartbeats
    workspace: /path/to/project

polling:
  interval_seconds: 300
  usage_api_url: https://api.anthropic.com/api/oauth/usage

pricing:
  claude-sonnet-4-6:
    input_per_mtok: 3.0
    output_per_mtok: 15.0
    cache_write_5m_per_mtok: 3.75
    cache_write_1h_per_mtok: 6.0
    cache_read_per_mtok: 0.3

Usage

# Poll usage data from API
cgov poll

# Show window capacity forecasts
cgov forecast

# Show worker count and targets
cgov workers

# Manually set target worker count
cgov scale 3

# Show capacity status (with --watch for live updates)
cgov status
cgov status --watch

# Run health diagnostic checks
cgov doctor

# Simulate future capacity trajectory
cgov simulate --workers 4 --hours 24

# View recent scaling decisions
cgov explain

# Tail governor logs
cgov logs --follow

# Print or edit configuration
cgov config
cgov config --edit

# Print version, build info, and component status
cgov version

# Run one token collection pass (or start daemon)
cgov collect
cgov collect --daemon

# Query token history from SQLite mirror
cgov token-history --last 5
cgov token-history --compare
cgov token-history --fleet

# Run the governor daemon (main capacity management loop)
cgov daemon

Daemon Management

# Initialize (create config, directories, install systemd units)
cgov init

# Enable services (install + start systemd/tmux)
cgov enable

# Start services
cgov start
cgov start observe
cgov start act

# Stop all services, or pause only automated scaling and alerting
cgov stop
cgov stop act

# Restart services
cgov restart

# Disable services (stop + remove systemd units)
cgov disable
cgov disable --purge

The governor runs as two independently supervised loops. _observe polls usage, updates burn rates and forecasts, and keeps state fresh without launching or killing workers. _act reads that state and performs scaling and alerting. Stop act when actions need to be paused while telemetry should continue; doctor reports this as a warning rather than treating the intentional pause as a telemetry failure.

Usage Windows

The governor tracks three parallel usage windows:

Window	Reset	Purpose
`five_hour`	Rolling 5-hour session	Burst rate limiting
`seven_day`	7-day rolling window	Weekly quota (all models)
`seven_day_sonnet`	7-day rolling window	Weekly Sonnet quota

Alerting

The governor creates HUMAN-type beads via NEEDLE when specific conditions are detected.

See docs/research/alerts.md for complete alert documentation including:

All alert types (cutoff_imminent, sonnet_cutoff_risk, session_cutoff_risk, collector_offline, etc.)
Severity levels and thresholds
Cooldown deduplication
Troubleshooting steps

Bead visibility

NEEDLE Pluck uses the resolved workspace's .beads store, the bead-rs --ready frontier, and exact exclude_labels matching. For worker launches, use an absolute --workspace path; an empty custom label list does not disable the built-in exclusions, and wildcard-looking labels are literal strings.

Use docs/bead-visibility-quickref.md for the commands and common mistakes, or docs/bead-visibility-troubleshooting.md for the full starvation response procedure. The authoritative current filter inventory is docs/plan/pluck-configuration.md.

Project Structure

src/
├── alerts.rs       # Alert conditions and bead creation
├── burn_rate.rs    # Exhaustion forecasting and safe worker calculation
├── collector.rs    # Token usage collection from Claude Code logs
├── governor.rs     # Main governor loop and scaling logic
├── poller.rs       # Usage API polling
├── worker.rs       # Worker discovery and scaling
└── ...

Documentation

docs/plan/plan.md — Complete system design plan
docs/research/ — Research on API pricing, usage tracking, off-peak promotions
docs/bead-visibility-troubleshooting.md — Comprehensive troubleshooting guide for bead visibility issues, common pitfalls, and configuration best practices
docs/bead-visibility-quickref.md — Quick reference for bead visibility configuration and common pitfalls
docs/filter-patterns-reference.md — Historical Pluck filter patterns and query examples
docs/plan/pluck-configuration.md — Authoritative current Pluck filter and label settings
docs/pluck-workspace-paths.md — Workspace path configuration and discovery
docs/pluck-query-results.md — Historical query patterns and filter syntax examples
docs/research/bead-visibility-configuration.md — Historical six-layer configuration map for bead visibility

License

Apache-2.0 — see LICENSE.

Part of jedarden.com

This GitHub repo is a read-only mirror of git.ardenone.com/jedarden/claude-governor — issues and PRs are welcome here either way.