vrr/codeburn
2
0
Fork 0
mirror of https://github.com/AgentSeal/codeburn.git synced 2026-05-19 07:43:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: update README for Codex support, provider system, currency command

Browse source
This commit is contained in:
AgentSeal 2026-04-14 08:52:26 -07:00
parent 40d04261d6
commit fb18a79779
1 changed files with 73 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

103
README.md
View file

@ -17,9 +17,9 @@
<img src="https://raw.githubusercontent.com/AgentSeal/codeburn/main/assets/dashboard.jpg" alt="CodeBurn TUI dashboard" width="620" />
</p>
By task type, tool, model, MCP server, and project. Tracks one-shot success rate per activity type so you can see where the AI nails it first try vs. burns tokens on edit/test/fix retries. Interactive TUI dashboard with gradient charts, responsive panels, and keyboard navigation. macOS menu bar widget via SwiftBar. CSV/JSON export.
By task type, tool, model, MCP server, and project. Supports **Claude Code** and **Codex** (OpenAI) with a provider plugin system. Tracks one-shot success rate per activity type so you can see where the AI nails it first try vs. burns tokens on edit/test/fix retries. Interactive TUI dashboard with gradient charts, responsive panels, and keyboard navigation. macOS menu bar widget via SwiftBar. CSV/JSON export.
Works by reading Claude Code session transcripts directly from disk. No wrapper, no proxy, no API keys. Pricing from LiteLLM (auto-cached, all models supported).
Works by reading session transcripts directly from disk. No wrapper, no proxy, no API keys. Pricing from LiteLLM (auto-cached, all models supported).
## Install
@ -36,7 +36,7 @@ npx codeburn
### Requirements
- Node.js 20+
- Claude Code (reads `~/.claude/projects/` session data)
- Claude Code (`~/.claude/projects/`) and/or Codex (`~/.codex/sessions/`)
## Usage
@ -44,14 +44,61 @@ npx codeburn
codeburn # interactive dashboard (default: 7 days)
codeburn today # today's usage
codeburn month # this month's usage
codeburn report -p month # same as above
codeburn report -p 30days # rolling 30-day window
codeburn status # compact one-liner (today + month)
codeburn status --format json
codeburn export # CSV with today, 7 days, 30 days
codeburn export -f json # JSON export
```
Arrow keys switch between Today / 7 Days / Month. Press `q` to quit, `1` `2` `3` as shortcuts.
Arrow keys switch between Today / 7 Days / 30 Days / Month. Press `q` to quit, `1` `2` `3` `4` as shortcuts.
## Providers
CodeBurn auto-detects which AI coding tools you use. If both Claude Code and Codex have session data on disk, press `p` in the dashboard to toggle between them.
```bash
codeburn report # all providers combined (default)
codeburn report --provider claude # Claude Code only
codeburn report --provider codex # Codex only
codeburn today --provider codex # Codex today
codeburn export --provider claude # export Claude data only
```
The `--provider` flag works on all commands: `report`, `today`, `month`, `status`, `export`.
### Supported providers
| Provider | Data location | Status |
|----------|--------------|--------|
| Claude Code | `~/.claude/projects/` | Supported |
| Claude Desktop | `~/Library/Application Support/Claude/local-agent-mode-sessions/` | Supported |
| Codex (OpenAI) | `~/.codex/sessions/` | Supported |
| Pi, OpenCode, Amp | -- | Planned (provider plugin system) |
Codex tool names are normalized to match Claude's conventions (`exec_command` shows as `Bash`, `read_file` as `Read`, etc.) so the activity classifier and tool breakdown work across providers.
### Adding a provider
The provider plugin system makes adding a new provider a single file. Each provider implements session discovery, JSONL parsing, tool normalization, and model display names. See `src/providers/codex.ts` for an example.
## Currency
By default, costs are shown in USD. To display in a different currency:
```bash
codeburn currency GBP # set to British Pounds
codeburn currency AUD # set to Australian Dollars
codeburn currency JPY # set to Japanese Yen
codeburn currency # show current setting
codeburn currency --reset # back to USD
```
Any [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) is supported (162 currencies). Exchange rates are fetched from [Frankfurter](https://www.frankfurter.app/) (European Central Bank data, free, no API key) and cached for 24 hours at `~/.cache/codeburn/`. Config is stored at `~/.config/codeburn/config.json`.
The currency setting applies everywhere: dashboard, status bar, menu bar widget, CSV/JSON exports, and JSON API output.
The menu bar widget includes a currency picker with 17 common currencies. For any currency not listed, use the CLI command above.
## Menu Bar
@ -62,25 +109,7 @@ codeburn install-menubar # install SwiftBar/xbar plugin
codeburn uninstall-menubar # remove it
```
Requires [SwiftBar](https://github.com/swiftbar/SwiftBar) (`brew install --cask swiftbar`). Shows today's cost in the menu bar with a flame icon. Dropdown shows activity breakdown, model costs, and token stats for today, 7 days, and month. Refreshes every 5 minutes.
## Currency
By default, costs are shown in USD. To display in a different currency:
```bash
codeburn config currency GBP # set to British Pounds
codeburn config currency AUD # set to Australian Dollars
codeburn config currency JPY # set to Japanese Yen
codeburn config currency # show current setting
codeburn config currency --reset # back to USD
```
Any [ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) is supported (162 currencies). Exchange rates are fetched from [Frankfurter](https://www.frankfurter.app/) (European Central Bank data, free, no API key) and cached for 24 hours at `~/.cache/codeburn/`. Config is stored at `~/.config/codeburn/config.json`.
The currency setting applies everywhere: dashboard, status bar, menu bar widget, CSV/JSON exports, and JSON API output.
The menu bar widget also includes a currency picker with 16 common currencies. For any currency not listed in the menu bar, use the CLI command above.
Requires [SwiftBar](https://github.com/swiftbar/SwiftBar) (`brew install --cask swiftbar`). Shows today's cost in the menu bar with a flame icon. Dropdown shows activity breakdown, model costs, token stats, per-provider cost breakdown, and a currency picker. Refreshes every 5 minutes.
## What it tracks
@ -102,17 +131,26 @@ The menu bar widget also includes a currency picker with 16 common currencies. F
| Conversation | No tools, pure text exchange |
| General | Skill tool, uncategorized |
**Breakdowns**: daily cost chart, per-project, per-model (Opus/Sonnet/Haiku/GPT-4o/Gemini), per-activity with one-shot rate, core tools, MCP servers.
**Breakdowns**: daily cost chart, per-project, per-model (Opus/Sonnet/Haiku/GPT-5/GPT-4o/Gemini), per-activity with one-shot rate, core tools, shell commands, MCP servers.
**One-shot rate**: For categories that involve code edits, CodeBurn detects edit/test/fix retry cycles (Edit -> Bash -> Edit patterns). The 1-shot column shows the percentage of edit turns that succeeded without retries. Coding at 90% means the AI got it right first try 9 out of 10 times.
**Pricing**: Fetched from [LiteLLM](https://github.com/BerriAI/litellm) model prices (auto-cached 24h at `~/.cache/codeburn/`). Handles input, output, cache write, cache read, and web search costs. Fast mode multiplier for Claude. Fallback to hardcoded prices if fetch fails.
**Pricing**: Fetched from [LiteLLM](https://github.com/BerriAI/litellm) model prices (auto-cached 24h at `~/.cache/codeburn/`). Handles input, output, cache write, cache read, and web search costs. Fast mode multiplier for Claude. Hardcoded fallbacks for all Claude and GPT-5 models to prevent fuzzy matching mispricing.
## How it reads data
Claude Code stores session transcripts as JSONL at `~/.claude/projects/<sanitized-path>/<session-id>.jsonl`. Each assistant entry contains model name, token usage (input, output, cache read, cache write), tool_use blocks, and timestamps.
**Claude Code** stores session transcripts as JSONL at `~/.claude/projects/<sanitized-path>/<session-id>.jsonl`. Each assistant entry contains model name, token usage (input, output, cache read, cache write), tool_use blocks, and timestamps.
CodeBurn reads these files, deduplicates messages by API message ID (prevents double-counting across sessions), filters by date range per entry (not per session), and classifies each turn.
**Codex** stores sessions at `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl` with `token_count` events containing per-call and cumulative token usage, and `function_call` entries for tool tracking.
CodeBurn reads these files, deduplicates messages (by API message ID for Claude, by cumulative token cross-check for Codex), filters by date range per entry, and classifies each turn.
## Environment variables
| Variable | Description |
|----------|-------------|
| `CLAUDE_CONFIG_DIR` | Override Claude Code data directory (default: `~/.claude`) |
| `CODEX_HOME` | Override Codex data directory (default: `~/.codex`) |
## Project structure
@ -120,7 +158,7 @@ CodeBurn reads these files, deduplicates messages by API message ID (prevents do
src/
cli.ts Commander.js entry point
dashboard.tsx Ink TUI (React for terminals)
parser.ts JSONL reader, dedup, date filter
parser.ts JSONL reader, dedup, date filter, provider orchestration
models.ts LiteLLM pricing, cost calculation
classifier.ts 13-category task classifier
types.ts Type definitions
@ -129,6 +167,11 @@ src/
export.ts CSV/JSON multi-period export
config.ts Config file management (~/.config/codeburn/)
currency.ts Currency conversion, exchange rates, Intl formatting
providers/
types.ts Provider interface definitions
index.ts Provider registry
claude.ts Claude Code session discovery
codex.ts Codex session discovery and JSONL parsing
```
## License
@ -137,6 +180,6 @@ MIT
## Credits
Inspired by [ccusage](https://github.com/ryoppippi/ccusage). Pricing data from [LiteLLM](https://github.com/BerriAI/litellm).
Inspired by [ccusage](https://github.com/ryoppippi/ccusage). Pricing data from [LiteLLM](https://github.com/BerriAI/litellm). Exchange rates from [Frankfurter](https://www.frankfurter.app/).
Built by [AgentSeal](https://agentseal.org).