Lesson 1 · 15 min
A long session fails in three ways: it doesn't know when to stop, it forgets what it did after compaction, and it spends what it shouldn't. The execucao-longa kit answers with files, not with the model's memory: the agent rereads the folder instead of remembering. In this lesson you install the kit and create your first folder.
Start the lesson
Goal: create the longrun/ folder for a run and say, for each of the seven files, who writes it, when it is read, and whether it only appends.
Tap each block: who writes it, when it is read, and how it changes.
Scroll the page: each step below lights up its part of the diagram.
Result in one sentence, done criteria (function, regression, limit), caps, constraints, and human gates. It is the only file the agent should not rewrite: changing the goal midway means changing the task.
Both are snapshots of right now: rewrite, don't accumulate. state.md ends with the exact commands to resume. When the first line of "Funciona" says concluído, the watchdog and the hook stop treating the run as active.
Dated history in a table. You never delete a line: it's what lets you see later whether the agent reopened an item that was already done or repeated the same attempt three times.
Project knowledge, not task state: where things are, the right name for each piece, the trap that cost an hour. Append only, one line per fact, with a date. The hook asks you to fill it in at band 1 (lesson 3).
After every compaction or resume, the first thing is to reread the files, in this order: goal → state → plan → canal → end of progress and failures, and continue from the first pending item.
The goal stays parked in goal.md; the now lives in plan and state; the history only grows in progress, failures and decisions; what the summary loses lives in the canal.
The same files work for Claude Code and for Codex: one picks up what the other wrote.
One run from start to finish, seen through the files.
novo-longrun.sh creates the folder with the seven files already stamped with the date.
You fill in goal.md. It's the slow part, and it decides whether the run finishes (lesson 2).
longrun/2026-10-19-contador-palavras/
Reads state and plan, picks the next useful action, runs it and tests it.
At the end it rewrites state and plan and adds a line to progress. If something went wrong, a line in failures.
| 2026-10-01 14:30 | medição do piloto | 7714c3c | sim (nível 3) | 332791 / 304000 / 4296 | 0 |
The compaction summary mixes what is confirmed with guesses. The files don't.
The agent rereads goal → state → plan → canal before acting and does not reopen what state says is done.
state.md says done, but you are the one who closes it: run the final test yourself and measure the session (lesson 7).
The smallest fix for each failure goes from failures.md to the project's FALHAS.md.
Once per machine, and then one folder per run. The paths follow the kit's README.
git clone https://github.com/inematds/execucao-longa ~/projetos/execucao-longa cd ~/projetos/execucao-longa python3 -m pytest -q -p no:cacheprovider | tail -1
~/projetos/execucao-longa/tools/novo-longrun.sh ~/projetos/<seu-projeto> <slug-do-objetivo> ls ~/projetos/<seu-projeto>/longrun/*/
## Execução longa (/goal, loop, objetivo de horas) — método em ~/projetos/execucao-longa - **Antes de começar:** `~/projetos/execucao-longa/tools/novo-longrun.sh <projeto> <slug>` cria `longrun/<data>-<slug>/` (goal, plan, state, progress, failures, decisions, canal). Critério de pronto no `goal.md` em **nível 3+**: `comando → saída esperada`, cobrindo função, regressão e limite, sem atalho possível (contagem mínima, testes congelados, validador). - **Durante:** releia goal → state → plan → canal após toda compactação ou retomada; registre cedo no `canal.md` (só acrescentar) fatos, aprendizados, glossário e armadilhas; teste cada mudança; commit a cada checkpoint; continue enquanto houver próxima ação útil e segura. - **Parar e chamar o humano:** 3 ciclos sem avanço mensurável; o mesmo plano de fechamento repetido sem fechar ou item já feito reaberto (contexto degradou); crédito/API, ação irreversível ou externa, credencial ausente, decisão de negócio. - **Faixas de contexto** (no Claude Code o hook avisa uma vez cada; no Codex, acompanhe o % em `/status`): ~50% → registrar no `canal.md`; ~70% → atualizar estado e pedir `/compact`; ~85% ou 3ª compactação → `/session-handoff` + sessão nova + `/prime`. - **Headless:** `~/projetos/execucao-longa/tools/loop-longrun.sh <pasta-longrun>` (flock, timeout, MemoryMax, testes protegidos, parada por estagnação). Medir: `tools/medir-sessao.py <jsonl>`. - Tetos sempre: timeout, memória (`systemd-run --user --scope -p MemoryMax=`), saída de ferramenta curta. - **Histórico:** `recall "termo" [--projeto X] [--fonte codex|claude] [--desde AAAA-MM-DD]` busca em tudo o que já foi dito com o Codex e o Claude nesta máquina (índice reindexado de hora em hora) — use antes de perguntar ao usuário algo que pode já ter sido decidido.
$ python3 -m pytest -q -p no:cacheprovider | tail -1 73 passed in 18.59s $ novo-longrun.sh ~/ensaio/projeto-teste contador-palavras criado: ~/ensaio/projeto-teste/longrun/2026-10-19-contador-palavras próximo: preencher ~/ensaio/projeto-teste/longrun/2026-10-19-contador-palavras/goal.md (critérios nível 3+) e colar templates/prompt-goal-codex.md no /goal $ ls ~/ensaio/projeto-teste/longrun/*/ canal.md decisions.md failures.md goal.md plan.md progress.md state.md $ novo-longrun.sh ~/ensaio/projeto-teste contador-palavras já existe: ~/ensaio/projeto-teste/longrun/2026-10-19-contador-palavras $ echo $? 1
Run with the 10/18/2026 kit; only the path of the rehearsal folder was shortened. The pytest time changes from machine to machine.
longrun/*/state.md at the root of the git repository.Six minutes with the concept (10/10/2026). The concept holds; two details changed afterward: at band 3 and at the 3rd compaction the agent finishes the task in progress before the new session (lesson 3), and the care with the cache today is the automatic handoff at 45 min idle (lesson 4).
On your machine. Only move on to the next one when the "done when" is true.
Clone the kit into ~/projetos/execucao-longa and run its test suite.
Done when: python3 -m pytest -q -p no:cacheprovider | tail -1 → 73 passed (in a newer clone the number may be higher; failed must never appear).
Pick a real task from one of your projects that takes more than an hour and create its folder. Run the same command twice.
Done when: ls ~/projetos/[your-project]/longrun/*/ | wc -l → 7; the second call prints já existe: and echo $? → 1.
Paste the block from templates/AGENTS-long-run.md into ~/.claude/CLAUDE.md and into ~/.codex/AGENTS.md. Open a new session and ask: "how do you start a long run?" The block also mentions /session-handoff, /prime and recall: they only exist from lessons 5 and 7 on.
Done when: grep -c novo-longrun.sh ~/.claude/CLAUDE.md → 1 or more, and the new session answers by citing novo-longrun.sh and the level 3 criterion without you reminding it.
Question 1 of 4
Which of these files should the agent REWRITE each cycle, instead of only appending to?skill
Question 2 of 4
The agent found out that the test database only starts with the variable DB_LOCAL=1. Where does this go?
Question 3 of 4
After a compaction, what is the first thing the agent does?skill
Question 4 of 4
You ran novo-longrun.sh with a slug that already exists today. What happens?
Pick an answer. The explanation shows up after you try.