Running agents
Mining your own transcripts
Every pattern on this site, each a write-up of one habit from my work with AI coding agents, comes out of one loop. I read back the transcripts, the saved logs, of my own sessions with coding agents, find what keeps recurring, write it up, and turn it into rules my agents follow. Then I read the next transcripts to see if the rules held. It is a retrospective, run over the written record instead of memory.
One of 15 patterns I've found working with AI coding agents. An agent drafted the words from my notes, and I haven't edited them yet. See all 15, or read how they are made.
An agent drafted the words from my notes, and I haven't edited them yet. The code was run before it went in.
The problem
After months of working with coding agents, models that write and change code by themselves, I had made the same correction many times without noticing. Each time it felt like a one-off. A retrospective, the meeting where a team looks back at what went well and what did not, would have caught some of it. But a retrospective works from memory, and memory keeps the incident that hurt most, not the small one that keeps coming back.
The whole record does exist. Each session leaves a transcript holding every message, command and result. There is far too much of it to read by hand, and it is full of client names, file paths and the odd secret, so it can't be published as it is.
Asking a model to read it all and tell you your patterns gets you an answer quickly. In my experience some of that answer is not in the transcripts at all.
The idea
I think of it as personal digital archaeology: dig through your own record, keep only what you can show is there, and label what you find. It runs in four steps, and the fourth feeds the first.
- Mine. A reader, usually a model, goes through a sample of sessions with a brief that says what to look for: what I corrected, what failed twice, what was settled. Every note quotes one line from one session, and says whether the reader opened that line itself (checked) or is going on something else (relayed). Habits are counted across sessions and across projects. I set the bar, a minimum count such as three sessions or two projects, and decide what clears it. Each habit it notes is a candidate until it clears the bar.
- Distil. A habit that clears the bar becomes a sketch: the situation, what goes wrong with the obvious approach, what I settled on, and its limits. The evidence sits in a separate appendix that stays private. The sketch is then rewritten with no project, client, product or person names, given a worked example cut down from the real prompt or script I use, and checked before it is published.
- Encode. The pattern becomes something my agents load: a rule, a check, or a skill, a short set of instructions an agent reads before a task. My private copy of the skill stays thin: it points at the published steps, the ones at the foot of this page, and adds only my own choices.
- Repeat. On the next pass, each encoded habit is looked for in sessions dated after its rule. If it is still there, the rule did not hold, and the rule gets revised.
The raw notes live in one folder outside every repository, so a note with a real name in it is not sitting where a commit could pick it up. Most habits noted there stay below the bar and stay in the folder, which is how it should be.
A version small enough to read
My miner is not a program. It is a scheduled agent that follows two plain files of instructions, cut down here with the names taken out. The first is what it reads every night.
# The nightly miner: standing instructions
You are a scheduled run with no memory of earlier nights. Everything you needis in this folder. You work alone: do not start sub-agents or other sessions.One piece of work at a time, so the machine stays usable.
## Why this exists
The owner writes up patterns that recur across the software they build withcoding agents. A private catalogue lists candidates. Each night you turn upto two lines of the queue into notes for them to read. You never publish,and you never draft the write-up itself.
## Each night
1. Read `QUEUE.md`. Take the first two unticked lines. If none are left, write the morning note saying the queue is empty, and stop.2. For a `source` line: read that source and follow `miner.md` for it.3. For a `candidate` line: write one sketch of that candidate in the format the line names. Do the two lines one after the other, never at once.4. Tick each finished line (`- [x]`), and add the date.5. Write the morning note: what you wrote, as full file paths, and anything that stopped you.6. Stop. Do not start a third line.
## Hard limits
- Read only in every project. No edits, no commits, no installs, no tests.- Write only inside this folder. It sits outside every repository on purpose: notes may name projects and people here and nowhere else.- Nothing leaves this machine. No web requests, no tickets, no messages.- If a tool asks for a permission you do not have, do not look for another way round. Say so in the morning note and stop.The second is the brief for mining one source: what to look for, the form each candidate takes, and the rule that names go only under the evidence.
# Brief: mine one source for candidate patterns
Read every transcript in `transcripts/`. Each is one session between aperson and a coding agent. Look for habits: what the person corrected, whatwent wrong twice, what was settled and then held.
Write each habit you find to `candidates.md`, in this form:
## <a working title, in plain words>
**Pressure.** What keeps causing the problem, in one or two sentences.**Mechanism.** What the person settled on instead.**Evidence.** One list item for each line that shows it, written as`- <file> (<project>): "<the line, quoted character for character>", checked`or the same ending in `relayed`. Checked means you opened the file andfound the line yourself just now; relayed means you are going on somethingelse. Never pass a relayed line off as checked. Use no dashes aspunctuation.**Recurrence.** How many sessions and how many projects it appears in.
Rules:
- The pressure and the mechanism name no project, product, company or person. Names, files and quotes go only under Evidence, which stays in this private folder.- A habit seen once is still written down; mark it "once". The owner decides what clears the bar, not you.- Write nowhere except `candidates.md`. Change nothing else.The source here is six short made-up sessions from three projects. One of them reads:
project: docsdate: 2026-10-18
agent: All green, ready to merge.person: Green where? Show me the command and its result.agent: I added the slow test to the skip list for now.person: Don't add to the skip list. Fix the test.A short script copies the brief and the sessions into a separate folder, outside every repository, and runs the agent there through the command line of Claude Code, Anthropic's coding agent. It may read anything in the folder and write one file, and nothing else.
// One night of the miner over a folder of transcripts: a scheduled agent, read-only,// writing only into its own private folder, following a brief. Nothing here judges; the agent does.// Run: bun mine.ts. Needs the claude CLI, logged in. Costs well under a dollar.import { cpSync, existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";
// The private folder: the brief and the transcripts, outside every repository.const folder = mkdtempSync(join(tmpdir(), "inbox-"));for (const f of ["miner.md", "transcripts"]) cpSync(join(import.meta.dir, f), join(folder, f), { recursive: true });
// It may read anything in the folder and write one file. No shell, no web, no sub-agents.Bun.spawnSync(["claude", "-p", "--model", process.env.MINE_MODEL ?? "claude-sonnet-5-5", "--safe-mode", "--setting-sources", "", "--no-session-persistence", "--allowed-tools", "Read,Glob,Grep,Write", "--disallowed-tools", "Bash,WebFetch,WebSearch,Agent,Task", "--max-turns", "30", "--output-format", "json"], { cwd: folder, stdin: new TextEncoder().encode("Follow miner.md.") });
const out = join(folder, "candidates.md");console.log(existsSync(out) ? readFileSync(out, "utf8").trim() : "The miner wrote no candidates.md. Nothing is known about this night.");rmSync(folder, { recursive: true, force: true });Run with Bun, a JavaScript runtime, one real run wrote:
## Show the command and its result with any claim of success
**Pressure.** The agent reports work as done, passing or fixed in a single phrase, with nothing the person can check. The person has to ask for the proof every time.**Mechanism.** A claim of success comes with the exact command that was run and what it returned. A bare "done" or "green" is not accepted.**Evidence.**- transcripts/s1.txt (shop): "person: Which tests? Show me the command and its result.", checked- transcripts/s4.txt (docs): "person: Green where? Show me the command and its result.", checked- transcripts/s5.txt (docs): "person: How do you know? Show me the command and its result.", checked**Recurrence.** 3 sessions, 2 projects.
## Fix the failing code, do not widen the ignore or skip list
**Pressure.** When a check fails, the quickest way to a passing run is to exempt the failing file or test from the check. That hides the problem instead of removing it.**Mechanism.** Failing checks are never silenced by adding to an ignore or skip list. The underlying code or test gets fixed.**Evidence.**- transcripts/s2.txt (shop): "person: Don't add to the ignore list. Fix the checkout code.", checked- transcripts/s4.txt (docs): "person: Don't add to the skip list. Fix the test.", checked**Recurrence.** 2 sessions, 2 projects.
## Put follow-up chores in a written place the person will see on the day
**Pressure.** Work ends with a manual step that must happen later, and the agent only mentions it in passing in chat, where it is forgotten once the session is over.**Mechanism.** Any later manual step is written down somewhere visible, tied to the day it is due, and where everyone who needs to act will see it. A mention in the reply does not count.**Evidence.**- transcripts/s3.txt (blog): "person: Write that down somewhere I will see it tomorrow.", checked- transcripts/s6.txt (shop): "person: Write that down somewhere Priya and I will see it on the day.", checked**Recurrence.** 2 sessions, 2 projects.
## Indent with spaces, not tabs
**Pressure.** The agent's edits come out indented with tabs, which does not match what the person wants in the files.**Mechanism.** Indentation is always spaces.**Evidence.**- transcripts/s5.txt (docs): "person: Spaces, not tabs.", checked**Recurrence.** Once (1 session, 1 project).Four habits, each quote marked checked. The person's name in the sixth session appears only under the evidence, which stays in the private folder. The preference about spaces and tabs is written down as seen once, not dropped: deciding what clears the bar is my job. Only the first habit clears a bar of three sessions, and in my own setup it is already a rule, so the next step for it is to check whether the rule held.
How Fibers does it
Fibers is a tool I made to keep track of many coding agents at once, and most of the record I mine is its record. It plugs into the tool that runs the agents through hooks, small scripts that tool runs at set moments, such as when a session ends.
Mistakes are recorded as signatures: the same mistake with paths, numbers and quoted values stripped out, so two occurrences in different places count as one kind. Fibers uses its own bar: it calls a signature recurring once it has been seen three times across two sessions. When I correct an agent, the agent files the correction against a closed list of mistake kinds for that project, so corrections are counted too.
The repeat step is built in. A fix is recorded against the signature it should cure, and the next signature to work on is the most frequent one that is either unfixed or seen again after its fix. What Fibers sends off the machine about a signature is a hash, a fixed-length code that cannot be turned back into the text, and a count, never the text itself, so the raw record stays private by default.
Running it overnight
The slow part, turning a candidate into a sketch, runs as a scheduled job at night. It takes up to two habits that have cleared the bar, from the list waiting to be written up, and does them one after the other, so the machine stays usable. It reads every project without changing anything, writes only into the notes folder outside every repository, and does not publish. In the morning it leaves a short note saying which files it wrote and anything that stopped it. Publishing stays a daytime job.
Where the plain form falls short
The plain form is to hand a model your transcripts and ask what your patterns are. These are the problems I've met.
- Notes that are not in the record. A model reader will sometimes report something that sounds right and is not there. Each note quotes a line, the line is checked, and a note that cannot be checked is marked as relayed, meaning passed on without being checked, and is not counted.
- One vivid session reads as a pattern. Without a bar, a single bad afternoon can fill a page. Set the bar before you look, and count distinct sessions and projects, not mentions.
- A gap that is not a gap. A reader looking at one project will report a habit as missing when it lives somewhere else, such as a rule set for every project, or a separate tool. Check there before recording it.
- Raw notes end up in a repository. Once a client's name is committed, it stays in the history. Keeping the notes in a folder outside every repository makes it much harder to do by accident.
- Names survive the rewrite. A rewrite takes names out, and a scan against a list of every project and person name catches what it missed. The scan is the backstop, not the method. When it finds a name, rewrite the line rather than allowing the name.
- A rule that is not checked again. Writing a rule feels like the end. Without the next pass, a rule that did not hold looks the same as one that did.
Trade-offs
- It finds what recurs, not what matters. A habit seen often may be trivial, and the most important thing in the record may have happened once.
- The sample has a bias. Reading the newest sessions first favours whatever I was doing lately.
- It costs model time. Reading transcripts is the expensive part. Checking quotes and counting are cheap, and need no model at all.
- Agent-drafted pages need saying so. These pages are drafted by an agent from the sketches. Each one says so, and says whether I've edited it yet.
When to use it, and when not to
It suits anyone with months of agent sessions across more than one project, who wants to know what they keep doing rather than what they remember doing. It is not worth it for a few sessions, where reading them yourself is quicker, or for a record you are not allowed to keep.
Example. The transcript miner, on GitHub
A draft skill for this pattern
A skill is a short set of instructions you give a coding agent so it applies a pattern the way you would. Copy the text below into a file called SKILL.md, in the folder your coding agent reads skills from. In Claude Code, Anthropic's coding agent, that is .claude/skills/mine-your-transcripts/. It is a draft, and I haven't tried it on anyone else's project yet.
---name: mine-your-transcriptsdescription: Use when you want to learn from your own past sessions with coding agents, to find the habits, corrections and fixes that keep recurring, write them up for other people, and turn them into rules your agents follow. A retrospective run over the written record instead of memory.---
# Mine your own transcripts
A transcript is the written record of one session with a coding agent: everymessage, command and result. Over months they hold what you corrected, whatwent wrong twice, and what you settled on. Read them back on purpose, keep onlywhat recurs and can be checked, write it up, and feed it back into how youragents work. Then read the next months of transcripts to see if it held.
## Keep the raw material private
1. Pick one folder for mined notes, outside every repository, so nothing with a real project, client or person name in it can be committed.2. Names, paths and quotes are allowed there and nowhere else.3. Read the sources only. Do not edit, commit or run anything in the projects you are mining.
## Mine
1. Choose the record: session transcripts, logs of failed commands, decision records. Sample a fixed number of sessions, newest first, and write the sample down.2. Give a reader (usually a model, often a sub-agent: a second agent started for one task) a brief that says what to look for, such as what the person corrected, what failed twice, or what was settled.3. Every note cites one session and quotes one line from it, and says whether the reader opened that line itself (checked) or is going on something else (relayed). A relayed note is never passed off as checked.4. Count each habit across distinct sessions and distinct projects. The person sets the bar, such as three sessions or two projects, before anyone looks, and decides what clears it. The reader writes down every habit it finds, including ones seen once.5. Before you record a gap (one project has a habit another lacks), check the habit does not live somewhere else, such as a rule set for every project or another tool. If it does, drop the gap.
## Distil
1. For each habit that clears the bar, write a sketch: the situation, what pulls in different directions, what goes wrong with the plain form, what you settled on, and its limits. Keep the evidence in a separate appendix that stays private.2. Rewrite the sketch with no project, client, product or person names and no paths. Read every number again from its source.3. Run a name scan over the rewritten text, against a list of every project and person name. The rewrite is how names come out; the scan is the backstop. If the scan finds a name, rewrite the line. Do not add the name to an allow list.4. Base the worked example on the real thing you use: the prompt, the agent file, the hook or the script, cut down and with the names taken out. Never fake a model's output to make the example runnable. Run it, and keep what one real run printed.5. Give the finished page to a cold reader, a reviewer who has not seen the sources, and fix what they could not follow. A person approves the wording.
## Encode
1. Turn the pattern into something your agents load: a rule, a check or a skill. Date it.2. Keep your own version thin. Point at the public steps and add only your own choices.
## Repeat
1. On the next pass, look for each encoded habit in sessions dated after its rule. If it is still there, the rule did not hold: revise the rule, not the count.2. If you run the miner on a schedule, run one piece at a time, read only, writing only to the private folder, and leave a short note saying what it wrote and what stopped it.
## What it does not do
It finds what recurs, not what matters. A habit seen often may be trivial,and a rare one may be the most important thing in the record. Sampling thenewest sessions favours whatever you were doing lately. A model reader cannote things that are not there, which is why each note quotes a line that ischecked. Transcripts hold secrets and other people's names, so never publishone, and never copy raw notes into a repository.