{"id":47300077,"url":"https://github.com/mkrowiarz/ccmonitor","last_synced_at":"2026-05-24T20:03:12.056Z","repository":{"id":344891717,"uuid":"1183568718","full_name":"mkrowiarz/ccmonitor","owner":"mkrowiarz","description":"Terminal dashboard for monitoring Claude Code usage, sessions, and rate limits","archived":false,"fork":false,"pushed_at":"2026-03-21T09:55:46.000Z","size":140,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T05:28:55.232Z","etag":null,"topics":["bubbletea","claude-code","cli","dashboard","golang","monitoring","terminal","tui"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mkrowiarz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-16T18:33:04.000Z","updated_at":"2026-03-21T09:55:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mkrowiarz/ccmonitor","commit_stats":null,"previous_names":["mkrowiarz/ccmonitor"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/mkrowiarz/ccmonitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkrowiarz%2Fccmonitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkrowiarz%2Fccmonitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkrowiarz%2Fccmonitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkrowiarz%2Fccmonitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkrowiarz","download_url":"https://codeload.github.com/mkrowiarz/ccmonitor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkrowiarz%2Fccmonitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33448586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-24T19:21:36.376Z","status":"ssl_error","status_checked_at":"2026-05-24T19:21:10.562Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bubbletea","claude-code","cli","dashboard","golang","monitoring","terminal","tui"],"created_at":"2026-03-17T00:03:47.093Z","updated_at":"2026-05-24T20:03:12.050Z","avatar_url":"https://github.com/mkrowiarz.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ccmonitor\n\n\u003ca href=\"https://github.com/mkrowiarz/ccmonitor/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/release/mkrowiarz/ccmonitor.svg\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/mkrowiarz/ccmonitor/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/mkrowiarz/ccmonitor\" alt=\"License\"\u003e\u003c/a\u003e\n\nA terminal dashboard for monitoring [Claude Code](https://docs.anthropic.com/en/docs/claude-code) usage, sessions, and rate limits.\n\nBuilt with [Bubble Tea](https://github.com/charmbracelet/bubbletea) and [Lip Gloss](https://github.com/charmbracelet/lipgloss).\n\n## Features\n\n- **Dashboard** — today/lifetime message \u0026 token counts, active sessions, rate limit utilization\n- **Activity** — daily message sparkline chart + recent prompt history\n- **Processes** — full-width table of running Claude Code instances with CPU/memory/uptime\n- **Rate limits** (macOS only) — 5-hour and 7-day window utilization with progress bars, reset countdowns, and burn-rate indicators\n- Auto-refreshing (configurable interval)\n- Responsive layout (adapts to narrow terminals)\n- Graceful degradation when data sources are unavailable\n\n## Data sources\n\n| Data | Source |\n|------|--------|\n| Messages, sessions, tokens | `~/.claude/stats-cache.json` |\n| Recent prompts | `~/.claude/history.jsonl` |\n| Active processes | `ps` + `lsof` (macOS) or `/proc` (Linux) |\n| Rate limits | Anthropic OAuth usage API via macOS Keychain (macOS only) |\n\n## Requirements\n\n- Go 1.25+\n- macOS or Linux\n- Claude Code installed (for data in `~/.claude/`)\n- macOS Keychain credentials for rate limit data (macOS only, optional)\n\n## Install\n\n### Pre-built binary\n\nDownload the latest release for your platform:\n\n```bash\n# macOS (Apple Silicon)\ncurl -L https://github.com/mkrowiarz/ccmonitor/releases/latest/download/ccmonitor-darwin-arm64 -o /usr/local/bin/ccmonitor \u0026\u0026 chmod +x /usr/local/bin/ccmonitor\n\n# macOS (Intel)\ncurl -L https://github.com/mkrowiarz/ccmonitor/releases/latest/download/ccmonitor-darwin-amd64 -o /usr/local/bin/ccmonitor \u0026\u0026 chmod +x /usr/local/bin/ccmonitor\n\n# Linux (x86_64)\ncurl -L https://github.com/mkrowiarz/ccmonitor/releases/latest/download/ccmonitor-linux-amd64 -o /usr/local/bin/ccmonitor \u0026\u0026 chmod +x /usr/local/bin/ccmonitor\n\n# Linux (arm64)\ncurl -L https://github.com/mkrowiarz/ccmonitor/releases/latest/download/ccmonitor-linux-arm64 -o /usr/local/bin/ccmonitor \u0026\u0026 chmod +x /usr/local/bin/ccmonitor\n```\n\n### Go install\n\n```\nGOBIN=~/.local/bin go install github.com/mkrowiarz/ccmonitor@latest\n```\n\nOr without `GOBIN`, it installs to `~/go/bin` by default.\n\n### From source\n\n```\ngit clone https://github.com/mkrowiarz/ccmonitor.git\ncd ccmonitor\nmake install        # installs to ~/.local/bin\n```\n\nMake sure `~/.local/bin` is in your `PATH`.\n\n### Update\n\n```\nccmonitor update\n```\n\nChecks the latest GitHub release and, if newer than the running build, downloads\nthe matching binary for your platform and atomically replaces the current\nexecutable in place. Requires write permission to the binary's directory — if it\nlives somewhere root-owned (e.g. `/usr/local/bin`), re-run with `sudo` or\nreinstall manually. Builds installed via `go install` report no version and will\nalways update to the latest release.\n\n### Uninstall\n\n```\nmake uninstall\n```\n\n## Usage\n\n```\nccmonitor                    # default: 10s refresh\nccmonitor -interval 5        # 5s refresh\nccmonitor -no-rate-limits    # hide the rate limits panel\nccmonitor -minimal           # dashboard only, no activity/analytics tabs\nccmonitor -waybar            # print one Waybar JSON line and exit\n```\n\n| Flag | Description |\n|------|-------------|\n| `-interval N` | Refresh interval in seconds (default: 10) |\n| `-no-rate-limits` | Disable the rate limits panel |\n| `-minimal` | Dashboard only — no Activity/Analytics tabs |\n| `-waybar` | Print one [Waybar](#waybar) JSON line for rate limits and exit |\n| `-version` | Print version and exit |\n\n| Command | Description |\n|---------|-------------|\n| `waybar-setup` | Print [Waybar](#waybar) module setup instructions and exit |\n| `update` | Update ccmonitor to the latest GitHub release (see [Update](#update)) |\n\n### Keyboard shortcuts\n\n| Key | Action |\n|-----|--------|\n| `q` | Quit |\n| `r` | Force refresh |\n| `Tab` | Cycle tabs |\n| `1` | Dashboard |\n| `2` | Activity |\n| `3` | Analytics |\n\n## Platform notes\n\n| Feature | macOS | Linux |\n|---------|-------|-------|\n| Process monitoring | `ps` + `lsof` | `ps` + `/proc` |\n| Usage stats | `~/.claude/stats-cache.json` | `~/.claude/stats-cache.json` |\n| Activity history | `~/.claude/history.jsonl` | `~/.claude/history.jsonl` |\n| Rate limits | Keychain + OAuth API | `~/.claude/.credentials.json` + OAuth API |\n\n## Rate limits\n\nThe rate limits panel shows your Anthropic API usage across two rolling windows:\n\n- **5-hour window** — short-term burst usage\n- **7-day window** — longer-term sustained usage\n\nEach window displays utilization percentage, a progress bar, time until reset, and a burn-rate indicator dot that compares your usage pace against the window's elapsed time:\n\n| Dot | Condition | Meaning |\n|-----|-----------|---------|\n| Green | usage ≤ elapsed + 5% | On track — usage is proportional to time elapsed |\n| Yellow | usage \u003e elapsed + 5% | Elevated — burning faster than the window replenishes |\n| Red | usage \u003e elapsed + 15% | Hot — at risk of hitting the limit before the window resets |\n\nFor example, if 50% of the 5-hour window has elapsed but you've used 70% of your quota, the difference is +20% — the dot turns red.\n\n### How it works\n\n1. ccmonitor reads your OAuth access token — from the macOS Keychain (`Claude Code-credentials`) on macOS, or from `~/.claude/.credentials.json` on Linux\n2. It calls the Anthropic usage API (`api.anthropic.com/api/oauth/usage`) to fetch current utilization\n3. Results are cached locally (`~/.ccmonitor/usage-cache.json`) with a **10-minute TTL** — the API is not called more frequently than that\n4. If the API returns 429 (rate limited), ccmonitor enters a ~10-minute cooldown before retrying\n\nUse `-no-rate-limits` to disable this feature entirely.\n\n## Waybar\n\n`ccmonitor -waybar` prints a single line of [Waybar](https://github.com/Alexays/Waybar) JSON\n(`text`, `tooltip`, `class`) describing your rate-limit windows, then exits. It reuses the same\n10-minute on-disk cache as the dashboard, so polling every minute only hits the API every 10 minutes.\n\nRun `ccmonitor waybar-setup` to print ready-to-paste config (module JSON, CSS, and reload steps)\nwith the binary's absolute path filled in. The manual steps are:\n\n```jsonc\n\"custom/claude\": {\n    \"exec\": \"ccmonitor -waybar\",\n    \"return-type\": \"json\",\n    \"interval\": 60,\n    \"tooltip\": true,\n    \"on-click\": \"ghostty -e ccmonitor\"  // optional: open the full dashboard\n}\n```\n\n…and reference `\"custom/claude\"` in one of your `modules-*` arrays. Give the module the same\n\"pill\" look as the rest of your bar (tweak to match your theme, or fold `#custom-claude` into\nyour existing pill selector), then layer the utilization colors on top via the CSS `class`:\n\n```css\n#custom-claude {\n    padding: 4px 10px;\n    margin: 0px 2px;\n    background-color: rgba(48, 52, 70, 0.35);\n    border: 2px solid rgba(98, 104, 128, 0);\n    border-radius: 5px;\n}\n#custom-claude:hover    { border: 2px solid rgba(98, 104, 128, 1); }\n\n#custom-claude.ok       { color: #a6d189; }            /* \u003c 50%  */\n#custom-claude.warning  { color: #e5c890; }            /* 50–80% */\n#custom-claude.critical { color: #e78284; font-weight: bold; } /* ≥ 80% */\n#custom-claude.error    { color: #838ba7; }            /* token missing / API down */\n```\n\nThe `text` starts with a Nerd Font glyph (`󰚩`), so the module needs a Nerd Font in your bar.\n\n### Click to open the dashboard\n\nThe simplest `on-click` just launches the TUI in a terminal: `\"on-click\": \"ghostty -e ccmonitor\"`.\nFor a floating, toggleable dropdown on Hyprland, point `on-click` at a small script that spawns\nthe TUI on a special workspace and toggles its visibility:\n\n```bash\n#!/usr/bin/env bash\nset -euo pipefail\nclass=com.ccmonitor.popup   # must be a valid GTK app-id (reverse-DNS, has a dot)\nws=ccmonitor\nif hyprctl clients -j | jq -e \".[] | select(.class==\\\"$class\\\")\" \u003e/dev/null; then\n    hyprctl dispatch togglespecialworkspace \"$ws\"\nelse\n    hyprctl dispatch exec \"[workspace special:$ws silent] ghostty --class=$class -e ccmonitor\"\n    hyprctl dispatch togglespecialworkspace \"$ws\"\nfi\n```\n\n…plus a Hyprland rule to float and center it:\n\n```\nwindowrulev2 = float,        class:^(com\\.ccmonitor\\.popup)$\nwindowrulev2 = size 900 520, class:^(com\\.ccmonitor\\.popup)$\nwindowrulev2 = center,       class:^(com\\.ccmonitor\\.popup)$\n```\n\n\u003e **Gotcha:** some terminals (e.g. ghostty) ignore `--class` unless it's a valid GTK app-id\n\u003e containing a dot. A bare name like `ccmonitor-popup` is silently dropped (ghostty falls back\n\u003e to `com.mitchellh.ghostty`), which breaks both the window rule and the script's already-open\n\u003e check — so every click spawns a new instance.\n\n## Credits\n\n- [kvaps/claude-code-usage](https://gist.github.com/kvaps/84fa5963df1bff9cec65b57afd54e1e4) — inspiration for the usage API integration\n- [MacDev](https://github.com/arvindjuneja/MacDev) — initial idea for an open-source Claude Code monitor\n- [Bubble Tea](https://github.com/charmbracelet/bubbletea) — terminal UI framework\n- [Lip Gloss](https://github.com/charmbracelet/lipgloss) — terminal styling and layout\n- [ntcharts](https://github.com/NimbleMarkets/ntcharts) — terminal bar charts\n- [Catppuccin](https://catppuccin.com/) — color theme\n- [Zellij](https://zellij.dev/) — tmux replacement that makes the Claude Monitor look beautiful\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — AI pair programmer that co-built this project\n\n## Author\n\nMichał Krowiarz — [@mkrowiarz](https://github.com/mkrowiarz)\n\nBuilt with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic's AI coding agent).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkrowiarz%2Fccmonitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkrowiarz%2Fccmonitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkrowiarz%2Fccmonitor/lists"}