TokenCap builds task-scoped context packs for AI coding agents. Retrieval is good but not perfect, so v3.1 adds a way to tell it when a pack was right or wrong. The constraint we kept throughout: the ledger records only explicit, bounded evidence, and it records it locally.

Recording a judgment

After reviewing a pack, record what happened:

tokencap analyze --learning --outcome helped \ --task "invoice rounding" \ --files src/billing/invoice.js,src/billing/round.js

If the pack left something out:

tokencap analyze --learning --outcome neutral \ --task "invoice rounding" \ --missing src/billing/currency.js

The CLI confirms what it did and what it did not do:

Recorded explicit focus-feedback (helped). Local only; no automatic behavior changed.

--outcome accepts helped, neutral or hurt. Anything else is rejected.

What a record contains

Each event in .tokencap/learning/ledger.json has an ID, a timestamp, a kind, a source (cli or companion), an outcome, a task label, and two file lists: selected and missing. That is the full schema.

The bounds are enforced in src/learning/ledger.js:

  • Task labels are capped at 300 characters, with newlines and tabs collapsed.
  • Each file list keeps at most 30 entries, deduplicated.
  • Only workspace-relative paths are accepted. Absolute paths, drive letters, UNC paths, ~ paths, URL schemes and anything containing .. are dropped.

Redacting the task label

A task label is free text, so it can contain things that should not be stored. Two passes run before it is written:

  1. Paths are scrubbed. A path inside the workspace is rewritten as workspace-relative. A path outside it becomes [path]. POSIX paths are only matched under system roots such as /Users or /home, so an API route like /users/:id stays readable.
  2. The label goes through TokenCap's central redaction engine, the same one that redacts packs.

If redaction throws, the label is dropped rather than stored unredacted.

What it never does

There is no transcript capture. The ledger does not accept chat history and does not infer outcomes from what an agent did. There is no telemetry; the file stays on disk and nothing reads it over the network. And there are no automatic changes. Recording feedback does not edit rules, the Constitution, or default ranking.

The ledger is also not shared. Team rules in .tokencap/team/ are meant to be committed. The learning ledger stays ignored with the rest of .tokencap/, so one developer's judgments do not end up in everyone's history.

Reading it back 

tokencap analyze --learning

This prints a count of helpful, neutral and harmful focus events, rule feedback events, and the ten most recent records with their files. Add --json to get the full report, which states local: true and automaticChanges: false in the output itself.

The companion signal

The Chrome companion can mark a file Useful or Missed for the current task. It sends that to the local loopback bridge's /feedback endpoint, which writes the same kind of event with source: "companion". The bridge only accepts feedback for a project that has been indexed, named by absolute path.

Where the evidence is used

The ledger is input for two opt-in features: tokencap ask "<task>" --adaptive, which can re-rank candidates using matching feedback, and tokencap analyze --patterns, which reports file pairs that keep appearing together. Both are covered in the next post. Neither runs unless you ask for it.

Docs: tokencap.vansharora.app