Waybill

Bring receipts. Token accounting for AI-assisted work, as a Claude Code plugin.

Sixty seconds to your first receipt

claude plugin marketplace add Jakeintech/waybill
claude plugin install waybill@waybill
        ↳ restart Claude Code (hooks load at startup), then say:
          "initialize my waybill ledger"

No accounts, no tokens, no OAuth — and the first receipt renders in under a minute. Real output: this repository's own development, metered by the engine (waybill on waybill — the session that built 2.1.0):

WAYBILL · BOOTSTRAP RECEIPT
────────────────────────────────────────
WINDOW    2026-05-25 → 2026-08-23 (90 days)
IDENTITY  info@jakeawilliams.com

REPO      Jakeintech/waybill
ITEMS
  COMMITS                  43
  MERGES                    0
  ACTIVE DAYS               3
  FIRST → LAST    2026-08-16 → 2026-08-23
  TRACKER KEYS    WB-05 ×1

SUBTOTAL  43 commit(s) across 1 repo(s)
TOKENS    1 metered session(s)
  INPUT                       608
  OUTPUT                  255,071
  CACHE READ          102,428,828
  CACHE WRITE             604,563
  unattributed        103,289,070
────────────────────────────────────────
EVIDENCE TIER: FACTS (LOCAL GIT LOG · METERED TRANSCRIPTS)
RANGES NOT MIDPOINTS · NOTHING PADDED · UNATTRIBUTED SHOWN

Look at the shape of that spend before the claims: 99.2% of this session's tokens were cache reads (query cache on the same ledger) — billed at a tenth of the input rate, invisible in a "tokens used" headline. Receipts change what you even think to ask. And the unattributed line is the point: nothing is hidden, and the attribution ladder plus one-tap pins move spend onto the stories it served as you work.

The claim, in one clause: Waybill deterministically attributes AI coding-agent token spend to the work item that shipped — metered from local transcripts and git history, never estimated. Vendor dashboards stop at per-user/per-day; engineering-intelligence platforms spread daily spend across tickets proportionally. Waybill's numbers are receipts, not estimates (the field, dated and labeled).

Ask "why is my bill like this" and the cache skill answers from the same receipts: volume by cache tier, the cache-read share, and the effective-vs-list cost delta — derived, labeled, never estimated.

A waybill is the shipping document that itemizes cargo and its charges. You ship; Waybill keeps the itemized record: value reports, performance-review packets, standups, invoices, disclosure registers, and token-budget requests that survive scrutiny.

Why

Two conversations decide a lot of an engineer's year, and both run on the same broken input:

• "What was the AI budget worth?" — more teams allocate Claude tokens by demonstrated value. Use them well, show it, get more.
• "What did you accomplish this cycle?" — performance reviews, promo packets, sprint reviews.

Humans answer both from memory, the night before, in adjectives. The person deciding can't tell honest claims from inflated ones, so they discount everything. Waybill fixes the evidence, not the persuasion: it records work as it happens, ties every claim to an artifact — a PR, an issue, a deploy tag, a transcript — and refuses to let you make the kind of claim that gets your next pitch ignored.

What init actually does

