Metadata-Version: 2.4
Name: transcripto
Version: 0.1.0
Summary: Search everything your coding agents ever did, grade your own prompts, and price your decisions. Local, stdlib-only, your data never leaves the machine.
Author: Oscar Morke
License: MIT
Project-URL: Homepage, https://github.com/Morkeeth/transcripto
Project-URL: Source, https://github.com/Morkeeth/transcripto
Keywords: claude-code,coding-agents,transcripts,local-first,analytics
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# transcripto

**your coding agents keep a transcript of every session. it is the most valuable
dataset you own, and you cannot scroll back far enough to read it. transcripto
indexes it, keeps only the turns you actually typed, and grades them.**

one command, no account, no signup, no cloud. it reads files that are already on
your disk and never opens a socket.

```
uvx transcripto coach
```

## what you get back

this is a real run on one machine, pasted unedited:

```
  YOUR PROMPT HABITS, GRADED   (offline, your machine only)

  harness: claude
  corpus : 2713 transcript(s), 366,664 records
  kept   : 3605 prompts you actually typed (0.98% of records)
  ranked : 1911 episodes, 890 survived (47%)
  tiers  : commit 356 | write/edit 534 | reverted 2 | nothing durable 1019

  SURVIVAL IS A PROXY: survival = a durable Write/Edit or an un-reverted git commit in-episode. A PROXY, not proof the work was correct or shipped.

  SURVIVES MOST  do more of these:
     65%  (164/253)  detailed (>40 words)
     64%  (66/103)  states-a-check-or-done-condition
     59%  (404/690)  intent:CHANGE
     58%  (21/36)  no-object (pronoun/vague)
     58%  (98/170)  cites-a-file-or-path

  SURVIVES LEAST  these tend to loop:
     33%  (4/12)  intent:REVERT
     39%  (403/1030)  intent:none
     40%  (4/10)  intent:TEST
     41%  (293/709)  terse (<8 words)
     44%  (75/169)  intent:DESCRIBE

  + your best landed prompt, with its witness:
      "mTERMINAL 8 — Mountain of Helicon · ~/CODE/mountain-of-helicon Read ~/CODE/mountain-of-helicon. Two…"
      COMMIT-WITNESSED: git commit  ·  corrections: 0

  - your worst looped prompt, with its witness:
      "ok, and lets see they might solve it in the future so i can go back to my beloeved routine :) Befor…"
      NO-DURABLE-RECORD: read-only Bash only, no file change  ·  corrections: 15  ·  assistant turns: 221
```

those are my numbers. yours will be different, which is the whole point. the last
two lines are the ones that sting: it hands you back your own best and worst
prompt, verbatim, with the receipt for why it scored each one.

on that machine, prompts that wrote down what done looks like survived **64% of
the time (66 of 103)**. prompts with no stated intent survived **39% (403 of
1030)**. i had spent a year blaming the model.

## the proxy caveat, which travels with every number

an episode "survived" if a Write or Edit landed, or a git commit ran and nothing
reverted it inside the same transcript.

that is a durable **keystroke**, not a durable **outcome**. a commit is not proof
the code was right. a revert in a later session is invisible to it. a prompt
whose payoff was a decision rather than an edit reads as dead. it is a coaching
signal, not a verdict. if it ever prints something that flatters you, distrust it.

the caveat is printed in the output itself, every run, on purpose.

## why your own gate matters here

at fleet scale roughly 95% of the `type: user` records in a transcript are not
you. they are tool results, injected skill bodies, sub-agent prompts, and
messages from other terminals, all wearing your role. transcripto gates on
`promptSource` (typed/queued, no meta, no sidechain) so it grades what you typed.

you can watch the gate do work: in the run above, 3605 of 366,664 records
survived it. that is 0.98%.

the same gate is what makes `cost` produce a number a spend tracker cannot:

