Waybill

Bring receipts. Waybill is token accounting for AI-assisted work — a Claude Code plugin that meters every token, attributes it to the Jira story it shipped, and turns the receipts into value reports, performance-review packets, and token-budget requests that survive scrutiny.

A waybill is the shipping document that itemizes cargo and its charges. You ship; Waybill keeps the itemized record.

<!-- TODO: 60–90s demo GIF here — init → bootstrap receipt → the token pitch rendered as a receipt. -->

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.

Sixty seconds to your first receipt

claude plugin marketplace add Jakeintech/waybill
claude plugin install waybill@waybill

Then in a Claude Code session, say "initialize my waybill ledger". That's the whole setup: no accounts, no tokens, no OAuth. Waybill seeds your identity from git config, imports Anthropic list-price rates so costs appear from day one, checks your transcript-retention setting, and renders a bootstrap receipt from your local git history alone — your shipped work, itemized, in under a minute.

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. /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	log records your without-Claude estimate first (pre-registration), sealed with a SHA-256 escrow hash
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 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

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 = Σ observed, per session) you can re-run offline with waybill verify, 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.

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 ROADMAP.md.

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 spreadsheet brag doc	Org admin dashboards	Waybill
Captured when it happens	✗	✓	✓
Tied to PRs/issues/deploys	✗	partial	✓
Honest counterfactuals	✗	✗	✓ (pre-registered, ranged)
Works bottom-up, for you	✓	✗	✓
Data you own locally	✓	✗	✓

Docs

• Tutorial: this README's quickstart, above.
• How-to: swap Jira/GitHub for Linear, GitLab, Bitbucket…
• Reference: ledger entry & config schema · skill reference · test plan — the docs Claude reads are the docs you read.
• Explanation: 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).

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 only network calls are the MCP calls you authorize, scoped to your own items.

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 receipt. Adapter configs for other trackers are the most-wanted contribution. Please read the Code of Conduct; security reports go through SECURITY.md.

License

MIT