{"id":50861262,"url":"https://github.com/cooco119/claude-quota-tracker","last_synced_at":"2026-06-14T21:35:29.974Z","repository":{"id":364355742,"uuid":"1266872667","full_name":"cooco119/claude-quota-tracker","owner":"cooco119","description":"Track Claude Max usage windows, forecast \u0026 nudge on under-use, and schedule heavy work for the quiet night hours. Local-first macOS companion for Claude Code.","archived":false,"fork":false,"pushed_at":"2026-06-12T17:05:48.000Z","size":220,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T19:07:06.933Z","etag":null,"topics":["anthropic","claude","claude-code","claude-max","cli","dashboard","launchd","macos","menubar","productivity","quota","sqlite","swiftbar","token-usage","usage-tracking"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/cooco119.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-06-12T03:02:02.000Z","updated_at":"2026-06-12T17:05:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cooco119/claude-quota-tracker","commit_stats":null,"previous_names":["cooco119/claude-quota-tracker"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cooco119/claude-quota-tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cooco119%2Fclaude-quota-tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cooco119%2Fclaude-quota-tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cooco119%2Fclaude-quota-tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cooco119%2Fclaude-quota-tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cooco119","download_url":"https://codeload.github.com/cooco119/claude-quota-tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cooco119%2Fclaude-quota-tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34339195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["anthropic","claude","claude-code","claude-max","cli","dashboard","launchd","macos","menubar","productivity","quota","sqlite","swiftbar","token-usage","usage-tracking"],"created_at":"2026-06-14T21:35:29.317Z","updated_at":"2026-06-14T21:35:29.968Z","avatar_url":"https://github.com/cooco119.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Quota Tracker\n\n\u003e Track your Claude Max usage windows, never waste a quota window, and schedule\n\u003e heavy work for the quiet hours — a local-first macOS companion for Claude Code.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Platform: macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](#requirements)\n[![Node ≥22.5](https://img.shields.io/badge/node-%E2%89%A522.5-339933.svg?logo=node.js\u0026logoColor=white)](#requirements)\n[![Runtime deps: 0](https://img.shields.io/badge/runtime%20deps-0-success.svg)](#how-it-works)\n[![For Claude Code](https://img.shields.io/badge/for-Claude%20Code-8A2BE2.svg)](https://claude.com/claude-code)\n\n![Claude Quota Tracker dashboard](docs/dashboard.png)\n\nClaude's Max plan gives you a **5-hour rolling session window** and **weekly\nwindows** that quietly reset whether or not you used them. Quota Tracker keeps a\ntime series of your usage, forecasts whether you're on pace to fill (or waste) a\nwindow, nudges you when you're under-using, surfaces your **whole** token usage\nacross every Claude Code project, and can run deferrable batch work **unattended\nduring the quietest night hours** so a window never goes to waste.\n\nEverything runs locally. No account, no server, no telemetry — it reads\n`claude -p \"/usage\"` and your local Claude Code session logs, and stores them in\na SQLite file on your machine.\n\n---\n\n## Features\n\n- **📊 Usage tracking \u0026 forecast** — polls your 5h / weekly windows every 5\n  minutes, forecasts the reset-time usage from your burn rate, and tells you\n  *when* you'll hit 100% (not a meaningless \"\u003e100%\").\n- **🔔 Under-use nudges** — a macOS notification when a window is on pace to\n  reset unused, so you can put the spare capacity to work. (Over-use and\n  schedule-hint modes ship off by default.)\n- **🌙 Night scheduler** — queue heavy, non-urgent tasks and they run\n  unattended via headless `claude -p` during your configured night window,\n  starting at the historically **lowest-usage hour**. Permission-triaged\n  (read-only / write-scoped / destructive) with explicit confirmation.\n- **🖥️ Menubar glance** — a [SwiftBar](https://swiftbar.app) plugin shows the\n  most urgent window at a glance, with all three windows + sparklines in the\n  dropdown. Reads cached data only; never calls Claude.\n- **📈 Local web dashboard** — gauges, **total** per-model token usage, a\n  GitHub-style contribution heatmap, estimate-vs-actual accuracy, and queue\n  state. Self-contained inline SVG; opens with one menubar click.\n- **🧩 Claude Code plugin** — a skill + `UserPromptSubmit` hook so Claude itself\n  becomes quota-aware and can offer to defer heavy work to the night queue.\n\n---\n\n## Screenshots\n\n**`quota status`** — current windows, forecast, and 7-day totals:\n\n```text\nSession (5h): 39%  → ~58% by reset · resets Jun 13 1:40 AM\nWeek (all models): 59%  → ~72% by reset · resets Jun 13 11:00 AM\nWeek (Sonnet): 32%  → ~39% by reset · resets Jun 13 11:00 AM\n7d: $0.97 · 1,699,099 tok · 1 runs   (total Claude Code usage · session-log based)\n```\n\n**Menubar** (SwiftBar) — glance + dropdown:\n\n```text\nCQ 5h 39%\n---\nSession (5h): 39% → ~58% by reset Jun 13 1:40 AM\n-- ▂▂▂▂▂▂▁▁▁▁▁▁▁▁▁▃\nWeek (all models): 59% → ~72% by reset Jun 13 11:00 AM\n-- ▂▃▃▄▄▄▄▄▄▄▄▄▅▅▅▅\nOpen Dashboard\n```\n\n\u003e The dashboard and CLI messages are currently in Korean. PRs for i18n are very\n\u003e welcome.\n\n---\n\n## Requirements\n\n- **macOS** (Apple Silicon or Intel)\n- **Node ≥ 22.5** — uses the built-in `node:sqlite`; no native modules\n- **[Claude Code](https://claude.com/claude-code) CLI**, logged in (so\n  `claude -p \"/usage\"` works)\n- *(optional)* [SwiftBar](https://swiftbar.app) for the menubar plugin —\n  installed automatically by `setup.sh` if Homebrew is present\n\n---\n\n## Install\n\n```bash\ngit clone https://github.com/cooco119/claude-quota-tracker.git\ncd claude-quota-tracker\nnpm install\nbash scripts/setup.sh\n```\n\n`setup.sh` compiles the project, installs a tiny launcher to\n`~/.local/bin/quota`, registers a launchd agent that polls every 5 minutes,\nand starts the SwiftBar menubar. Config and data live in `~/.quota-tracker/`.\n\nTo remove: `quota uninstall` (your data is preserved).\n\n\u003e Why a launcher and not a single binary? An ad-hoc-signed Node SEA binary gets\n\u003e SIGKILLed by the Apple Silicon kernel once `cp` breaks its signature. Node is\n\u003e already a hard dependency, so a launcher is lighter and far more robust.\n\u003e `scripts/build-binary.sh` can still bake a standalone binary if you want one.\n\n---\n\n## Usage\n\n```bash\nquota status                 # current windows, forecast, 7-day totals (--json available)\nquota tasks                  # the night queue + recent runs\nquota dashboard --open       # open the web dashboard (idempotent)\n\n# Queue a heavy task to run unattended at the quietest night hour:\nquota enqueue --night --prompt \"...\" --size m --perm read-only\n\n# Run a destructive/urgent task manually, while you watch:\nquota executor --task \u003cid\u003e\n```\n\n`--perm` triages how the task may run unattended:\n\n| class | runs unattended | sandbox |\n|---|---|---|\n| `read-only` | ✅ | read-only tools only |\n| `write-scoped` | ✅ | isolated `git worktree` |\n| `destructive` | ❌ (manual only) | — |\n\nNight execution holds until your configured floor (default **2 AM**) and, once a\nfew days of history exist, targets the lowest-burn hour of the window.\n\n**What \"unattended\" honestly means** — three limits to know before you rely on it:\n\n- **The machine must be awake.** launchd's `StartInterval` does not fire (or wake\n  the Mac) during sleep, so a sleeping Mac runs nothing. Keep it awake for the\n  window, e.g. `sudo pmset repeat wake MTWRFSU 01:55:00` (wake before the floor)\n  or `caffeinate -s` while plugged in. `quota uninstall` doesn't touch pmset.\n- **The session window throttles throughput.** Running `claude -p` burns your 5h\n  session window, and execution pauses when it crosses `executor.sessionGuardPct`\n  (default 80%). So one night fills roughly one or two session windows' worth of\n  work, not the whole weekly window — raise `sessionGuardPct` if you want it to\n  burn harder overnight.\n- **It runs tasks that fit the time left.** A task whose size-timeout exceeds the\n  remaining window is skipped in favor of smaller tasks that fit (it runs earlier\n  on a later night), so the queue keeps draining rather than stalling.\n\n---\n\n## Claude Code plugin\n\nThis repo is also a Claude Code marketplace (`.claude-plugin/marketplace.json`):\n\n```text\n/plugin marketplace add cooco119/claude-quota-tracker\n/plugin install quota-tracker@quota-tracker-marketplace\n```\n\nIt installs a **skill** (so Claude can read your usage and defer heavy work via\nthe `quota` CLI) and a **`UserPromptSubmit` hook** that nudges Claude when your\nsession window is filling. The plugin is the Claude integration only — you still\nrun `bash scripts/setup.sh` once to install the CLI/daemon.\n\n---\n\n## How it works\n\n```\nclaude -p \"/usage\" ──poll(5m)──▶ window_readings ──▶ forecast ──▶ notify / menubar\n                                        │\n~/.claude/projects/*.jsonl ─ingest──▶ usage_events ─┐\n                                                     ├──▶ dashboard\nquota enqueue ──▶ tasks ──night executor──▶ task_runs┘\n```\n\n- **Zero runtime dependencies.** Everything is the Node standard library\n  (`node:sqlite`, `node:http`, `fs`). The dashboard's charts are hand-rolled\n  inline SVG — no CDN, no build step, works offline.\n- **Two separate data sources, on purpose.** `usage_events` (ingested from your\n  Claude Code session logs, deduped by `message.id`) is your total usage and\n  drives the dashboard's model/heatmap/token charts. `task_runs` is only the\n  orchestrator's own runs and powers cost + size-estimate accuracy. They are\n  never mixed into one number.\n  - *Scope:* out of the box this reads `~/.claude/projects`, where standard\n    Claude Code logs every project. If you run a **custom harness** (e.g. CCS, or\n    a non-default `CLAUDE_CONFIG_DIR`) that logs elsewhere, add its root to\n    `config.ingest.extraRoots` — otherwise the dashboard \"total\" undercounts.\n- **Idempotent, incremental ingest.** Session logs are read from a per-file\n  byte cursor (multibyte-safe), deduped on the `message.id` primary key, and\n  re-running is a no-op. A 26 MB / 300-file corpus ingests in well under a\n  second; subsequent polls only read what changed.\n\n---\n\n## Configuration\n\n`~/.quota-tracker/config.json` (see [`config.example.json`](config.example.json)):\n\n- `notify` — nudge modes, thresholds, quiet hours, cooldown\n- `nightWindow` — `start`/`end` (local wall-clock) + a one-time confirmation\n- `executor` — `sessionGuardPct` (default 80), `nightFloorHHMM` (default\n  `02:00`), per-size timeouts, `maxAttempts`\n- `dashboard` — `port` (default 47600), `idleShutdownMin`\n- `ingest` — `extraRoots` (extra session-log roots for custom harnesses; `~/`\n  expands to `$HOME`)\n\n---\n\n## Privacy\n\nEverything stays on your machine. Quota Tracker reads `claude -p \"/usage\"` and\nyour local `~/.claude/projects/*.jsonl` session logs, and writes a SQLite file\nunder `~/.quota-tracker/`. Nothing is sent anywhere. Token stats reflect Claude\nCode usage only (not claude.ai / the web app).\n\n---\n\n## Development\n\n```bash\nnpm run build        # tsc → dist/\nnpm test             # vitest (116 tests)\nnpm run typecheck\n```\n\nThe codebase is plain TypeScript ESM. `store.ts` / `forecast.ts` / `ingest.ts`\nare importable libraries; everything validates at system boundaries.\n\n---\n\n## License\n\n[MIT](LICENSE) © jaejun.lee\n\n🤖 Built with [Claude Code](https://claude.com/claude-code).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcooco119%2Fclaude-quota-tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcooco119%2Fclaude-quota-tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcooco119%2Fclaude-quota-tracker/lists"}