aakashdhar Vibe Ledger
Generates a visual cost report from your project's cost history.
Reads vibe/cost/history.json. Writes vibe/cost/ledger/index.html. Opens in browser.
No dependencies. No installs. Works on Mac, Linux, and Windows.
When this runs
Automatically — vibe-cost calls this at the end of every session after writing history.json.
Manually — when the user says:
ledger:— regenerate and openshow cost report/open ledger/generate ledgerhow much have I spent— if history.json exists
Step 1 — Check history.json exists
ls vibe/cost/history.json 2>/dev/null && echo "EXISTS" || echo "MISSING"
If missing:
"No cost history found yet. Run
cost:after your next session to start tracking, thenledger:to generate the report."
Stop here if missing.
Step 2 — Run the generator
# Resolve the generator across install layouts (flat install or plugin marketplace)
GEN=$(ls ~/.claude/skills/vibe-ledger/scripts/generate.py \
~/.claude/plugins/marketplaces/*/skills/vibe-ledger/scripts/generate.py 2>/dev/null | head -1)
python3 "$GEN"
The script:
- Finds
vibe/cost/history.jsonfrom the current project directory - Computes all metrics — totals, averages by task size, day breakdowns, efficiency ratios
- Generates
vibe/cost/ledger/index.html— self-contained, no external dependencies - Opens it in the default browser automatically
- Prints a summary to the terminal
Step 3 — Confirm to user
After the script runs, tell the user:
"Ledger generated — opening in your browser.
[Project name] · [N] sessions · [N] tasks · $[X.XX] total Report:
vibe/cost/ledger/index.htmlRun
ledger:any time to refresh it with the latest data."
What the report shows
Header — project name, total cost, session count, date range, build progress
Stat cards — avg cost per task, avg cost by size (S/M/L), peak session, cache savings
At a glance — plain English summary: what was built, what it cost, whether costs are healthy
Day by day — cost per day with ASCII block bars
Task size breakdown — S/M/L cost totals with percentage of total spend
Session burn table — each session with dot indicators (each dot ≈ cost/7), colour-coded:
- Green = on track
- Red = peak session
- Amber = output-heavy (CP-03)
- Blue = review session
Token composition — reading vs writing cost in plain terms ("reading costs $X of your $Y")
Efficiency metrics — tokens per task, read-to-write ratio, code written per dollar
Top 5 most expensive tasks — with size, phase, input and output tokens
Advice cards — plain English explanations of waste patterns detected, with specific fixes
Forecast — remaining cost estimate based on avg task cost × tasks remaining
Output files
vibe/cost/
├── history.json ← source data (written by cost:)
└── ledger/
└── index.html ← generated report (open this)
index.html is a single self-contained file (all data + CSS + JS inlined) — share
it by just sending the file. It renders fully offline; the only network use is the
optional VT323/Share Tech Mono web font, which gracefully falls back to the system
monospace if there's no connection (the layout and numbers are unaffected).
Updating the report
Every cost: session automatically regenerates the ledger.
Or run ledger: manually any time to refresh from the current history.json.
The report always reflects the complete project history — not just the last session.
Troubleshooting
"vibe/cost/history.json not found"
→ You haven't run cost: yet in this project. Run it after your next session.
"history.json is empty"
→ The file exists but has no sessions. Run cost: at the end of a session to populate it.
"python3: command not found"
→ Python is not installed. Install from python.org — it's free and takes 2 minutes.
On most Macs and Linux machines, python3 is already available.
Report opens but looks wrong
→ Try opening vibe/cost/ledger/index.html directly in Chrome or Firefox.
The VT323 font requires an internet connection to load from Google Fonts.
If offline, it falls back to Share Tech Mono or monospace — same layout, different font.