Vibe ledger

Skill aakashdhar/vibe-skill/vibe-ledger

vibe-* is a collection of Claude Code CLI skills. Each skill is a structured instruction set that tells Claude Code exactly what to do at a specific moment in a project — how to plan it, build it, review it, test it, deploy it, and hand it off.

Install

npx -y skills add aakashdhar/vibe-skill --skill vibe-ledger

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Generates a full project cost report as a self-contained HTML file from vibe/cost/history.json. Opens automatically in the browser. Tracks spend per session, per task, per phase, and per day. Shows task size breakdown (S/M/L avg costs), session burn with dot indicators, token composition, efficiency metrics, waste pattern advice, and project cost forecast. All plain English — readable by non-technical stakeholders. Triggered automatically at the end of every cost: session. Also triggers on "ledger:", "generate ledger", "show cost report", "open ledger", "cost report", "how much have I spent", "show me the report". Requires vibe/cost/history.json to exist — run cost: first if it doesn't. Zero dependencies — uses Python stdlib only, works on any machine.

SKILL.md

4.7 KB, as published. Nobody here has run it

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 open
show cost report / open ledger / generate ledger
how 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, then ledger: to generate the report."

Stop here if missing.

Step 2 — Run the generator

python3 ~/.claude/skills/vibe-ledger/scripts/generate.py

The script:

Finds vibe/cost/history.json from 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.html

Run 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 fully self-contained — no internet required to view it. Share it with a client or team member by just sending the file.

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.