{"slug": "claumon-forecasting-claude-code-usage-limits-with-a-gamma-process", "title": "Claumon – Forecasting Claude Code usage limits with a Gamma process", "summary": "Claumon, a new open-source dashboard tool for Claude Code, provides real-time rate limit gauges, token and cost breakdowns, and 14-day usage trends via a single binary with no dependencies. The tool, available for macOS, Linux, and Windows, offers session forecasts with 80% confidence intervals, per-session token analysis, and a memory browser with relationship graphs and staleness alerts. Users can install it via Homebrew, download prebuilt binaries, or build from source, with optional service installation for automatic startup on login.", "body_md": "**Claude Code dashboard** - run it, see where your tokens go.\n\nSingle binary, zero config, one browser tab. Runs on macOS, Linux, and Windows.\n\nThere are plenty of Claude Code dashboards out there. This one isn't trying to be special - it's just my take on it, optimized for the things I care about: minimal, fast, and easy to set up.\n\nSingle binary, no dependencies, no build step, no config required. Run it and open a browser tab.\n\nIt gives you rate limit gauges with usage forecasts, per-session token breakdowns, cost estimates, historical trends, conversation history, and a memory browser with relationship graph, health scores, and staleness alerts. Everything updates in real time via SSE. Daily aggregates are stored in SQLite so you can track usage over weeks, not just the current session.\n\nLive dashboard: rate-limit gauges, token and cost breakdowns, and 14-day trends.\n\nSession forecast: projected usage at reset with an 80% confidence interval.\n\n**Homebrew (macOS / Linux):**\n\n```\nbrew install fabioconcina/claumon/claumon\nclaumon\n```\n\n**Download a prebuilt binary** from [the latest release](https://github.com/fabioconcina/claumon/releases/latest):\n\n```\n# macOS (Apple Silicon)\ncurl -Lo claumon https://github.com/fabioconcina/claumon/releases/latest/download/claumon-darwin-arm64\nchmod +x claumon\n./claumon\n\n# macOS (Intel)\ncurl -Lo claumon https://github.com/fabioconcina/claumon/releases/latest/download/claumon-darwin-amd64\nchmod +x claumon\n./claumon\n\n# Linux (x86_64)\ncurl -Lo claumon https://github.com/fabioconcina/claumon/releases/latest/download/claumon-linux-amd64\nchmod +x claumon\n./claumon\n\n# Windows (x86_64)\n# Download claumon-windows-amd64.exe from the releases page\n# If blocked by Defender: right-click the .exe -> Properties -> Unblock\n# Or run: Unblock-File claumon-windows-amd64.exe\n```\n\n**Build from source:**\n\n```\ngo install github.com/fabioconcina/claumon@latest\nclaumon\n```\n\nOpen [http://localhost:3131](http://localhost:3131) in your browser.\n\nclaumon reads credentials from `~/.claude/.credentials.json`\n\n(created by `claude /login`\n\n), or falls back to the OS credential store (macOS Keychain, Windows Credential Manager) used by the VS Code extension. If credentials are missing, session tracking still works. Only the API usage gauges are unavailable.\n\nRun claumon automatically on login so the dashboard is always available. First, move the binary to a permanent location, then register the service.\n\n**macOS:**\n\n```\nmkdir -p ~/.local/bin\nmv claumon ~/.local/bin/\n# Add to PATH if not already: export PATH=\"$HOME/.local/bin:$PATH\"\nclaumon service install\n```\n\nCreates a LaunchAgent at `~/Library/LaunchAgents/com.claumon.dashboard.plist`\n\n. Logs go to `~/.claumon/claumon.log`\n\n.\n\n**Linux:**\n\n```\nmv claumon ~/.local/bin/\nclaumon service install\n```\n\nCreates a systemd user unit at `~/.config/systemd/user/claumon.service`\n\n. Logs go to journald (`journalctl --user -u claumon`\n\n). By default, systemd user services stop when you log out. To keep claumon running after logout, enable lingering: `loginctl enable-linger $USER`\n\n.\n\n**Windows (PowerShell):**\n\n```\n# Move the exe to a permanent location\nNew-Item -ItemType Directory -Force \"$env:LOCALAPPDATA\\Programs\\claumon\"\nMove-Item claumon-windows-amd64.exe \"$env:LOCALAPPDATA\\Programs\\claumon\\claumon.exe\"\n\n# Add to PATH (current user, persists across sessions)\n$p = [Environment]::GetEnvironmentVariable('Path', 'User')\n[Environment]::SetEnvironmentVariable('Path', \"$p;$env:LOCALAPPDATA\\Programs\\claumon\", 'User')\n\n# Restart your terminal, then:\nclaumon service install\n```\n\nAdds claumon to the Windows Startup folder - it launches automatically (hidden) on login.\n\n**Manage the service:**\n\n```\nclaumon service status     # check if running\nclaumon service restart    # restart after config changes\nclaumon service uninstall  # stop and remove\n```\n\nNo root or admin required on any platform.\n\n```\nclaumon update\n```\n\nChecks GitHub releases for a newer version, downloads the right binary for your platform, and replaces the current one. If a background service is installed, it restarts automatically after the update.\n\nRemove the background service (if installed), delete the binary, and optionally remove local data (SQLite database, logs, config, pricing cache).\n\n**macOS / Linux:**\n\n```\nclaumon service uninstall\nrm ~/.local/bin/claumon\nrm -rf ~/.claumon\n```\n\n**Windows (PowerShell):**\n\n```\nclaumon service uninstall\nRemove-Item (Get-Command claumon).Source\nRemove-Item -Recurse \"$env:USERPROFILE\\.claumon\"\n```\n\n**Session usage**- 5-hour sliding window utilization with reset countdown** Weekly usage**- 7-day window utilization with reset countdown** Per-model quotas**- separate Opus and Sonnet weekly limits (when applicable)** Extra usage credits**- monthly limit and spend (if enabled) Gauges are color-coded: green (<50%), yellow (50–80%), red (>80%).\n\n**Projected utilization at reset**- an 80% credible interval and ETA to threshold for each rate-limit window, so you can see where you'll land before you get there.**Empirical-Bayes model, refit daily** from your own past windows, over a monotone (non-decreasing) usage process so the interval respects that utilization only grows within a window. Full spec in(LaTeX source:`internal/forecast/MODEL.pdf`\n\n).`MODEL.tex`\n\n**Benchmarked out-of-sample** with`claumon bench`\n\n- leave-one-out and temporal-holdout protocols, proper scoring (CRPS/pinball) with coverage and bias breakdowns.\n\n**Input / output / cache read / cache write** tokens per session**Estimated equivalent API cost** using current model pricing**Daily aggregates** with 14-day trend charts**Activity heatmap**- 24-hour breakdown of token activity by hour\n\n**Active sessions table**- project, model, tokens, cost, messages, last activity** Today / Recent toggle**- switch between today's sessions and the 50 most recent across all time** Running process detection**- shows which sessions are actively running with green \"active\" badge** Session detail view**- full message timeline with per-message token counts and tool usage** Automatic discovery**- watches`~/.claude/projects/`\n\nfor new and updated sessions\n\n**Live process table**- shows all running Claude Code processes with PID, chat title, project, type, and uptime** Stop button**- send SIGINT to gracefully stop any running process (conversation is preserved on disk)** Auto-refresh**- updates via SSE and periodic polling\n\n**All memory files**- CLAUDE.md, rules, auto-memory indexes, per-project memories** Search**across content, path, project name, and frontmatter** Filter by category**- CLAUDE.md, Rules, Index, Memory** Staleness indicators**- green (today), gray (<7d), yellow (7–30d), red (>30d)** Staleness alerts**- broken MEMORY.md links, orphaned files, index mismatches** VS Code integration**- click to open files in your editor via`vscode://`\n\nlinks\n\n**Per-file grading**- each memory file gets a letter grade (A–F) based on freshness, structure, specificity, and connectedness** Improvement suggestions**- actionable tips for low-scoring files (add frontmatter, link from MEMORY.md, etc.)\n\n**Interactive visualization**- nodes are memory files, edges show relationships** Project filters**- focus on specific projects** Clickable legend**- toggle node types on/off** Click to navigate**- click a node to jump to its file in the memory browser\n\n| Key | Action |\n|---|---|\n`1` `2` `3` |\nSwitch to Dashboard, Memories, Graph tab |\n`/` |\nJump to memory search |\n`Esc` |\nClose session detail panel |\n\nThe dashboard uses Server-Sent Events (SSE) - no polling, no manual refresh. Changes appear instantly:\n\n**Usage gauges** update every 2 minutes (configurable) from the Claude API**Session table** updates when any`.jsonl`\n\nsession file changes on disk**Memory browser** highlights changed files with a visual pulse**Graph and staleness** re-render when memory files change on disk\n\nA status dot in the top bar shows connection state (green = connected, red = disconnected).\n\nOptional. Create `~/.claumon/config.json`\n\n:\n\n```\n{\n  \"port\": 3131,\n  \"poll_interval_seconds\": 120,\n  \"credentials_path\": \"~/.claude/.credentials.json\",\n  \"claude_dir\": \"~/.claude\",\n  \"db_path\": \"~/.claumon/usage.db\",\n  \"stuck_threshold_minutes\": 10\n}\n```\n\nAll fields are optional. Defaults are shown above; claumon works without a config file.\n\nclaumon stores usage snapshots and daily aggregates in a SQLite database at `~/.claumon/usage.db`\n\n. Historical data is backfilled automatically on first startup by scanning all existing session files.\n\nThe database uses WAL mode for concurrent reads during writes. No maintenance required.\n\nclaumon combines three data sources:\n\n**Claude API**(`/api/oauth/usage`\n\n) - polled periodically for rate limit utilization. Requires OAuth credentials from`claude /login`\n\n.**Session files**(`~/.claude/projects/*/*.jsonl`\n\n) - watched via`fsnotify`\n\nfor real-time token counting. Each JSONL file is parsed for message-level token usage.**Memory files**(`~/.claude/projects/*/memory/*.md`\n\n,`CLAUDE.md`\n\n, rules) - discovered and parsed for frontmatter, rendered as HTML, analyzed for cross-references and staleness.\n\nEverything is embedded in a single binary via `//go:embed`\n\n- no external files, no Node.js, no build step for the frontend.\n\n``` php\ngraph TD\n    API[\"Claude OAuth API\"] --> ENGINE\n    JSONL[\"Session JSONL Files\"] --> ENGINE\n    MEM[\"Memory Files\"] --> ENGINE\n    PRICE[\"Pricing Data\"] --> ENGINE\n\n    ENGINE[\"Pollers · Watchers · Parsers\"] --> DB[\"SQLite\"]\n    ENGINE --> CACHE[\"In-Memory Cache\"]\n    ENGINE --> SSE[\"SSE Broker\"]\n\n    DB --> HTTP[\"HTTP Server\"]\n    CACHE --> HTTP\n    JSONL -->|\"parsed fresh\"| HTTP\n    SSE --> HTTP\n\n    HTTP --> SPA[\"Embedded SPA\"]\n```\n\nMIT", "url": "https://wpnews.pro/news/claumon-forecasting-claude-code-usage-limits-with-a-gamma-process", "canonical_source": "https://github.com/fabioconcina/claumon", "published_at": "2026-06-06 09:52:57+00:00", "updated_at": "2026-06-06 10:18:35.241036+00:00", "lang": "en", "topics": ["ai-tools", "ai-products", "large-language-models"], "entities": ["Claude Code", "Claumon", "Homebrew", "SQLite", "macOS", "Linux", "Windows", "fabioconcina"], "alternates": {"html": "https://wpnews.pro/news/claumon-forecasting-claude-code-usage-limits-with-a-gamma-process", "markdown": "https://wpnews.pro/news/claumon-forecasting-claude-code-usage-limits-with-a-gamma-process.md", "text": "https://wpnews.pro/news/claumon-forecasting-claude-code-usage-limits-with-a-gamma-process.txt", "jsonld": "https://wpnews.pro/news/claumon-forecasting-claude-code-usage-limits-with-a-gamma-process.jsonld"}}