token-burn
AGENTS.md6 starsChanged 7 days agoMITView on GitHub
Guidance for coding agents working in this repository. Build a small, reliable daemon and CLI for monitoring live subscription quota usage for AI coding tools. The primary use case is live quota visibility: Do not infer subscription usage from local session files, transcripts, token logs, or pricing estimates unless explicitly requested later. This project is about provider live usage signals. The implementation is Go. - Treat OAuth files and keychain values as secrets. - Redact secrets in logs and diagnostics.…
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .cursor/rules/beads.mdcCursor rule
- beadsSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
21 rules. About 1 is common, 10 are distinctive, and 10 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈10
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Do not infer subscription usage from local session files, transcripts, token logs, or pricing estimates unless explicitly requested later.
- Distinctive: line 56
Keep the provider interface small and shaped around live usage windows.
- Very specific: line 57
Prefer table-driven tests with the standard testing package.
- Distinctive: line 60
Never log raw access tokens, refresh tokens, cookies, or authorization headers.
- Distinctive: line 62
Use UTC timestamps in storage.
- Distinctive: line 63
Keep the TUI a read-only view over SQLite.
- Common: line 67
Treat OAuth files and keychain values as secrets.
- Distinctive: line 69
Do not export account email as an OTel attribute by default.
- Very specific: line 94
Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Very specific: line 95
Run bd prime for detailed command reference and session close protocol
- Very specific: line 96
Use bd remember for persistent knowledge — do NOT use MEMORY.md files
- Very specific: line 104
Conservative (default): Use bd for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked.
- Very specific: line 105
Minimal: Keep tool instruction files as pointers to bd prime.
- Distinctive: line 106
Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of …
- Distinctive: line 112
File issues for remaining work: - Create beads for anything that needs follow-up
- Distinctive: line 130
Do not commit or push without clear authority from the active profile or the current user request.
- Distinctive: line 131
If a required sync or push is blocked, stop and report the exact command and error.
- Very specific: line 137
Use Beads (bd) for durable task tracking in repositories that include it.
- Very specific: line 151
Use bd for all task tracking.
- Very specific: line 152
Run bd prime when Beads context is missing or stale.
- Very specific: line 153
Keep persistent project memory in Beads via bd remember.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md - token-burn
Guidance for coding agents working in this repository.
Project Intent
Build a small, reliable daemon and CLI for monitoring live subscription quota usage for AI coding tools.
The primary use case is live quota visibility:
- percentage used
- reset time
- window duration
- plan/account metadata
- forecasted exhaustion time
- OpenTelemetry export
Do not infer subscription usage from local session files, transcripts, token logs, or pricing estimates unless explicitly requested later. This project is about provider live usage signals.
Language Direction
The implementation is Go.
Rationale:
- Simple daemon/CLI story.
- Strong OpenTelemetry support.
- Easy SQLite integration.
- A CGO-free binary is possible with
modernc.org/sqlite.
Layout
cmd/token-burn/ CLI entrypoint
internal/cli/ command wiring
internal/config/ XDG config load and defaults
internal/provider/ provider interface and shared models
internal/provider/codex/ live Codex usage client
internal/provider/claude/ live Claude usage client
internal/provider/copilot/ Copilot quota via the logged-in GitHub CLI
internal/provider/antigravity/ Antigravity quota via existing OAuth state
internal/store/ SQLite schema, migrations, queries
internal/forecast/ burn-rate and exhaustion forecast logic
internal/otel/ OTLP metric exporter
internal/daemon/ poll loop, backoff, graceful shutdown
internal/service/ macOS LaunchAgent and Linux systemd user unit
internal/tui/ read-only dashboard over SQLite
internal/upgrade/ self-upgrade from GitHub ReleasesCode Style
- Keep the provider interface small and shaped around live usage windows.
- Prefer table-driven tests with the standard
testingpackage. - HTTP provider tests should use
httptest.NewServer. - SQLite tests should use
t.TempDir. - Never log raw access tokens, refresh tokens, cookies, or authorization headers.
- Store raw provider JSON only after redacting obvious token/cookie fields.
- Use UTC timestamps in storage; format in local time only in CLI/TUI output.
- Keep the TUI a read-only view over SQLite; it must not poll providers.
Security
- Treat OAuth files and keychain values as secrets.
- Redact secrets in logs and diagnostics.
- Do not export account email as an OTel attribute by default. Use account IDs or configured aliases.
- Poll gently. Default interval should be 60 seconds or slower.
References
See docs/RESEARCH_LINKS.md for public references and endpoint notes.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:46cd31e7 -->Beads Issue Tracker
This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.
Quick Reference
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete workRules
- Use
bdfor ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists - Run
bd primefor detailed command reference and session close protocol - Use
bd rememberfor persistent knowledge — do NOT use MEMORY.md files
Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
Agent Context Profiles
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
- Conservative (default): Use
bdfor task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. - Minimal: Keep tool instruction files as pointers to
bd prime; use the same conservative git policy unless active instructions say otherwise. - Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
Session Completion
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
- File issues for remaining work - Create beads for anything that needs follow-up
- Run quality gates (if code changed) - Tests, linters, builds
- Update issue status - Close finished work, update in-progress items
- Handle git/sync by active profile:
# Conservative/minimal/default: report status and proposed commands; wait for approval. git status # Team-maintainer opt-in only, unless current instructions forbid it: git pull --rebase bd dolt push git push git status - Hand off - Summarize changes, validation, issue status, and any blocked sync/commit/push step
Critical rules:
- Explicit user or orchestrator instructions override this Beads block.
- Do not commit or push without clear authority from the active profile or the current user request.
- If a required sync or push is blocked, stop and report the exact command and error.
<!-- END BEADS INTEGRATION --><!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->Beads Issue Tracker
Use Beads (bd) for durable task tracking in repositories that include it. Use the beads skill at .agents/skills/beads/SKILL.md (project install) or ~/.agents/skills/beads/SKILL.md (global install) for Beads workflow guidance, then use the bd CLI for issue operations.
Quick Reference
bd ready # Find available work
bd show <id> # View issue details
bd update <id> --claim # Claim work
bd close <id> # Complete work
bd prime # Refresh Beads contextRules
- Use
bdfor all task tracking; do not create markdown TODO lists. - Run
bd primewhen Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use/hooksto inspect or toggle them. - Keep persistent project memory in Beads via
bd remember; do not create ad hoc memory files.
Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
<!-- END BEADS CODEX SETUP -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

