Skip to content

docs(readme): four-surface hero grid with install shortcuts #715

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
iamtoruk merged 2 commits into from
Jul 17, 2026
+43 −26
Merged

docs(readme): four-surface hero grid with install shortcuts #715

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cef7795
docs(readme): four-surface hero grid with per-surface install shortcuts
iamtoruk Jul 17, 2026
d3a9d64
docs(readme): star and sponsor ask up top, consistency pass
iamtoruk Jul 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 43 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,40 @@
<a href="https://github.com/sponsors/iamtoruk"><img src="https://img.shields.io/badge/sponsor-♥-F97316?logo=github" alt="Sponsor" /></a>
</p>

<p align="center">If CodeBurn shows you something your bill never did, <a href="https://github.com/getagentseal/codeburn/stargazers">star the repo</a> so other developers find it, and consider <a href="https://github.com/sponsors/iamtoruk">sponsoring</a> to keep 36 integrations honest.</p>

<table align="center">
<tr>
<td align="center" width="50%">
<strong>Desktop</strong><br/>
<img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/desktop.jpg" alt="CodeBurn Desktop" /><br/>
<a href="https://github.com/getagentseal/codeburn/releases/download/desktop-v0.9.15/CodeBurn-0.9.15-arm64.dmg"><img src="https://img.shields.io/badge/macOS-Apple_Silicon-F97316?logo=apple&logoColor=white" alt="Download for macOS (Apple Silicon)" /></a>
<a href="https://github.com/getagentseal/codeburn/releases/download/desktop-v0.9.15/CodeBurn-0.9.15.dmg"><img src="https://img.shields.io/badge/macOS-Intel-F97316?logo=apple&logoColor=white" alt="Download for macOS (Intel)" /></a>
<a href="https://github.com/getagentseal/codeburn/releases/download/desktop-v0.9.15/CodeBurn-0.9.15.AppImage"><img src="https://img.shields.io/badge/Linux-AppImage-F97316?logo=linux&logoColor=white" alt="Download for Linux" /></a>
<a href="https://github.com/getagentseal/codeburn/releases/download/desktop-v0.9.15/CodeBurn-Setup-0.9.15.exe"><img src="https://img.shields.io/badge/Windows-Setup-F97316?logoColor=white" alt="Download for Windows" /></a>
</td>
<td align="center" width="50%">
<strong>Web</strong><br/>
<img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/web.jpg" alt="CodeBurn Web dashboard" /><br/>
<code>npx codeburn web</code>
</td>
</tr>
<tr>
<td align="center" width="50%">
<strong>Terminal</strong><br/>
<img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/dashboard.jpg" alt="CodeBurn TUI dashboard" /><br/>
<code>npx codeburn</code>
</td>
<td align="center" width="50%">
<strong>macOS Menubar</strong><br/>
<img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/menubar-app.jpg" alt="CodeBurn macOS menubar" /><br/>
<code>codeburn menubar</code>
</td>
</tr>
</table>

<p align="center"><em>Four surfaces, one source of truth: everything reads the session files already on your disk.</em></p>

**CodeBurn is a free, open-source, local-first tool that tracks AI coding token usage and cost across 36 tools and agents (Claude Code, Cursor, Codex, Gemini, Grok and more), broken down by model, project, and task.**

You pay for Claude, Codex, Cursor, and a stack of other AI tools. The bill tells you the total. It never tells you that half of it went to conversation instead of code, or that an expensive model burned your budget on work a cheaper one would have one-shot.
Expand All @@ -26,11 +60,6 @@ CodeBurn does. It reads the session files your tools already write to disk and b

