Metadata-Version: 2.4
Name: myburn
Version: 0.2.0
Summary: Your Claude Code dashboard — track burn, YOLO mode, score cards. 100% local.
Project-URL: Homepage, https://myburn.cc
Project-URL: Repository, https://github.com/Gekko-dot-ETH/myburn
Author: MyBurn Contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,claude-code,dashboard,tokens,usage
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.20.0
Description-Content-Type: text/markdown

# MyBurn 🔥

**Your Claude Code Dashboard** — track your burn, tokens, YOLO mode, and flex your score cards. 100% local, zero telemetry, open source.

![MyBurn dashboard](https://raw.githubusercontent.com/Gekko-dot-ETH/myburn/master/myburn/static/dashboard-preview.png)

> **Status: Beta.** Core features are stable; APIs and CLI may shift before 1.0. Backup your `~/.myburn/data/usage.db`.

## Install

**macOS** — via [Homebrew](https://brew.sh):

```bash
brew install Gekko-dot-ETH/myburn/myburn
```

**Linux, Windows, or macOS without Homebrew** — via `pipx` (recommended) or `pip`:

```bash
pipx install myburn   # recommended (PEP 668-safe, isolated)
# or
pip install myburn    # works, but PEP 668 systems will warn
```

> **Don't have `pipx`?**
> - macOS: `brew install pipx && pipx ensurepath`
> - Debian / Ubuntu: `sudo apt install pipx && pipx ensurepath` (Debian < 12 / Ubuntu < 23.04: `python3 -m pip install --user pipx` instead)
> - Fedora / Arch: `sudo dnf install pipx` / `sudo pacman -S python-pipx`
> - Windows: `python -m pip install --user pipx` then `python -m pipx ensurepath`

We recommend `pipx` because it handles its own venv bootstrap; plain `pip install` on Debian/Ubuntu often fails with `ensurepip` errors unless you install `python3-venv` first.

Then run it:

```bash
myburn
```

Your browser opens at [localhost:7734/dashboard](http://localhost:7734/dashboard) with all your stats. That's it.

## Requirements

- **Python 3.9+** (3.10+ recommended)
- **Claude Code installed and used at least once.** MyBurn reads your session logs from `~/.claude/projects/`. If you've never opened a Claude Code session, the dashboard will show a welcome screen instead of charts.
- A modern browser (Chrome, Firefox, Safari, Edge — current versions).

## Supported platforms

| OS | Status |
|---|---|
| Linux | ✅ Tested |
| macOS | 🟡 Expected to work — not yet verified |
| Windows (WSL2) | ✅ Works as Linux |
| Windows (native) | 🟡 Experimental (tracked in issues) |

## Features

- **Burn Tracking** — real-time cost tracking with daily, monthly, and per-project breakdowns
- **Score Cards** — share your stats in style (Clean, Epic, Roast, Trading Card, Wrapped, more)
- **YOLO Stats** — track how much of your burn happens with bypass permissions
- **Live VU Meter** — 32-segment LED bar with 3-second polling
- **Hourly Patterns** — see when you code most
- **Session Details** — per-session cost, duration, and tool breakdown
- **Project Breakdown** — which projects burn the most

## How it works

1. **Install** — `pipx install myburn`, one command.
2. **Reads your local logs** — parses `~/.claude/projects/` JSONL files into a local SQLite DB.
3. **Dashboard opens** — your browser opens at `localhost:7734` with all your stats.

Nothing leaves your machine — ever. No accounts, no telemetry, no cloud calls.

## CLI options

```
myburn                    # Start dashboard, open browser
myburn --port 8080        # Custom port
myburn --no-browser       # Don't auto-open browser
myburn --host 0.0.0.0     # Bind to all interfaces (LAN/Tailscale access)
myburn --version          # Show version

myburn backup [--out PATH]   # Snapshot the DB
myburn restore <path>        # Restore from a snapshot
```

## Data directory

By default, MyBurn stores its SQLite database in `~/.myburn/data/`. Override with:

```bash
MYBURN_DATA_DIR=/path/to/data myburn
```

If your Claude Code logs live in a non-standard location:

```bash
MYBURN_CLAUDE_DIR=/path/to/.claude/projects myburn
```

## Your data, your responsibility

Claude Code purges JSONL session logs from `~/.claude/projects/` after roughly 30 days. **MyBurn's SQLite database is the only permanent copy of your usage history** after that — once a JSONL file is gone, only your DB remembers what was in it.

This means: **back it up.**

MyBurn keeps an automatic rolling snapshot in `~/.myburn/backups/` (every 6h while the dashboard is running, last 7 always kept + everything from the last 30 days). You can also trigger one anytime:

```bash
myburn backup                    # writes ~/.myburn/backups/usage_YYYYMMDD_HHMMSS.db
myburn backup --out ~/dropbox/   # custom destination
myburn backup --compress         # gzip the result
```

To restore:

```bash
myburn restore ~/.myburn/backups/usage_20260501_120000.db
```

The current DB is auto-saved to `usage.db.pre-restore-TIMESTAMP` before being replaced, so a wrong restore is reversible.

Disable the periodic snapshot with `MYBURN_BACKUP_DISABLE=1`. Override location with `MYBURN_BACKUP_DIR`. Frequency with `MYBURN_BACKUP_INTERVAL_HOURS`.

## Troubleshooting

**The dashboard shows "Welcome — no Claude Code logs detected".**
You either don't have Claude Code installed, or it's been installed but never run. Open a Claude Code session and refresh.

**Port 7734 is already in use.**
```bash
myburn --port 17734
```

**My logs live in a non-default location.**
```bash
MYBURN_CLAUDE_DIR=/where/your/logs/are myburn
```

**The "Live VU Meter" looks frozen.**
Refresh the page. If it persists, check `localhost:7734/api/health` — `live_entries` should be > 0 and `sync_alive` should be true.

**Costs look wrong / banner says "approximate pricing".**
A model name was emitted by Claude Code that isn't in the PRICING table yet (typically right after Anthropic releases a new model). MyBurn falls back to default rates and shows a banner. [File an issue](https://github.com/Gekko-dot-ETH/myburn/issues/new) so we can update.

**More problems?**
Run `curl localhost:7734/api/health` and include the JSON in your bug report. It tells us your DB state, sync state, and which models you're using.

## Running from source

```bash
git clone https://github.com/Gekko-dot-ETH/myburn.git
cd myburn
pip install -e .
myburn
```

Tests:

```bash
python3 -m pytest tests/ -q
```

## Privacy

MyBurn extracts only aggregate metrics from your Claude Code logs:

- Token counts and model names
- Timestamps and session durations
- Cost calculations (API-equivalent pricing)
- Tool usage counts
- Permission mode (YOLO detection)

It **never** reads, logs, or transmits your code, prompts, file paths, or any conversation content. The dashboard front-end loads Chart.js, html2canvas, and Inter/JetBrains Mono fonts; the JS libs ship bundled in the wheel, fonts come from Google Fonts (a single GET to `fonts.googleapis.com` per page load — disable with browser policy if you need fully offline).

## Reporting bugs / contributing

- 🐛 [Open an issue](https://github.com/Gekko-dot-ETH/myburn/issues)
- 🛠️ [Read CONTRIBUTING.md](CONTRIBUTING.md)
- 💬 PRs welcome — keep them small and tested.

## Acknowledgements

MyBurn originally used [ccusage](https://github.com/anthropics/ccusage) as an external CLI tool for log parsing. It has since been fully replaced by a native Python parser — no ccusage code was used or forked.

## License

MIT
