Documentation

Code provenance

Point at a line of code. Tokenome works out when it was last changed, then brings back the conversations from exactly that change.

The command

tokenome context src/ledger.py 31

In the app, the Code context page does the same with a file picker and a line number.

OptionWhat it does
--window NMinutes of conversation to consider around the edit. The default is 30.
--symmetricLook on both sides of the edit, not only before it.

How it works

  1. It blames the line with git blame to learn who last committed it and when. If the file is not reachable now, it falls back to the blame captured when the conversation was indexed.
  2. It takes that timestamp and finds the conversations from just before the edit, because those are the discussions most likely to have driven it.
  3. It prints the committer, the time, the commit, and the conversations, each one openable in full.

What a good result looks like

Tokenome code context: line 31 of ledger.py blamed to the change called Go back to direct account lookups, with the conversations from just before that edit listed underneath.
Line 31 blamed to the change called "Go back to direct account lookups", with the conversation that caused the reversal directly under it. The project and its conversations are sample data; the software is not.

The useful case is not the line that was written once and never touched. It is the line that used to be something else. The commit message says what changed. The conversation under it says that a stale account misroutes money and the latency win was not worth it, which is the part nobody writes down.

A good result has three things: a blame that points at a real commit, at least one conversation inside the window, and a reason in that conversation that reads like a decision rather than a status update. When you get all three, you have the answer.

What it cannot do

  • It needs a git repository and a committed line. A line you have not committed blames to your working copy and has no timestamp to search around.
  • It needs the conversation to be indexed. Work done in a tool Tokenome does not read, or before you installed it, is not there. Drop in an export and it will be.
  • It finds conversations near the edit in time, not a proof of cause. Two things discussed in the same half hour both come back. You read them and decide; the tool does not assert that one caused the other.
  • It does not summarize. You get the turns themselves, with their exact wording, because the detail that matters is usually a specific number, id or model name that a summary would drop.
  • A line nobody discussed returns nothing. That is the honest answer, and it is worth having: it tells you the decision was never actually made in writing.

Widen --window, or add --symmetric, when the edit landed some time after the conversation that drove it.