transcript-drift
Skill67 starsChanged 40 days agoMITView on GitHub
Check whether Claude Code's transcript format has moved ahead of what ClaudeLens reads, and turn what the check finds into triage or an issue. Use when asked to look for format drift, to see what the app is missing from transcripts, after a Claude Code upgrade, or when a session renders wrong and the format is suspected.
In this repository9 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- src/CLAUDE.mdCLAUDE.md
- arch-analysisSkill
- build-dmgSkill
- github-issueSkill
- github-prSkill
- new-claude-modelSkill
- run-appSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 84
Real model turns, real tokens: Never run it as part of a check.
- Very specific: line 90
Every drift finding on a _shape_ axis gets one verdict in scripts/transcript-manifest.mjs, then npm run census:accept to re-baseline.
- Distinctive: line 113
Write what a real specimen would need to look like to settle it — that is the note's job.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Is the transcript format ahead of us?
ClaudeLens reads Claude Code's ~/.claude/projects/**/*.jsonl, and Claude Code
keeps adding to what it writes there. Nothing announces it. A new row type, a
new attachment subtype, a new content block simply doesn't appear in the app —
#245 and #246 both sat unnoticed for months.
Stages 1 and 2 answer two different questions and do not overlap — run both. Stage 3 costs tokens and is only for a question the first two left open.
1. What we don't read
npm run censusStreams the whole corpus (~1s) and diffs the shapes it finds against the
decisions in scripts/transcript-manifest.mjs. Exit 1 means drift. Read the
report in five parts:
- Drift — a shape with no manifest entry, absent from the baseline. This is the finding. Claude Code writes it and nobody has looked at it.
- New fields — the same drift line counts these separately, as in
0 unknown shapes, 11 new fields. A key-path on a row we read or intend to read that the baseline has never seen. Read the warning below before re-baselining. - Known gaps — triaged
candidate: decided, not yet read. A standing backlog, not news. Don't report these as new. - Looked at, not decided — triaged
unknown: open questions someone already examined. Also not news, but each one names what would settle it, so this is where to look when you have a new specimen in hand. - In the manifest, absent from this corpus — either dropped upstream, or
never exercised here. Stage 3 tells the two apart. Suppressed under
--root, where a narrowed corpus makes it list most of the manifest and mean nothing.
The field axis is report-once. Shapes are diffed against the manifest, so an un-triaged shape returns every run until someone decides about it. Fields are diffed against the baseline only — there is no table they must appear in — so
npm run census:acceptmakes a field finding disappear permanently, whether or not you understood it. That is deliberate: a hand table of every field would be a second copy of the format and wrong within a week. But it means the sequence matters. Look at the fields, write aFIELDSentry for any that carry something (that is what keeps them in the backlog where you can see them), and only then accept. Accepting first destroys the evidence.
2. What we read wrong
npm run census:replayThe census only sees the file. A field can be present, recognised, and still
dropped — which is what #245/#246 were. This test runs the real reader:
fixtures pin which content blocks survive parseContentArray, and a corpus
sweep fails on any dropped block the manifest hasn't triaged.
The sweep is opt-in (that script sets CLAUDELENS_DRIFT_CORPUS=1) and npm
test skips it: it reads the whole corpus, so its outcome depends on state the
test did not create, and left unconditional it reddens npm test on an
unrelated branch because this machine's transcripts happen to contain
something new. The fixtures in the same file are unconditional — they are the
regression gate.
A census with no drift and a red test here is the more serious result: it means we mishandle something we already know about.
3. Only if a shape is missing from the corpus
node scripts/transcript-exercise.mjs --list
node scripts/transcript-exercise.mjs --yes --only <keys> --censusThe corpus covers the features this user happens to use. A feature nobody
exercised writes no rows, so the census can't distinguish "Claude Code doesn't
do this" from "we never tried". This drives claude -p against prompts chosen
to provoke specific shapes, in a throwaway dir the census skips by name.
Real model turns, real tokens. Never run it as part of a check. Reach for it only when stage 1 or 2 left a specific question a generated transcript would settle, and say which scenarios you want to run and why before running them.
Triage
Every drift finding on a shape axis gets one verdict in
scripts/transcript-manifest.mjs, then npm run census:accept to re-baseline.
(Fields are the exception — FIELDS is the one table allowed to be incomplete;
see the report-once warning above.) The verdict is the deliverable: an un-triaged
shape comes back identically next run, and a tool that repeats itself gets
ignored.
read('<module>')— a module consumes it. Only after it actually does.ignored('<reason>')— deliberately not read. Harness bookkeeping, prompt scaffolding, anything carrying nothing a transcript view would show. The reason is the point: it's what stops the next person re-litigating it.candidate('<what it would give us>')— not read, and it should be. Say what the app could do with it, not just what the field is.unknown('<what you saw; what would settle it>')— looked at, and the rows didn't say enough.
Use unknown rather than guessing. Sometimes the only evidence is a shape's
name and one row with an opaque payload — a single occurrence, a bare {type,
uuid}, a field whose value tells you nothing. That is not ignored: every
ignored entry in the manifest names what the thing is, and none of them says
"it had no fields". It isn't candidate either, which claims the app could use
it. unknown records that someone looked, which stops it being re-reported as
fresh drift, and keeps it in its own report section as the open question it is.
Write what a real specimen would need to look like to settle it — that is the
note's job.
One thing no verdict expresses well: a shape read for one purpose and not
another. agent-meta is read by teams-reader, but only for the
in_process_teammate case — 1 of the 35 sidecars on disk — and by nothing for
the other 34. It is filed as candidate with that stated in the note, because a
single verdict per shape can't say it. If you hit the same thing, put it in the
note rather than picking the least-wrong verdict silently.
Which table the entry goes in follows the axis the report named: a row type in
ROW_TYPES, an attachment.type in ATTACHMENT_TYPES, a content block in
CONTENT_BLOCKS, a system.subtype in SYSTEM_SUBTYPES, a field in FIELDS
keyed by the dotted path exactly as printed.
To decide, read the actual rows before guessing:
grep -h '"<the-type>"' ~/.claude/projects/*/*.jsonl | head -3 | python3 -m json.toolJudgement calls worth stating plainly: volume is not importance —
total_tokens_reminder is 10k+ rows of nothing, continued-in is 6 rows and a
missing edge between sessions. And a dropped content block is never
ignored: parseContentArray discarding a block loses user-visible content,
and if the block is a message's only content the whole turn vanishes.
Reporting
Say which of the three stages produced the finding, and give the count — "57
image blocks across the corpus, each a turn the transcript renders as nothing"
lands; "unhandled content block" doesn't. Distinguish the backlog from new
drift; the user knows about the backlog.
For anything worth filing, use the github-issue skill — it carries this repo's
house rules. Don't fix and file in the same pass unless asked: triage is cheap
and reversible, a reader change needs a test alongside it.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

