TokenLedger 0.8.3

Released 2026-11-02. Fixes how the tracker journal grows and how it is saved,
and records the Paseo 0.14 review.

Compatibility

Requires Paseo >=0.11.0 on both the daemon and app, as in v0.8.2. Verified
on Paseo 0.14.0. Existing ledger.jsonl records and pricing.json files are
kept and are not rewritten. On the first start, the tracker journal is split
into tracker-state.json and tracker-retired.json. If you go back to v0.8.2,
it ignores tracker-retired.json, and agents in that file restart from their
last ledger record.

Changes

• Smaller tracker checkpoints. tracker-state.json was rewritten in full up
  to four times a second and kept every agent ever seen, so its writes grew
  without limit. One user measured 440 GB in 3 days. Archived, closed, and
  removed agents now move with their full state to tracker-retired.json,
  which changes only when an agent retires or returns. Cost baselines stay
  exact. Thanks to @tmikaeld.
• No empty journal on early stop. When the plugin stopped before tracking
  started, such as a reload with no session, turn, or overview request since
  load, it overwrote the journal with an empty one. This erased every agent's
  cost baseline and any recovered records that were not yet in the ledger.
  The journal is now saved only after it has been read.
• Billions of tokens. Token counts of one billion or more show a B suffix
  instead of thousands of millions. Thanks to @tmikaeld.

Paseo 0.14

Paseo 0.13 and 0.14 do not change the APIs that TokenLedger uses. Paseo 0.14
releases idle agent runtimes after one hour and resumes the session on the next
prompt. In Claude turns recorded after the upgrade, the reported session cost
continued across these gaps, and no turn lost its cost. See the
compatibility notes.

TokenLedger 0.8.2

Released 2026-10-28. Adds a shortcut to the plugin settings and moves npm
publishing to GitHub Actions.

Compatibility

Requires Paseo >=0.11.0 on both the daemon and app, as in v0.8.1. Existing
ledger.jsonl records and pricing.json files are kept and are not rewritten.

Changes

• Settings shortcut. The overview has a gear button, and the command center
  has an Open TokenLedger Settings command. Both open the plugin settings
  page, which is otherwise several levels deep.
• Published from CI. The npm package is published by the release workflow
  with npm Trusted Publishing, so it carries provenance. No npm token is stored.

v0.8.1 — custom price overrides and provider extends

TokenLedger v0.8.1