```
cost per human decision  last 30 days  2026-07-28 → 2026-08-27

  API-equivalent spend      $8,892.49
  your decisions            2934   turns you actually typed (promptSource typed/queued)
  ────────────────────────────────────────────────────
  cost per human decision   $3.03

  46.4k agent messages · 16 per decision · 11.5B tokens · 149 sessions
  57.7k raw `type: user` records in the same window. dividing by those instead
  would read $0.15, 19.7x too cheap.
```

it prints both, so the gate's effect is something you can check rather than
something i am asserting. these are API-equivalent dollars at list rates,
because a transcript has no cost field, only token counts. on a subscription you
did not pay this.

## honest limits

read these before you quote a number at anyone.

- **survival is a proxy**, described above. durable keystroke, not durable outcome.
- **one operator's corpus.** every figure in this README comes from one machine.
  it is an existence proof that the measurement runs, not a finding about how
  people prompt. run it on yours and you get yours.
- **two harnesses today: Claude Code and Codex.** nothing else is supported.
  cursor, aider, and the rest are not read.
- **the habit labels are heuristics.** "states-a-check-or-done-condition" is a
  pattern match over your text, not comprehension. it will misfile some prompts.
- **correlation, not instruction.** detailed prompts surviving more often does not
  prove that padding a prompt causes survival.

## privacy

it runs locally and never touches the network. the entire import list is
`sys, os, json, glob, re, sqlite3, argparse, datetime`. there is no socket, no
urllib, no requests, no subprocess, no telemetry, no analytics, and no account.
you can check that in one grep of the single file it ships as.

your transcripts stay in `~/.claude` and `~/.codex`. the index it builds stays in
`~/.trace`.

## the rest of it

```
transcripto index      build / refresh (incremental)
transcripto watch      live, new sessions get picked up as your agents work
transcripto ask        YOUR OWN messages about a topic, newest first + a rollup
transcripto search     full-text across everything (you + agents + tool logs)
transcripto find       every session that wrote / edited / read a file
transcripto sessions   recent sessions + their opening ask
transcripto stats      what you actually work on
transcripto cost       what ONE of your decisions costs
transcripto coach      which of YOUR prompt habits survive (a proxy)
```

`ask` is the one that kills "wait, did i lose something?". it answers "what was i
thinking about X across ALL my sessions", in your own words only.

```
$ transcripto find USER-JOURNEY.md
2026-08-20  WROTE  ~/CODE/mountain-of-helicon-main/USER-JOURNEY.md
```

the file you lost, found across every session you ever ran, one line.

## Codex

```
transcripto coach --harness codex
```

reads `~/.codex` (sessions + archived_sessions), normalises it into the same rows,
and applies the identical survival proxy. it also ingests `history.jsonl` purely
as a control on the gate: it reports how many of its input lines also show up as
typed rollout turns, so you can see the gate agreeing with a second source.

## install

```
uvx transcripto coach
```

no install, nothing to set up. or put it on your PATH:

```
pipx install transcripto
```

or run the single file with no packaging at all:

```
git clone https://github.com/Morkeeth/transcripto
cd transcripto
python3 transcripto.py coach
```

no dependencies, stdlib only, one file. the packaging adds nothing at runtime, it
just gives the file a name on your PATH. `trace` is a second name for the same
command.

## tests

```
./test_coach.sh    14 assertions
./test_codex.sh    14 assertions
./test_cost.sh     12 assertions
```

offline, no keys, on fixtures that inherit the real transcript shape including
all four ways a non-human record disguises itself as `type: user`.

the load-bearing one in `test_coach.sh` is `REVERTED IS NOT SURVIVED`: a commit
that got `reset --hard` in the same session left no durable record. flip that one
line and the suite goes red, which is the point. a generous proxy is a broken one.

## why though

your agent history is proof. every "yeah it's done" has a real trace sitting
behind it. transcripto is the index that makes it checkable.

it is the fuel layer. on top of it you check what your agents *claim* against what
the trace *shows*, which is [mountain of helicon](https://github.com/Morkeeth/mountain-of-helicon).
the pitch was never "search your history". it is *prove your agent did what it
said, from your own local traces.*

local, MIT, no telemetry. star it if it finds you something you'd lost ™