Everything runs locally. No wrapper, no proxy, no API keys, nothing leaves your machine. Pricing comes from [LiteLLM](https://github.com/BerriAI/litellm), refreshed daily.

<p align="center">
<img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/dashboard.jpg" alt="CodeBurn TUI dashboard" width="760" />
</p>
<p align="center"><em>A week across every tool you use, in one screen.</em></p>

<p align="center">
<a href="#quick-start">Quick start</a> ·
<a href="#find-and-fix-waste">Find waste</a> ·
Expand Down Expand Up @@ -61,7 +90,7 @@ That opens the interactive dashboard (last 7 days by default). Arrow keys switch
npm install -g codeburn
```

Also runs via `bunx codeburn` or `dx codeburn`, or `brew install codeburn` on macOS.
Also runs via `bunx codeburn` or `pnpm dlx codeburn`, or `brew install codeburn` on macOS.

**Menu bar app** for macOS, with your spend always in the menu bar:

Expand Down Expand Up @@ -128,10 +157,6 @@ codeburn optimize --format json # setup health + findings as JSON
- Possibly low-worth expensive sessions with no edit turns or repeated retries
when no `git`/`gh` delivery command is observed

<p align="center">
<img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/optimize.jpg" alt="CodeBurn optimize" width="760" />
</p>

Each finding shows the estimated token and dollar savings plus a ready-to-paste fix: a `CLAUDE.md` line, an environment variable, or a `mv` command to archive unused items. Findings are ranked by urgency (impact weighted against observed waste) and rolled up into an A to F setup health grade. Repeat runs classify each finding as new, improving, or resolved against a 48-hour recent window.

You can also open it inline from the dashboard: press `o` when a finding count appears in the status bar, `b` to return.
Expand Down Expand Up @@ -180,10 +205,6 @@ codeburn compare --provider claude # Claude Code sessions only

Which model is actually better for *your* work? Press `c` in the dashboard, or run `codeburn compare`. Arrow keys switch periods, `b` to return.

<p align="center">
<img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/compare.jpg" alt="CodeBurn compare" width="760" />
</p>

| Section | Metric | What it measures |
|---------|--------|-----------------|
| Performance | One-shot rate | Edits that succeed without retries |
Expand Down Expand Up @@ -215,7 +236,7 @@ Did the spend actually ship? `codeburn yield` correlates AI sessions with git co
| Abandoned | No commits near session, or commits never merged |
| Ambiguous | Session ran parallel to another and its window's commits were attributed to the tighter one |

Attribution is timestamp-window based (heuristic): each commit is credited to at most one session — the tightest window containing it. The JSON report carries `methodology: "timestamp-window"`.
Attribution is timestamp-window based (heuristic): each commit is credited to at most one session, the tightest window containing it. The JSON report carries `methodology: "timestamp-window"`.

Requires a git repository. Run from your project directory.

Expand Down Expand Up @@ -254,11 +275,7 @@ Pairing is PIN-authorized and stays on your local network. You can also discover
codeburn menubar
```

One command: downloads the latest `.app`, installs into `~/Applications`, and launches it. Re-run with `--force` to reinstall. Native Swift and SwiftUI app lives in `mac/` (see `mac/README.md` for build details).

<p align="center">
<img src="https://raw.githubusercontent.com/getagentseal/codeburn/main/assets/menubar-0.9.11.png" alt="CodeBurn macOS menubar" width="440" />
</p>
One command: downloads the latest `.app`, installs into `~/Applications`, and launches it. Re-run with `--force` to reinstall. The native Swift and SwiftUI app lives in `mac/` (see `mac/README.md` for build details).

The menubar icon shows the spend period selected in Settings (Today by default; Week, Month, and 6 Months are also available). Non-today periods add a short suffix such as `$42 / mo` so the menu bar value stays clear. Click to open a popover with agent tabs, period switcher (Today, 7 Days, 30 Days, Month, All), Trend, Forecast, Pulse, Stats, and Plan insights, activity and model breakdowns, optimize findings, and CSV/JSON export. Refreshes every 30 seconds.

Expand Down Expand Up @@ -403,7 +420,7 @@ Run `codeburn` for the dashboard, or use a subcommand below. Most commands also
| `codeburn sync logout` | Revoke token and remove credentials |
| `codeburn sync reset --confirm` | Clear sent-ledger (re-send all data on next push) |

Sync sends token counts, costs, models, and projects — never prompts or code. This feature is in preview; the protocol may change between releases. See [docs/sync/](docs/sync/) for details.
Sync sends token counts, costs, models, and projects, never prompts or code. This feature is in preview; the protocol may change between releases. See [docs/sync/](docs/sync/) for details.

**Web & devices**

Expand Down Expand Up @@ -447,7 +464,7 @@ Sync sends token counts, costs, models, and projects — never prompts or code.
|---------|--------------|
| `codeburn models` | Per-model token + cost table (last 30 days) |
| `codeburn models --by-task` | Break each model into per-task-type rows |
| `codeburn models --by-agent` | Break each model into per-agent rows (which agent drove which model's spend); Claude subagent transcripts only, other providers and main sessions bucket under `(main)`. The default `--min-cost 0.01` hides sub-cent agent buckets; use `--min-cost 0` for a complete inventory. |
| `codeburn models --by-agent` | Break each model into per-agent rows: which agent drove which model's spend (`(main)` covers non-agent sessions; `--min-cost 0` shows sub-cent agents) |
| `codeburn models --top 10` | Only the 10 most expensive models |
| `codeburn models --format markdown` | Emit a paste-friendly markdown table |
| `codeburn models --task feature` | Filter to feature-development work |
Expand Down Expand Up @@ -611,7 +628,7 @@ CodeBurn surfaces the data; you read the story. A few patterns worth knowing:
| Cache hit < 80% | System prompt or context is not stable, or caching is not enabled |
| Lots of `Read` calls per session | Agent re-reading same files, missing context |
| Low 1-shot rate (Coding 30%) | Agent struggling with edits, retry loops |
| Opus 4.6 dominating cost on small turns | Overpowered model for simple tasks |
| Opus 4.8 dominating cost on small turns | Overpowered model for simple tasks |
| `dispatch_agent` / `task` heavy | Sub-agent fan-out, expected or excessive |
| No MCP usage shown | Either you don't use MCP servers, or your config is broken |
| Bash dominated by `git status`, `ls` | Agent exploring instead of executing |
Expand Down Expand Up @@ -685,7 +702,7 @@ CodeBurn deduplicates messages (by API message ID for Claude, by cumulative toke

CodeBurn is free, runs entirely on your machine, and exists to cut your AI bill. If it has already saved you more than a sponsorship costs, consider sending a little of that back.

Keeping 30 integrations accurate is constant work. The tools underneath change every week: Cursor reshapes its database, Claude moves a config path, new models ship at new prices. Sponsorship keeps CodeBurn current with all of it, so the numbers you see are always the real ones.
Keeping 36 integrations accurate is constant work. The tools underneath change every week: Cursor reshapes its database, Claude moves a config path, new models ship at new prices. Sponsorship keeps CodeBurn current with all of it, so the numbers you see are always the real ones.

Where your sponsorship goes:

Expand All @@ -699,10 +716,10 @@ Sponsoring as a team or company? Your logo lands right here, in front of every d
<a href="https://github.com/sponsors/iamtoruk"><img src="https://img.shields.io/badge/Sponsor_CodeBurn-♥-F97316?style=for-the-badge&logo=github&labelColor=1a1a1a" alt="Sponsor CodeBurn" /></a>
</p>


## License

MIT
MIT.

CodeBurn is an AgentSeal open-source project and is not affiliated with CodeBurn Bt. or codeburn.hu.

## Credits
Expand Down
Binary file added assets/desktop.jpg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/menubar-app.jpg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/web.jpg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.