🔁 Handoff and prime: the daily cycle
The readback proves the core works once. The daily cycle is what keeps it working every day: session → handoff → Markdown → prime → new session. In this module you write the handoff, build latest.md, learn the prime prompt and have Claude and Codex take turns on the same work without losing anything along the way.
📦 What goes into a handoff
The handoff is the note the session that is ending leaves for the session that hasn't started yet. It is not a report for humans, not a changelog and not a pretty summary: it is the minimum information that lets an agent with no memory at all resume the work at the exact point where you stopped. The criterion is brutally simple — if the next agent has to ask anything to get started, something was missing from the handoff.
The flow described in the kit documentation has five mandatory items, and they came from practice, not theory: decisions made, unfinished tasks, next steps, file paths and checks run with their results. The first four are what the /handoff command looks for in a session; the fifth is what module 2.5 taught you to produce, and it is what stops the next agent from celebrating a migration nobody tested.
The cycle always turns in the same direction: the closing session produces a file, and the opening session reads that file. No arrow passes through the chat — that is why the cycle survives a /clear, a reboot and a runtime switch.
🧭 New here? Four words from this module
- Session — one continuous conversation with the agent, from the first prompt until you close it or run
/clear. When it ends, the agent forgets everything. - Handoff — the Markdown file the session writes before it dies, recording the state of the work.
- Prime — telling the new session to read that file before it touches anything. To "prime" is to load the context right at the start.
- JSONL — the format runtimes use to store the raw conversation history, one JSON line per event. It's a machine log, not a document.
✓ Goes in the handoff
- ✓Accepted decisions, along with what was dropped ("we chose X, abandoned Y").
- ✓Unfinished tasks, with the exact point where they stopped.
- ✓File paths, absolute or relative to the project root, never "that script".
- ✓Checks that were run, with the result: passed, failed or not run.
- ✓Open questions that need the human owner to answer.
✗ Stays out
- ✗A narrative of the session ("first I tried this, then that"). The next agent doesn't need the journey.
- ✗Failed searches, abandoned paths, exploration noise.
- ✗Credentials, tokens, API keys — never, under any circumstances.
- ✗A promise that something uncommitted "is available in another worktree".
- ✗An unresolved failure erased so the handoff looks clean.
Key concepts
A structured note from the session that's closing to the session that's opening.
A future instance of the agent, not a manager. Write for whoever will execute.
Decisions, pending work, next steps, paths, checks with results.
An unresolved error stays in the handoff until someone actually fixes it.
📄 The handoffs/latest.md template
The kit settles the format question with a seven-section template in template/handoffs/latest.md. It's empty on purpose: the value is a stable structure. If every session writes to the same seven sections, in the same order, the agent reading it knows where to look without interpreting anything. When a section has nothing to say, you write "none" — you never delete the section.
Goal: create your project's handoffs folder from the kit's template.
mkdir -p ~/projetos/<your-project>/handoffs
cp ~/projetos/agente-claude-codex/template/handoffs/latest.md \
~/projetos/<your-project>/handoffs/latest.md
cat ~/projetos/<your-project>/handoffs/latest.md
# → # Handoff — AAAA-MM-DD
# ## Projeto e escopo
# ## Objetivo atual
# ## Estado aceito
# ## Arquivos alterados
# ## Checks rodados e resultado (passou / falhou / não rodado)
# ## Perguntas abertas
# ## Próxima ação exataHow to check: the cat shows the seven sections and nothing else. Replace <your-project> with the real folder. If your project already has handoffs/latest.md, don't overwrite it: compare the section titles and add the missing ones.
The template alone doesn't teach much. What teaches is seeing the file actually filled in. Below is the kit's real handoffs/latest.md, written at the end of the September 13, 2026 session — the same session whose readback you studied in the previous module. Notice what it does and what it doesn't: not a single sentence about how the session went, every section present, two checks marked as not run, and a next action that is literally a pasteable command.
Real file: the kit's handoffs/latest.md (excerpt, with sections in template order).
# Handoff — 2026-09-13
## Projeto e escopo
agente-claude-codex: kit de migração / workspace agnóstico. Escopo desta
sessão: criar o repo, plano, prompts, scripts, template e primeira evidência.
## Objetivo atual
Ver tasks/current.md: validar piloto (session-handoff no Codex + readback
nos dois runtimes).
## Estado aceito
Repo criado, 2 commits, branch main, sem remote. Auditoria rodada
(relatorios/auditoria-2026-09-13.md). Readback aprovado no Codex e no Claude.
Nada em ~/.claude ou ~/.codex alterado.
## Arquivos alterados
PLANO.md, README.md, AGENTS.md, CLAUDE.md, prompts/*, scripts/*, template/*,
context/*, tasks/current.md, .gitignore, este arquivo.
## Checks rodados e resultado
- scripts/audit.sh — passou (89 skills só no Claude).
- template/scripts/check.sh — passou.
- scripts/readback-test.sh . codex — passou na 2ª rodada.
- scripts/sync-skills.sh — não rodado (aguarda escolha do piloto).
- Cópia isolada + check.sh — não rodado.
## Perguntas abertas
- Qual projeto real é o piloto? (default: este repo)
- Publicar em inematds/agente-claude-codex?
## Próxima ação exata
`scripts/sync-skills.sh import session-handoff && scripts/sync-skills.sh build`,
depois `install session-handoff --codex` e `drift`.How to check yours: read only the last section and ask, "could I run this right now, without opening anything else?". If the answer is no, the section is written as an intention ("continue the migration") rather than an action ("run this command in that folder").
💡 Practical tip: why the file is called latest
The fixed name is what makes prime automatable. You can keep a dated history alongside it (handoffs/2026-09-13.md), but latest.md must always point to the most recent one, because that is the name that goes into the prime prompt, the scripts and AGENTS.md. A variable name forces the agent to guess which file to read — and guessing is exactly what the portable core exists to eliminate.
Key concepts
Scope, goal, accepted state, files, checks, questions, next action.
An empty section becomes "none"; a section is never deleted.
Fixed name, latest content. It is what prime looks for.
A pasteable command, not an intention. It is the section that saves the most time.
🚀 Prime: the new session reads before acting
Writing the handoff is half the cycle. The other half is making sure someone reads it. A fresh agent, left to its own devices, starts acting: it opens random files, infers the goal from the README, proposes a refactor nobody asked for. Prime reverses the order — first read, then talk, only then act. It is a one-sentence change in your first prompt of the day, and it is the difference between resuming the work and starting it over.
Goal: open the day in any runtime without the agent running off to execute. Paste this text as the first message of the session, inside the project folder.
Read handoffs/latest.md and tasks/current.md before acting and tell me the exact next
action, citing the file.How to verify: the answer is short, names both files and returns one action, not a plan. If the agent replies with a refactoring proposal, or cites no file at all, it did not read — and the first thing to investigate is the reading order in AGENTS.md, not the prompt.
Look at each piece of the sentence, because each one is there for a reason. "Read … before acting" blocks premature editing. "the exact next action" asks for a single, executable thing, not a ten-step roadmap. "citing the file" is the same trick as readback: it forces the agent to show the source, which makes a lie visible. Two files, one action, one citation — that is the whole prime.
You open the session in the project folder
Without this, the agent reads files from somewhere else, or from nowhere. The folder is the scope.
Paste the prime prompt
One sentence. The agent reads handoffs/latest.md and tasks/current.md and nothing is modified yet.
It returns the next action, citing the source
You compare it with what you remember. If it matches, move on. If it doesn't, the handoff is out of date — fix the file before working.
Only then do you authorize execution
The day's work starts with context loaded and aligned, not with an assumption.
At the end of the day, the handoff closes the cycle
The session rewrites handoffs/latest.md and the wheel returns to the start, with the state updated.
📋 Prime and readback are not the same thing
Readback is a test: you run it every now and then, with five questions, to prove the core works, and you don't let the agent edit anything. Prime is routine: you run it every day, with one question, to load context and start working. Same principle — read the files and cite the source — in two different doses.
Key concepts
Loading context from the file at the start of the session, before any action.
Blocks premature editing, the most common mistake of a new session.
Asking for "the exact next action" avoids speculative roadmaps.
If the answer doesn't match your memory, the handoff has gone stale. Fix the file.
🔀 Cross-runtime: Claude writes, Codex resumes
This is where the daily cycle delivers on the promise of the whole course. Because the handoff is a Markdown file in the project folder, and not the internal state of a runtime, whoever writes and whoever reads don't need to be the same program. You wrap up the afternoon in Claude, open the evening in Codex, and the work carries on. Or the other way around. The file is the meeting point; the executors take turns around it.
Blue and cyan arrows converge on the same file: handoffs/latest.md is the only shared thing. Below, the cut path shows what does not cross over: each runtime's JSONL histories are islands, and that is why the Markdown exists.
Goal: prove the relay works in practice: prime Claude and Codex against the same handoff and compare their answers.
cd ~/projetos/<seu-projeto>
claude -p "Read handoffs/latest.md and tasks/current.md before acting and tell me \
the exact next action, citing the file."
codex exec --skip-git-repo-check "Read handoffs/latest.md and tasks/current.md \
before acting and tell me the exact next action, citing the file."How to check: both answers point to the same next action and cite the same files. Differences in style are normal and expected. Differences in content mean the handoff is ambiguous, and you fix the file, not the prompt. The --skip-git-repo-check flag stops Codex from refusing to run when the folder isn't a git repository.
✓ Crosses runtimes
- ✓
handoffs/latest.md: plain text that any agent can read. - ✓
tasks/current.mdandcontext/decisions/: same principle. - ✓
AGENTS.md, which both runtimes treat as project instructions. - ✓The prime prompt, which is a single sentence and doesn't rely on a built-in command.
✗ Doesn't cross
- ✗Each runtime's JSONL history, which lives in your home folder and can't be read by the other one.
- ✗The
/handoffcommand itself: the gesture changes, but the file it produces is the same. - ✗Session memory, loaded context, "what we agreed on yesterday".
- ✗Harness tool state (background processes, running servers).
Key concepts
One writes, the other picks up, in both directions, through the same file.
The project's Markdown, not the runtime or the account.
Lets codex exec run in a folder that isn't a git repository.
A symptom of an ambiguous handoff. Fix the file, not the agent.
🗃️ JSONL sessions are history, not a source
Both runtimes record everything that happens in a session in JSONL files (one JSON line per event) inside your home folder. It's a faithful, complete record, and that's exactly why it doesn't work as working memory: it keeps everything, including what went wrong, what got thrown out and what you changed your mind about three times. A handoff of twenty curated lines is worth more than three hundred megabytes of faithful transcript.
Goal: see for yourself how big the raw history on your machine is, and where each runtime keeps it.
find ~/.claude/projects -name '*.jsonl' | wc -l
du -sh ~/.claude/projects
find ~/.codex/sessions -name '*.jsonl' | wc -l
du -sh ~/.codex/sessions
# on this machine, on 09/14/2026:
# Claude: 6,859 .jsonl files · 2.3 GB
# Codex: 209 .jsonl files · 601 MBHow to check: your machine's numbers will be different, and it doesn't matter what they are. What matters is noticing that there are two archives, in different folders, and that neither runtime reads the other's. If the path doesn't exist, the runtime isn't installed or stores its history somewhere else. Neither case changes the conclusion.
It's tempting to think of tools that read this history and rebuild the context automatically. They exist, and they're useful for auditing and for analyzing behavior. But look at what happens when you depend on them: the project's context ends up living in a proprietary format, inside one account's home folder, tied to one runtime. That's exactly the dependency this whole course is taking apart. The JSONL is the flight's black box; the handoff is the flight plan for the next one.
✓ What JSONL is good for
- ✓Auditing what really happened when something went badly wrong.
- ✓Recovering a specific passage you forgot to record in the handoff.
- ✓Analyzing the model's behavior patterns across many sessions.
- ✓Forensic proof that a check was run on a given date.
✗ What it's not good for
- ✗Being the project's source of truth: it lives in your home folder, not in the work folder.
- ✗Passing context between runtimes: each one has its own format and path.
- ✗Being read by a human: gigabytes of events, with no curation.
- ✗Going into the project's git: it's noisy, it's big and it sometimes contains secrets.
Notice: the gap between 6,859 and 209 files doesn't mean one runtime is better. It means the history archive grows with use and stays completely local to each tool. If you bet your work's memory on that archive, you're stuck with the runtime that produced it, and you start from scratch when you switch tools, machines or accounts.
Key concepts
One JSON line per event. A machine log, faithful and bulky.
A record of what happened, not a statement of what holds now.
What lives in your home folder doesn't travel with the repository.
Twenty chosen lines are worth more than gigabytes of transcript.
🏅 Golden rule: handoff before closing, always
Just one rule, and it has no exceptions: no session closes without a written handoff. Not the five-minute session, not the one where "nothing changed", not the one that ended in the middle of a command. The short session is exactly the one you'll forget, and the interrupted one is the one that needs the note most. The cost is one minute; the cost of skipping it is the half hour the next session spends rediscovering where it was.
To write that handoff without relying on your own discipline, there is a ready-made prompt in the kit's prompt library, stored in prompts/03-readback-handoff.md under the title "Continuation handoff". It is the exact counterpart of the readback you saw in module 2.5: that one reads and proves, this one writes and preserves. Notice the prohibitions in the middle of the text — they are there because they are the three most common ways a handoff lies.
Goal: have the session that is ending write its own handoff. Paste it as the last message, in any runtime.
Create a concise continuation handoff for a fresh agent. Include the project and scope,
current objective, accepted state, changed files, checks actually run and their results, open
questions, and exact next action. Cite source paths and relevant revisions. Preserve
unresolved failures. Do not include credentials or claim that uncommitted changes are
available in another worktree. Update the current task/state only where the evidence
supports it.How to verify: the output covers the template's seven sections, cites real file paths, keeps the unresolved failures and ends with a runnable command. Save it to handoffs/latest.md and reread it: if any section describes the conversation instead of the state, rewrite that section by hand before closing.
"Preserve unresolved failures"
A failure that wasn't resolved stays in the handoff. A handoff that's too clean is a handoff that erased the problem.
"Do not include credentials"
The handoff usually goes into git. An API key in versioned Markdown is a leak, not context.
"Checks actually run"
The three states from module 2.5 come in here: passed, failed or not run. No "it should be working".
"Only where the evidence supports it"
The agent updates tasks/current.md as far as the evidence reaches, and stops. The rest becomes an open question.
⚠️ The mistake to avoid
Closing the session thinking "I'll remember tomorrow". Tomorrow you remember half, and the agent remembers nothing — its memory ended the instant the session closed. The handoff isn't for you: it's for the executor that will arrive with no context at all, whether it's Claude, Codex or the third runtime that doesn't even exist yet.
Key concepts
Short session, interrupted session, "nothing new" session: they all write one.
Ready-made prompt in prompts/03-readback-handoff.md. Counterpart of the readback.
The file goes into git; secrets never go in it.
Update the state only as far as there is proof; the rest is an open question.
Self-check (optional): you worked all afternoon in Claude and want to continue tonight in Codex. What needs to cross over for the work to continue?
🎯 Module summary
handoffs/latest.md with a fixed name, stable structure and the exact next action as a pasteable command.Next:
Track 3 · Project 3.1 — migrate your first real project