Released 2026-10-23. Fixes costs for local or unbilled models that run on the
Claude Code or Codex harness through a custom provider (#1).

Compatibility

Requires Paseo >=0.11.0 on both the daemon and app, as in v0.8.0. Existing
ledger.jsonl records and pricing.json files are kept and are not rewritten.

Changes

• Custom prices override reported costs. A new setting, off by default. When
  a pricing.json price matches a turn, it replaces the runtime-reported cost.
  A runtime can report a list-price fallback for a model that it does not know.
  Add providers to a price entry to limit it to one provider. OpenRouter and
  built-in prices never replace a reported cost. The reported value stays in
  the ledger file, so turning the setting off restores it.
• Provider extends. A custom provider that declares extends: "claude" or
  extends: "codex" in the daemon config now follows its base harness. Its
  turns get per-turn usage and prices instead of unknown-scope snapshots. New
  records store the resolved harness. Earlier records of such providers stay
  unknown-scope snapshots.

Example

{
  "version": 1,
  "currency": "USD",
  "prices": [
    { "providers": ["local-claude"], "model": "acme/local-1", "tiers": [{ "input": 0, "cacheRead": 0, "cacheWrite": 0, "output": 0 }] }
  ]
}

Then turn on Settings → Plugins → token-ledger → TokenLedger → Custom prices
override reported costs.

v0.8.0 — Paseo 0.12 background workspaces and accounting accuracy

TokenLedger v0.8.0

Released 2026-10-23. Tracks agents in Paseo 0.12 background workspaces and
makes token and cost accounting more accurate and more explicit about what is
unknown.

Compatibility

Requires Paseo >=0.11.0 on both the daemon and app, without an upper version
limit. The verified hosts are 0.11.1 and 0.12.0. SDK development
dependencies stay pinned to 0.11.1; CI checks 0.11.0, 0.11.1, 0.12.0, and the
latest SDK. See the compatibility notes.

Existing ledger.jsonl records are reinterpreted on read and are not
rewritten. Existing pricing.json files are kept. After updating, reload or
reopen the app so the client uses the new summary fields.

Changes

• Paseo 0.12 background workspaces. Paseo 0.12 hides background workspaces
  from default agent and workspace lists. Before this release, turns in those
  workspaces were closed as canceled with no usage. TokenLedger now requests
  background workspaces, falls back on older hosts, and confirms a removal by
  agent ID before it settles an open turn.
• Overview ranges. Switching ranges stays on the same screen and no longer
  adds a navigation entry per click. Thanks to @ChtJT (#4).
• Usage scope. Per-turn usage is kept apart from OMP session/branch totals
  and unknown-scope snapshots. Snapshots stay visible but are not added to turn
  or date-range sums.
• Unknown is not zero. Missing counts, cache rates, and costs show as
  unknown. A cache hit rate shows only with a complete prompt denominator. The
  panel, pill, sidebar, and overview mark incomplete usage and partial
  estimates.
• Pricing. No private price seeds or fixed currency conversion are built
  in; new price files start empty. Prices match full model IDs and explicit
  aliases. Ambiguous or formerly unsafe matches block reference fallback and
  show a pricing.json warning.

Known gaps

Paseo 0.12.0 still omits cache-write counts and provider-internal subagent
usage. See usage API requirements.

v0.7.0 — Paseo 0.11 screens and sidebar

TokenLedger v0.7.0

Released 2026-10-09. Adopts the Paseo 0.11 screen and sidebar APIs and fixes
Git installs on Paseo 0.11. Token accounting, stored records, and custom prices
are unchanged.

Compatibility

Requires Paseo >=0.11.0 on both the daemon and app, without an upper version
limit. Paseo 0.9.1-0.10.x users should stay on v0.6.3. The verified host is
0.11.1; the 0.11.0 plugin SDK is identical to 0.11.1. SDK development
dependencies are pinned to 0.11.1. See the compatibility notes.

Changes

• Overview screen. The overview is a Paseo 0.11 screen with Today, Last 7
  days, Last 30 days, and All time ranges. The range is a screen param, so the
  link and the header title follow it. A range lists agents with turns that
  ended in it and agents with a turn in flight. Day ranges start at local
  midnight on the device that shows them.
• Sidebar footer row. A TokenLedger row in the sidebar footer shows today's
  cost (or tokens when no price is known), with an activity icon while a turn
  runs. It replaces the sidebar header link and opens the overview on Today.
• Git install fix. On Paseo 0.11, github: and git: installs of v0.6.3
  failed with Could not resolve type dependency "@getpaseo/client". Shipped
  code now derives Paseo client types from the host SDK, so @getpaseo/client
  and @getpaseo/protocol are development dependencies only.
• Registry listing. The manifest declares the display name, a PNG icon, and
  screenshots, and the package ships OVERVIEW.md for the
  registry page.

Install or update

Update the daemon and app to Paseo 0.11.0 or later first. Then, for an existing
npm installation:

paseo plugin update token-ledger

For an existing GitHub installation:

paseo plugin update token-ledger --ref v0.7.0

For a new installation:

paseo plugin install npm:paseo-token-ledger
# or
paseo plugin add github:stv1024/token-ledger --ref v0.7.0

Registry installations (paseo plugin add stv1024/token-ledger) receive v0.7.0
after the registry maintainers review it. Run paseo plugin ls; TokenLedger
should be running. Reopen the desktop app if a window still shows the old
sidebar link. No ledger migration or deletion is needed.

Validation

• Typecheck and all 65 automated tests passed against the 0.11.0 and 0.11.1 SDKs.
• A copy without node_modules, installed as a directory, compiled both bundles
  and reached "Plugin ready".
• Reloaded on the installed Paseo 0.11.1 daemon without errors. A real Claude
  turn and a real Codex turn each produced one completed record; the Codex
  record kept two request observations.
• The registry's own manifest and overview checks accept the new metadata.
• The maintainer completed manual testing of the sidebar row and overview
  ranges before authorizing release.

Paseo 0.11.1 still omits cache-write counts and Codex provider-internal child
usage from the public accounting API. This release does not recover that data.

Full diff

TokenLedger v0.6.3 — Paseo 0.10.2 compatibility

TokenLedger v0.6.3

Released 2026-09-30. Restores loading on Paseo 0.10.2 by removing the manifest's
<0.10.0 ceiling. The existing tracking implementation remains compatible;
token accounting, stored records, and custom prices are unchanged.

Compatibility policy

Requires Paseo >=0.9.1 on both the daemon and app, without an upper version
limit. A new Paseo version no longer disables TokenLedger solely because of
its version number. SDK dependencies remain pinned to 0.9.1.

Verified hosts are 0.9.1 and 0.10.2. Allowing later versions does not certify
untested releases; future restrictions will be based on confirmed incompatibilities.
CI now checks the minimum SDK, 0.10.2, and npm latest, including weekly runs.
See the compatibility policy and evidence.

Install or update

For an existing npm installation:

paseo plugin update token-ledger

For an existing GitHub installation:

paseo plugin update token-ledger --ref v0.6.3

For a new installation:

paseo plugin install npm:paseo-token-ledger
# or
paseo plugin add stv1024/token-ledger --ref v0.6.3

Run paseo plugin ls; TokenLedger should be running. No ledger migration or
deletion is needed. Local development installations use
paseo plugin reload token-ledger.

Validation

• Typecheck and all 65 automated tests passed against the 0.9.1 and 0.10.2 SDKs.
• Reloaded successfully on the installed Paseo 0.10.2 daemon; client and server
  bundles compiled and the plugin started without new errors.
• Real Claude turns retained the session-cost baseline across a plugin reload.
  A Codex turn retained and summed two request observations into one record.
• The maintainer completed manual testing before authorizing release.

Paseo 0.10.2 still omits cache-write counts and Codex provider-internal child
usage from the public accounting API. This release does not recover that data.

Full diff

TokenLedger v0.6.2 — fix npm install

Fixes installing from npm: paseo plugin install npm:paseo-token-ledger failed with Could not resolve type dependency "@getpaseo/client".

Paseo resolves type-only imports when it installs a plugin, and npm installs skip devDependencies. @getpaseo/client and @getpaseo/protocol are now dependencies. They are only imported for types, so nothing extra is bundled. Plugin behavior is the same as v0.6.0/v0.6.1. Requires Paseo 0.9.1–0.9.x.

paseo plugin install npm:paseo-token-ledger
# or
paseo plugin add stv1024/token-ledger --ref v0.6.2

Full diff: v0.6.1...v0.6.2

TokenLedger v0.6.1 — now on npm and paseo.cafe

TokenLedger v0.6.1

Released 2026-09-29. Distribution release: TokenLedger is now on npm as paseo-token-ledger and listed on paseo.cafe. Plugin behavior is unchanged from v0.6.0.

Compatibility and install

Requires Paseo 0.9.1–0.9.x on both the daemon and the app. Use v0.5.1 with Paseo 0.8.

paseo plugin install npm:paseo-token-ledger

Or from GitHub:

paseo plugin add stv1024/token-ledger --ref v0.6.1

Existing GitHub installations keep working and can keep updating from Git. To switch to npm, run paseo plugin remove token-ledger and then the npm install; the ledger in ~/.paseo/plugins/token-ledger/ is kept.

Changes

• npm package with plugin sources only (no tests), plus description, license, repository, and keywords metadata.
• README screenshots moved to images/; new Install and Limitations sections.
• 20-second promo video and its Remotion source in promo/.

Full diff: v0.6.0...v0.6.1

TokenLedger v0.6.0 — Paseo 0.9.1 compatibility and recovery

TokenLedger v0.6.0

Released 2026-09-23. This release adapts TokenLedger to Paseo 0.9.1, restores tracking after subscription failures, and adds native settings for summaries, reference prices, and refresh frequency.

Compatibility and upgrade

Both the Paseo daemon and app must be 0.9.1–0.9.x (>=0.9.1 <0.10.0). Use TokenLedger v0.5.1 with Paseo 0.8, or v0.3.1 with Paseo 0.7.

For a new installation:

paseo plugin add stv1024/token-ledger --ref v0.6.0

For an existing GitHub installation, update Paseo first, then run:

paseo plugin update token-ledger --check
paseo plugin update token-ledger --ref v0.6.0
paseo plugin ls

TokenLedger should be running. Local development installations use paseo plugin reload token-ledger. Reopen the desktop app if an existing window still holds the previous UI bundle.

Existing ledger records, checkpoints, and pricing.json overrides remain compatible; no data migration or deletion is required. Install/update selectors do not pin future updates: without --ref, Git updates follow the remote's default branch.

Changes

• Paseo 0.9.1 subscriptions: use host-assigned subscription handles, reconcile complete paginated catalogs after reconnect, retain live updates received during pagination, and await handle release during cleanup.
• Recovery and accounting: retry timeline subscription failures with bounded delays. Persist delivery gaps through reloads, display affected turns with gap, and use unknown when the terminal outcome was missed. Keep cumulative costs spanning an unobserved interval as raw data instead of assigning the entire amount to one turn.
• Native settings: open Settings → Plugins → token-ledger → TokenLedger to control Timeline summaries, OpenRouter reference prices, built-in fallback prices, and refresh frequency. The switches default to on; normal polling uses 3 seconds active / 30 seconds idle, and relaxed polling uses 10 / 60 seconds. Preferences apply to the selected host without reloading the plugin.
• Live cost estimates: show the current turn's estimated cost in the panel and include it in the composer pill's running total. Estimates retain the ≈ mark.
• Reference prices: refresh verified standard Claude rates, including Opus 5.5, against Anthropic's pricing table dated 2026-09-23. Match explicit model versions so unknown versions and Fast/Batch suffixes do not inherit an unverified built-in price. Reported costs and custom overrides keep priority.
• Optional cache-write accounting: carry supplied write counts through aggregation, persistence, RPCs, and UI, with an independent cacheWrite rate and OpenRouter write-price ingestion. Separate known cache counts from inclusive input, use complete prompt sizes for pricing tiers, and avoid normalizing live input twice.

Known data and validation limits

Paseo 0.9.1 still omits cache-write counts and provider-internal descendant usage from its public plugin usage API. Optional cache-write support does not recover those missing streams or reconstruct historical counts. Codex observations remain partial because identical requests cannot always be distinguished from replayed snapshots. Recovery marks missing data and does not backfill historical Timeline summaries.

Validation on Node 24 and Paseo 0.9.1 includes TypeScript checking, all 65 automated tests, plugin reload/startup, real Claude and Codex turns, preservation of Claude session-cost deltas across reload, catalog pagination beyond 200 entries, unchanged-record RPC responses, and native-settings read/write/validation/conflict behavior. Test agents were archived and settings were restored after verification.

Desktop and mobile visual checks were not completed because native UI automation was unavailable. These checks do not establish visual behavior of the settings page or Timeline renderer on either platform.

See the README, changelog, and upstream usage API requirements.

Full diff: v0.5.1...v0.6.0

Promo video

20-second overview (token-ledger-promo.mp4 below). Source: promo/.

TokenLedger v0.5.1

iOS plugin loading fix

• Fix iOS plugin activation by replacing the client-side PanelPlacement class with a closure factory, avoiding Hermes-incompatible class syntax in the dynamically loaded bundle.
• Use the Paseo plugin-hosted ScrollView in the panel and overview for compatible scrolling within mobile sheets.

Install or update with:

paseo plugin add stv1024/token-ledger --ref v0.5.1