Detailed content
🧭 Why an agent loses its way over hours
An agent that works for minutes usually does fine. Over hours, a problem emerges: the conversation fills up, the system compacts (summarizes) what came before, and important details get lost. The agent starts repeating "I'll finish and commit" without finishing, or reopens an item that was already done. This is context degradation, and it’s not a lack of intelligence: it’s a lack of memory outside the conversation.
🌱 New here?
Compaction is when the agent summarizes the old conversation to make room for more. The summary is useful, but it forgets details. Context degradation It's when, after a few compactions, the agent no longer remembers what was agreed.
🔥 Signs that context has degraded
Repeating the same closing line without wrapping up; reopening an item that was already done; forgetting a rule agreed at the beginning; going in circles without producing anything new. If you see this, the session has already gone too far.
✓ The solution
Move the memory out of the conversation and into files: the goal with proof of completion, the current state, the plan, and notes. After each compaction, the agent rereads the files and gets back on track. That’s what the kit execucao-longa organizes.
Why learn
Because long-running execution only works if the direction is in files and not in the agent’s head. Understanding why it gets lost shows which safeguards to set up in the next topics.
Key concepts
📁 The longrun/ folder (novo-longrun.sh and the 7 files)
The kit creates a dedicated folder for each long-running task. You run tools/novo-longrun.sh <projeto> <slug> and it creates longrun/<data>-<slug>/ with seven files. Each has a purpose, and together they form the memory that survives compaction.
🌱 New here?
O slug is a short name for the task, with no spaces (e.g., limpar-docs). O canal is a file where the agent only adds notes: facts, lessons, and pitfalls that compaction tends to erase.
The 7 files created by novo-longrun.sh
longrun/2026-10-12-meu-projeto/ ├── goal.md # the result + proof of completion ├── plan.md # the steps ├── state.md # where I am now ├── progress.md # what has been done ├── failures.md # what went wrong ├── decisions.md # what was decided └── canal.md # notes on what compaction loses
🔎 Golden rule
After every compaction or resumption, the agent rereads these files in this order: goal, state, plan, canal. During the work, it adds notes to canal early and commits at every checkpoint.
Why learn
Because this folder turns “an agent that gets lost” into “an agent that picks up where it left off on its own.” When the direction is written down, you never start from zero.
Key concepts
🎯 goal.md level 3: command → output
O goal.md states the result in one sentence and, most importantly, how to prove it’s done. Each criterion is a command → expected output. At level 3, the criteria cover functionality (it does what it should), regression (it hasn’t broken what already worked), and limits (it couldn’t be satisfied with a shortcut).
🌱 New here?
One shortcut means meeting the criterion without doing the actual work, for example, deleting the failing tests to get “0 failures.” Regression and limits close that loophole.
Example of proof of completion at level 3
# goal.md Result: all site pages pass the validator. Proof of completion (level 3): 1. functionality npm test → 0 failures 2. regression ls tests/ | wc -l → still ≥ 48 tests 3. limit git diff --stat tests/ → empty (tests/ untouched)
⚠️ Why “0 failures” alone isn’t enough
A rushed agent might delete the failing test. That’s why the example requires 0 failures e at least 48 tests e the tests/ folder left untouched. Three checks together, no shortcuts.
Why learn
Because the agent only stops when the check passes. If the check is weak, it “finishes” early and gets it wrong; if it’s strong, it keeps working until it really gets it right.
Key concepts
▶️ Run /goal in Codex and Claude Code
With the goal.md ready, you start the work with the command /goal, which exists in both Codex and Claude Code. You point to the goal, and the agent keeps working until the check passes. The same kit works with both runners, like the portable identity in module 5.1.
🌱 New here?
O /goal is a command that sets a goal and keeps the agent trying until it meets that goal, instead of stopping at the first answer.
🔎 Note for Claude Code
There, the check needs to appear in the output of the conversation. The /goal evaluator only reads the conversation; it won’t open your files. So have the agent run the check command and show the result.
✓ While it runs
Keep an eye on it without interrupting. Re-read the channel from time to time. Intervene only when you see the signals in the next topic.
Why learn
Because /goal is the “go and come back later” button. Without it, you’d have to keep nudging the agent at every step.
Key concepts
🛑 When to stop and call in a human
Long work doesn’t mean working without you. There are three signs that it’s time to stop the agent and step in: three cycles with no measurable progress; the agent repeats “I’ll finish and commit” without finishing or reopens an item that’s already done (the context has degraded); and 3rd compaction.
🌱 New here?
One A cycle with no measurable progress is a round in which no number in the check improves (the same tests fail, the count stays the same). Handoff is the handoff summary that the next session reads to continue.
1. No progress
3 consecutive cycles with no improvement in any measurement.
2. Context has degraded
Repeats the wrap-up without finishing or reopens a completed item.
3. Third compaction
Save the handoff, open a new session, and run /prime.
⚠️ Also call in a human when
Credit or an API is involved, an action is irreversible or external, a credential is missing, or a business decision is needed. This connects to the guardrails in the Rules and Hooks module: the agent doesn’t decide on its own what is costly or irreversible.
Why learn
Because knowing when to stop is part of the method. The costly mistake is letting the agent spin its wheels for hours.
Key concepts
🤖 Headless mode: loop-longrun.sh with limits
In headless mode, no one watches the screen. The script tools/loop-longrun.sh <pasta> repeats cycles, each one a codex exec with a time limit. The check decides whether to continue. The loop stops by itself when the task is complete, when progress stalls, or when it hits a limit.
🌱 New here?
Headless means running in the background without a window or interaction. A limit is a maximum threshold (for time or memory) that stops the process before it harms the machine.
The headless mode loop
tools/loop-longrun.sh longrun/2026-10-12-meu-projeto │ ├── each cycle = one codex exec with a time limit ├── the test, not the agent └── stops on its own: completion · stagnation · limit
🔥 Always set limits
Timeout for each cycle, memory limited with systemd-run --user --scope -p MemoryMax= e short tool output. Without a limit, a forgotten loop can freeze the computer.
Why learn
Because it lets you sleep while the agent works safely. Limits are the seat belt.
Key concepts
🛠️ HANDS-ON: your first longrun + medir-sessao.py
Time to get to work. Choose a small, verifiable task (something a command can prove is finished) and run the full cycle. At the end, tools/medir-sessao.py shows the session duration, compactions, tokens, and cache, so you can see what the task cost.
🌱 New here?
O .jsonl is the session log file that Claude Code and Codex store. The medir-sessao.py reads that log and returns the numbers.
Step-by-step for your first longrun
# 1. create the task folder tools/novo-longrun.sh meu-projeto limpar-docs # 2. open and fill in goal.md (result + level 3 proof) longrun/<data>-limpar-docs/goal.md # 3. start /goal in Codex or Claude Code /goal longrun/<data>-limpar-docs/goal.md # 4. track progress: reread goal → state → plan → canal after compaction # 5. at the end, measure the session (duration, compactions, tokens, cache) tools/medir-sessao.py <sessao>.jsonl
✓ Check at the end
The goal.md proof passed, canal has useful notes, and you have the session numbers. If it stopped early, check failures.md to see what got stuck and adjust the proof.
🔗 Guide and resource area
Full guide: inematds.github.io/execucao-longa/guia. Resource area: eventos.inema.pro/execucao-longa.
Why learn
Because you learn long-running execution by doing it once. Your first small longrun teaches you more than reading everything twice.
Key concepts
🎉 You’ve reached the end
End of Track 5—and of the course:
You’ve completed all 5 tracks. Now choose a domain, build your OS, and run /os-coach audit to score it against your goal.