Waybill seeds your identity from git config, imports Anthropic list-price rates so costs appear from day one (dated model ids resolve to their family rate, and waybill status names any model it can't price rather than showing a quietly partial total), checks your transcript-retention setting, meters your existing Claude Code transcripts — subagent transcripts included — and renders the bootstrap receipt above from your own git history and metered sessions.

Updating

Claude Code doesn't push plugin-update notifications; updating is one command whenever you like:

claude plugin update waybill@waybill

Then restart Claude Code. waybill status (or waybill --version) shows the engine version you're running. Waybill never checks for updates on its own — no network calls without you asking is a commitment, not an oversight. Releases and changelogs live on the releases page; watch the repo (Watch → Custom → Releases) if you want GitHub to email you.

The upgrade path (optional, five minutes)

Connecting your tracker and git host turns commits into receipts with story points, epics, and merge timestamps:

# Easiest — reuse your authenticated gh CLI:
export GITHUB_MCP_PAT="$(gh auth token)"
# Or mint a fine-grained read-only PAT (repos/PRs) at
# https://github.com/settings/personal-access-tokens and export it instead.

1. For Jira, either of:
   • acli (preferred — scoped fields, small payloads): install it, then acli jira auth login --web. Syncs fetch through it automatically.
   • Atlassian MCP: /mcp → complete the OAuth flow for atlassian (no token needed).
2. Say "sync my ledger and give me a bootstrap report."

Not sure what is or is not connected? waybill status says, and prints the exact command to fix anything missing.

That imports your last ~90 days of your own issues and merged PRs and produces a facts-only report — shipped items, points, PRs, deploys — before you've changed a single habit. From then on, opening tasks through the ledger unlocks the stronger claims (see tiers below).

How it works

Moment	What happens
You start a task	Tell log — it asks for your without-Claude estimate first, as a range, and seals it at write time (SHA-256 escrow; edits are detectable ever after). Decline and the item is simply logged facts-only — estimates are the tier-3 upgrade, never a toll
You work	A SessionEnd hook queues the session and a detached, dependency-free miner meters real token usage from the transcript — no model calls, no network, never blocking
Things merge	sync reconciles the ledger against your Jira issues and GitHub PRs (or Linear, GitLab, or plain local git)
You wonder where it went	spend answers by story/epic/model/week, files the attribution inbox one tap at a time, and tracks budget pacing — one line at 80%/100%, never nagging
You wonder what the bill is even made of	cache breaks it down by cache tier: the cache-read share, effective vs list cost (derived, labeled), write premiums netted out — "why is my bill like this", answered with receipts
It's 9:58 and standup is at 10	standup turns the ledger into "what I did yesterday" bullets — shipped, in progress, started — every line traceable to a receipt; --days 7 makes it a weekly digest
Work shipped without a ticket	salvage clusters the untracked spend with its receipts (sessions, branches, PRs), proposes what each group plainly was, and turns your one-tap confirmations into reconstructed entries — facts tier, never forged estimates
You just want to look	waybill dashboard writes a self-contained local page (spend, pacing, cache savings, open work, last 7 days) and opens it in your browser; the miner keeps it fresh — reading your own numbers costs zero tokens
The sprint ends	retro runs the honest look back: estimates vs. actuals (over-range items named, not hidden), tokens-per-point by model, waste, rework, and what sat on the truck
You need to make a case	report builds a one-page, receipt-linked pitch; forecast sizes your next token ask from your own metered tokens-per-story-point
They should not have to trust you	waybill export --pack ships the verification pack: the verbatim events behind the numbers plus the engine itself, so the recipient re-runs the integrity checks offline — node waybill.mjs verify --home .
A client, a policy, or finance asks	invoice renders shipped work as billing paperwork (recorded hours, disclosed AI costs); disclose answers "was AI used here?" per item from the meter — recorded role, sessions, tokens, conservation-checked

Every Claude Code token is metered deterministically from your local transcripts and attributed to the story it served, with a per-event resolver name and confidence, a conservation check (Σ attributed = Σ metered, per session) you can re-run offline with waybill verify — an internal-consistency guarantee on the meter's own output: it catches a dropped or edited event; it cannot detect undercounting at the source — plus an attribution inbox for the ambiguous leftovers and per-story waste diagnostics (what the tokens bought — and what they wasted on retry loops). As of 1.0 the schema is frozen: the receipts are the contract.

Evidence tiers (the whole idea)

Every number in a report states where it came from:

1. Facts — merge timestamps, deploy tags, story points, token counts.
2. Baseline deltas — your own pre-Claude velocity/cycle time vs. now.
3. Pre-registered estimates — logged before the work, reported as ranges.
4. Retrospective judgment — kept in the ledger, excluded from pitches by default.

Plus structural honesty: append-only storage (corrections supersede, never overwrite), ranges never collapse to midpoints, value counts only when merged or deployed, and costs (tokens spent, rework) appear in every pitch. Full rules: methodology.

Report presets

• token-pitch — the ask, the receipts, the spend ledger, the efficiency trend, the forecast.
• perf-review — epic-level outcomes for a review period, including review/incident/docs work.
• sprint-recap / quarterly — the running record.
• grant-report — what the sponsorship shipped, for maintainers and their funders.
• incident — the receipts pack over an incident timeframe: timeline facts, no efficiency math.
• Beyond reports: the career ledger (externally-redacted full export that follows you between jobs — see the ledger skill's exit section) and the invoice/disclose skills above.

Reports render at three audience levels — self, internal, external — with deterministic pseudonymization before anything leaves the org.

What Waybill will never do

• No manager mode, no surveillance. It queries only your assigned issues and your authored PRs.
• No peer ranking. The methodology refuses individual colleague comparisons by design — you compete with your own baseline, not with Dave.
• No hosted service, no telemetry. Everything lives in ~/.waybill/ (a local git repo you own).
• No time tracking. It records outcomes and estimates, not keystrokes.

These are commitments, not gaps. See the roadmap.

Pausing, quieting, leaving

Trust in a tool that logs your work includes knowing exactly how to stop it. The full exit path, from turning it down to walking away:

• Pause metering (client engagement, shared machine, debugging): set "metering": { "enabled": false } in ~/.waybill/config.json. Nothing is captured or metered while paused — waybill status reports metering: PAUSED so the state is never silent. Existing data is untouched; flip it back to resume.
• Turn down the talking: "notices": { "level": "minimal" } keeps only budget-threshold lines ("off" silences everything Waybill says unprompted — metering still runs). The renewal reminder (budgets.renewal_reminder_days, default 14) obeys the same switch.
• Take your data: waybill export --format json (or csv) emits the spend ledger; the entire ledger is already plain JSONL in ~/.waybill/ — a local git repo you own. Copy it anywhere; nothing is proprietary.
• Uninstall the tool, keep the data: claude plugin uninstall waybill@waybill, then restart Claude Code. Hooks and skills go away; ~/.waybill/ stays yours.
• Delete everything: rm -rf ~/.waybill (or $WAYBILL_HOME if you set one). That is the whole footprint — Waybill keeps no other state. Session transcripts under ~/.claude/ belong to Claude Code, not Waybill, and are governed by its cleanupPeriodDays setting.

Compared to the alternatives

	Memory / a brag doc	Vendor usage dashboards	Engineering-intelligence platforms	Waybill
Captured when it happens	✗	✓	✓	✓
Tied to PRs/issues/deploys	✗	✗ (per-user/per-day)	✓ (allocated)	✓ (metered)
Spend-to-work numbers are…	recollections	totals only	proportional estimates	receipts
Honest counterfactuals	✗	✗	✗	✓ (pre-registered, ranged)
Recipient can re-verify offline	✗	✗	✗	✓ (export --pack)
Works bottom-up, for you	✓	✗	✗	✓
Data you own locally	✓	✗	✗	✓

Categories, not names, on purpose — the named, dated field survey lives in docs/positioning.md, labeled in Waybill's own evidence tiers.

Docs

• Tutorial: this README's quickstart, above.
• How-to: swap Jira/GitHub for Linear, GitLab, Bitbucket, Azure DevOps… · one ledger on several machines · Windows · the OTel fallback
• Reference: ledger entry & config schema · skill reference · test plan — the docs Claude reads are the docs you read.
• Explanation: architecture & system design — how the pieces compose, the trust model, and the recorded 1.5.0 review · value-measurement methodology · roadmap & scope · brand & voice · schema freeze & migration policy
• Spec: full product specification — the normative design the shipped engine implements.

FAQ

Does it work without Jira or GitHub? Yes — that's the default. Git-only mode needs zero configuration and zero auth: metering, attribution by branch/pin, and the bootstrap receipt all run from local data. Connecting a tracker/git host upgrades the receipts; any of them with an MCP server can be swapped in (adapters).

Why isn't waybill on my PATH? The plugin never touches your PATH — inside Claude Code, skills invoke the bundled engine via "${CLAUDE_PLUGIN_ROOT}/bin/waybill", and that is the supported surface. To poke at the CLI directly, run the dependency-free bundle from a clone of this repo (Node 20+, no install):

git clone https://github.com/Jakeintech/waybill && cd waybill
node bin/waybill.mjs status

It reads the same ~/.waybill/ ledger your plugin writes.

Can I use this for performance reviews if my company doesn't ration tokens? Yes — that's the perf-review preset. The token pitch is one output of the ledger, not the point of it.

Is my data private? Local JSONL under your home directory. The engine itself makes no network calls; syncs go through the CLIs (acli, gh) or MCP servers you authorize, scoped to your own items, and init/status may invoke your locally authenticated gh/acli to read who you are — nothing of yours is ever sent anywhere you didn't point it.

Why won't it compare me to teammates? Story points aren't comparable across people, scraping colleagues reads as surveillance, and your own trajectory is stronger evidence anyway. (methodology §6)

How do I justify AI spend to my manager? Run sync, then "build my token pitch". Bring the one-pager; keep the ledger for the follow-up questions.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md, the roadmap, and issues labeled good first issue (GitHub special-cases that exact label for new contributors; the pun lives in the issue bodies). Adapter configs for other trackers are the most-wanted contribution. Please read the Code of Conduct; security reports go through SECURITY.md.

License

MIT