What breaks when an agent runs for hours
Ask a coding agent to build a clone of claude.ai and leave it running, and two failures turn up. Anthropic ran that experiment with Opus 4.5 on the Claude Agent SDK and wrote both down in its engineering post on long-running agents. First, the agent tried to build the whole app at once, ran out of context in the middle of a feature and left the next session a half-built feature with no notes. Later, a fresh session looked around, saw plenty of working code and declared the job done. It was not.
An older model showed a third failure. Anthropic's Labs team found that Claude Sonnet 4.5 began wrapping up early as it neared what it took to be its context limit, and named it context anxiety. Compaction alone did not cure it, so that harness reset the context and passed a written handoff to a fresh agent.
In Anthropic's study of Claude Code sessions, the longest turns, the 99.9th percentile, nearly doubled between October 2025 and January 2026, from under 25 minutes to over 45. The post adds that extreme turn duration has declined somewhat since mid-January. A context window is the text a model can see in one call, and a long-running agent is built to outlast many of them: one task, many sessions, each starting empty.
Before you start
This lesson builds on the loop from what an agent harness is and the tool design of lesson 2. Compaction, memory files and context editing keep one session going, and agent memory teaches them. Here the problem is the gap between sessions.
The worked example is Anthropic's autonomous-coding quickstart, an agent harness in Python on the Claude Agent SDK. It needs the Claude Code CLI, Python and an ANTHROPIC_API_KEY, and its README warns that a full app takes many hours across many sessions. The quickstart still imports the older claude_code_sdk package. The SDK now ships as claude-agent-sdk, and its README lists the rename of ClaudeCodeOptions to ClaudeAgentOptions.
Set up the first session: spec, feature list, init script, git
The first session writes almost no app code, on purpose. Anthropic calls it the initializer agent, and it shares the system prompt, the tools and the harness with every later session: only its first user message differs. Its job is to turn a spec into files a stranger could pick up.
The feature list stops the early victory. Each entry is an end-to-end test with a passes flag, and every flag starts as false. The format below is copied from the quickstart's initializer prompt. Anthropic chose JSON because the model was less likely to change or overwrite a JSON file than a Markdown one.
[
{
"category": "functional",
"description": "Brief description of the feature and what this test verifies",
"steps": [
"Step 1: Navigate to relevant page",
"Step 2: Perform action",
"Step 3: Verify expected result"
],
"passes": false
},
{
"category": "style",
"description": "Brief description of UI/UX requirement",
"steps": [
"Step 1: Navigate to page",
"Step 2: Take screenshot",
"Step 3: Verify visual requirements"
],
"passes": false
}
]- Put the spec in
app_spec.txtand tell the initializer to read it before anything else. - Have it write
feature_list.jsonfrom the spec. The quickstart asks for 200 tests in priority order, a mix of short checks and long ones of ten steps or more. Its README suggests 20 to 50 for a quicker demo. - Forbid edits to the list in plain words. The prompt says, in capitals, that removing or editing features is catastrophic, and allows later sessions to change only
passes. - Have it write
init.sh, which installs dependencies and starts the dev server, so no later session spends context working that out. - Make the first git commit with the list, the script and a README, then write
claude-progress.txtbefore the context fills.
Start every later session the same way
Every session after the first is a coding agent with no memory at all. Its prompt opens with a fixed routine that rebuilds the picture from files in seven commands, copied below from the quickstart's coding prompt.
Then the routine turns strict. Before new work, the agent reruns one or two core tests already marked passing, because the last session may have broken them, and fixes what it finds first. It picks the highest-priority failing feature, builds only that and checks it through the browser the way a user would, taking screenshots as it goes. Only then may it flip passes to true, commit, and add to the progress file what it did and what should come next.
Anthropic found that commits with descriptive messages and a summary file were the best way to make the agent leave the code in a clean state, and git let it revert a bad change. The table maps each failure to its fix.
# 1. See your working directory
pwd
# 2. List files to understand project structure
ls -la
# 3. Read the project specification to understand what you're building
cat app_spec.txt
# 4. Read the feature list to see all work
cat feature_list.json | head -50
# 5. Read progress notes from previous sessions
cat claude-progress.txt
# 6. Check recent git history
git log --oneline -20
# 7. Count remaining tests
cat feature_list.json | grep '"passes": false' | wc -l| What went wrong | What the first session sets up | What every later session does |
|---|---|---|
| The agent declares the whole project done | A feature list written from the spec | Reads the list and picks one failing feature |
| Bugs and unrecorded progress carry over | A git repository and a progress file | Reads the notes and git log, reruns a basic test, then commits and updates the notes |
| Features get marked done too early | The feature list | Checks each feature itself and marks it passing only after careful testing |
| Time goes into working out how to run the app | An init.sh script | Reads init.sh at the start |
End-to-end checks have blind spots. The post notes that Claude could not see browser-native alert dialogs through the Puppeteer MCP server, and features that relied on them came out buggier.
Restart the agent in a loop
Something has to start the next session when one ends. In the quickstart that is a Python loop. It creates a fresh client for each session, sends the initializer prompt once and the coding prompt after that, waits three seconds and goes again. It never stops on its own. The --max-iterations flag caps the number of sessions, and Ctrl+C pauses the run until you start the same command again.
Nicholas Carlini, a researcher on Anthropic's Safeguards team, used a bare shell loop to have 16 agents write a C compiler in Rust over nearly 2,000 Claude Code sessions. The compiler came to about 100,000 lines and builds Linux 6.9 on x86, ARM and RISC-V. The loop below is copied from his post, where one line sits above it: run this in a container, not your actual machine. The flag in it switches off every permission prompt, and agent guardrails, the next lesson, is about what goes around it.
The harness in his post had more lessons once several agents shared one repository:
#!/bin/bash
while true; do
COMMIT=$(git rev-parse --short=6 HEAD)
LOGFILE="agent_logs/agent_${COMMIT}.log"
claude --dangerously-skip-permissions \
-p "$(cat AGENT_PROMPT.md)" \
--model claude-opus-X-Y &> "$LOGFILE"
done- An agent claims a task by writing a text file to
current_tasks/, such ascurrent_tasks/parse_if_statement.txt. If two agents claim the same task, git's synchronization makes the second one pick another. - Test output is written for the model. The harness should not print thousands of useless bytes, and a failure line says ERROR with the reason on the same line, so grep finds it.
- Slow suites are sampled. A default
--fastoption runs a random 1% or 10% of the tests. - Each agent starts in a fresh container, so the prompt asks it to keep READMEs and progress files current.
When to split the work across agents
More agents buy parallel work and a clean context for each worker. They also cost tokens. Claude's research feature makes that trade. A lead agent plans the research and saves the plan to memory, since a context window past 200,000 tokens gets truncated. It then starts subagents that search in parallel. Each subagent returns its findings to the lead. The post's closing tips add that subagents can store their work in an outside system and pass back a lightweight reference, so less is lost relaying long results upward. In Anthropic's internal research eval, Claude Opus 4 leading Claude Sonnet 4 subagents beat a single Claude Opus 4 agent by 90.2%.
Tokens climb fast, as the chart shows: Anthropic says agents typically use about 4 times what a chat does, and multi-agent systems about 15 times. On BrowseComp, a test of how well browsing agents find hard-to-find facts, token use alone explained 80% of the variance in scores. We would start a coding task with one agent and good notes, and add workers only for parts that do not touch each other. The post gives two reasons. Most coding tasks have fewer truly parallel parts than research, and work where every agent needs the same context fits multi-agent systems badly today.
Source: Anthropic Engineering: How we built our multi-agent research system (read November 6, 2026)
Why the harness got smaller with each model
A harness, the code around the model, encodes guesses about what the model cannot do alone, and newer models make some of those guesses wrong. Anthropic's Labs team built a three-agent harness for apps that take hours. A planner turns a prompt of one to four sentences into a full spec, and a generator builds it feature by feature. An evaluator clicks through the running app with the Playwright MCP server and fails a sprint when any one score drops below its bar. On a prompt for a 2D retro game maker, a solo agent ran for 20 minutes and the harness with all three agents for six hours.
OpenAI's Codex team kept the same pieces in files instead of agents. In one run, GPT-5.3-Codex at Extra High reasoning worked about 25 hours on a design tool from a blank repo, using about 13M tokens and writing about 30k lines. It followed four Markdown files: a spec with a "Done when" section, a plan of milestones with validation commands, a runbook and a status log. A failed check meant repair before moving on.
Rebuild the harness when you change models. Take out one part at a time and compare results on the same tasks, which the AI evals course shows how to measure.
A lead agent and parallel subagents
The research feature splits one question across workers with clean contexts.
Source: Anthropic Engineering: How we built our multi-agent research system (read November 6, 2026)
Two prompts, the same harness
An initializer sets up the feature list, init.sh and git, and each coding session then adds one feature.
Source: Anthropic Engineering: Effective harnesses for long-running agents (read November 6, 2026)
16 agents, one repository
Agents in a shell loop claim tasks with lock files and write a C compiler together.
Source: Anthropic Engineering: Building a C compiler with a team of parallel Claudes (read November 6, 2026)
Parts come out
Context resets needed for Sonnet 4.5 were dropped with Opus 4.5. Sprints went with Opus 4.6, and the evaluator moved to one pass at the end.
Source: Anthropic Engineering: Harness design for long-running application development (read November 6, 2026)
How Claude Code's creator keeps long tasks running
Boris Cherny created Claude Code and works on Claude at Anthropic. His twelfth tip in a setup thread on X, posted on 2 January 2026, lists three ways he keeps Claude on a long task, quoted below. The second is the one to copy into your own harness: a Stop hook runs when Claude tries to finish, so a check in code decides whether the work is done. The third, the ralph-wiggum plugin he credits to Geoffrey Huntley, now sits in Anthropic's plugin repository as ralph-loop.
Anthropic announced the harness post on 26 November 2025 with the problem this lesson opened on: agents still struggle across many context windows. Its answer came from how human engineers hand over a shift, which is why the steps above are files and commits, not a smarter prompt. The workshop below is from Anthropic engineers on the AI Engineer channel.
I will either (a) prompt Claude to verify its work with a background agent when it's done, (b) use an agent Stop hook to do that more deterministically, or (c) use the ralph-wiggum plugin
Screenshots of X's own embeds of the posts, taken on 6 November 2026, with the time in UTC. Select one to open the post on X. X cuts Boris Cherny's post short with Show more.
Common mistakes
- Writing app code before the feature list exists.
- Keeping the task list in a Markdown file that later sessions rewrite as they please.
- Marking a feature done because it compiles or a curl call returns 200. The quickstart asks for a check through the UI with screenshots.
- Starting new work before rerunning a core test, so a bug from the last session spreads.
- Running a skip-permissions loop outside a container.
- Pouring thousands of lines of test output into the context of the agent that has to read them.
- Adding subagents to a coding task with few parallel parts and paying several times the tokens.
Try it yourself
- Write a five-item
feature_list.jsonfor a small app you know, with steps a browser can follow. - Cut the quickstart's initializer prompt to ten features, run it with
--max-iterations 3and readclaude-progress.txtandgit logafter each session. - Break a passing feature by hand between two sessions. Does the next session catch it before it starts new work?
- Make your test runner print one ERROR line per failure and compare how much of the context a failed run takes before and after.
Check yourself
Why does the first session write a feature list before any app code?
Show answer
A. So a later session cannot call the job done while tests still fail Every item starts with passes set to false, so unfinished work stays visible to each fresh session.
What does a coding session do before it starts a new feature?
Show answer
C. Reads the notes and git log, then reruns a core passing test The last session may have broken something, so the quickstart checks a core feature and fixes it before new work.
In the harness behind the C compiler, how does one of the 16 agents claim a task?
Show answer
B. It writes a text file to current_tasks/ A file such as current_tasks/parse_if_statement.txt acts as the lock on that task.
Which job fits a multi-agent system worst, by Anthropic's research post?
Show answer
D. Coding work where every agent needs the same context Most coding has fewer parallel parts than research, and work that needs one shared context fits multi-agent systems badly today.
Frequently asked questions
What is a long-running agent?
Any agent kept on one goal for longer than a single context window can hold. An app-building coding agent qualifies, and so does a team of agents sharing one repository. Each restart wipes the model’s memory, so what carries over is files and commits.
Is compaction enough to keep an agent on a long task?
Not always. In Anthropic's runs, an older Claude model kept wrapping up early even with compaction, so the team switched to context resets with a written handoff. Files on disk survive any reset, which is why the harness keeps its state there.
How many items should the feature list have?
Enough that each one fits in a single session. The quickstart's count is sized for a whole web app, and its README suggests far fewer for a demo. Split any item that an agent cannot build and check in one context window.
What goes in the progress file?
What the session did, which tests it completed, the issues it found or fixed, what to work on next and how many tests pass out of the total. That is the list the quickstart's coding prompt asks for.
What is the Ralph Wiggum loop?
It feeds an agent the same prompt again each time it stops, an idea from Geoffrey Huntley. In Claude Code the ralph-loop plugin does it with a Stop hook and ends on a completion phrase. Its README says to always set --max-iterations as a safety net.
Sources
- Anthropic Engineering: Effective harnesses for long-running agents https://www.anthropic.com/research/effective-harnesses-for-long-running-agents
- GitHub: anthropics/claude-quickstarts, autonomous-coding README https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding
- GitHub: autonomous-coding initializer prompt https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/prompts/initializer_prompt.md
- GitHub: autonomous-coding coding prompt https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/prompts/coding_prompt.md
- GitHub: autonomous-coding agent.py session loop https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/agent.py
- GitHub: anthropics/claude-agent-sdk-python README https://github.com/anthropics/claude-agent-sdk-python
- Anthropic Engineering: How we built our multi-agent research system https://www.anthropic.com/research/multi-agent-research-system
- Anthropic Engineering: Harness design for long-running application development https://www.anthropic.com/research/harness-design-long-running-apps
- Anthropic Engineering: Building a C compiler with a team of parallel Claudes https://www.anthropic.com/research/building-c-compiler
- Anthropic Research: Measuring AI agent autonomy in practice https://www.anthropic.com/research/measuring-agent-autonomy
- OpenAI Developers: Run long horizon tasks with Codex https://developers.openai.com/blog/run-long-horizon-tasks-with-codex
- GitHub: anthropics/claude-plugins-official, ralph-loop plugin https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop
- X: Boris Cherny on long-running tasks https://x.com/bcherny/status/2007179858435281082
- X: Anthropic shares its post on long-running agent harnesses https://x.com/AnthropicAI/status/1993733817849303409
- YouTube (AI Engineer): Anthropic Workshop, Build Agents That Run for Hours https://www.youtube.com/watch?v=mR-WAvEPRwE