# Long-running agents: keep one task going across many sessions

> A long-running agent works on one task across many context windows, each session starting with no memory of the last. The harness carries the state: a spec, a feature list with a pass flag per item, a progress file and git history. Each session reads them, finishes one feature, tests it end to end, commits and updates the notes.

Mindket editors · Published 2026-11-06 · Updated 2026-11-06 · https://mindket.com/learn/harness-engineering/long-running-agents

## In short

- Write the whole job down as checkable items before any code exists.
- Make each fresh session read the notes and rerun a core test before it touches new work.
- Let a script restart the agent, and give parallel agents a file to claim tasks with.
- Add agents only where the work splits cleanly, since a multi-agent system uses about 15 times the tokens of a chat.

## 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](https://www.anthropic.com/research/effective-harnesses-for-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](https://www.anthropic.com/research/measuring-agent-autonomy), 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](https://mindket.com/learn/harness-engineering/what-is-an-agent-harness) and the tool design of lesson 2. Compaction, memory files and context editing keep one session going, and [agent memory](https://mindket.com/learn/context-engineering/agent-memory) teaches them. Here the problem is the gap between sessions.

The worked example is Anthropic's [autonomous-coding quickstart](https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding), an agent harness in Python on the Claude Agent SDK. It needs the [Claude Code CLI](https://code.claude.com/docs/en/setup), 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](https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/prompts/initializer_prompt.md). Anthropic chose JSON because the model was less likely to change or overwrite a JSON file than a Markdown one.

````json
[
  {
    "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
  }
]
````

1. Put the spec in `app_spec.txt` and tell the initializer to read it before anything else.
2. Have it write `feature_list.json` from 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.
3. 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`.
4. Have it write `init.sh`, which installs dependencies and starts the dev server, so no later session spends context working that out.
5. Make the first git commit with the list, the script and a README, then write `claude-progress.txt` before 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](https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/prompts/coding_prompt.md).

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](https://www.anthropic.com/research/effective-harnesses-for-long-running-agents) 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.

````bash
# 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](https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/agent.py). 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](https://www.anthropic.com/research/building-c-compiler), 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](https://mindket.com/learn/harness-engineering/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:

````bash
#!/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 as `current_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 `--fast` option 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](https://www.anthropic.com/research/multi-agent-research-system), 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.

**Tokens a task uses, compared with one chat** Approximate multiples as Anthropic states them for its own systems.

- A chat: 1×
- An agent: 4×
- A multi-agent system: 15×

Source: [Anthropic Engineering: How we built our multi-agent research system](https://www.anthropic.com/research/multi-agent-research-system) (read 2026-11-06)

## 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](https://www.anthropic.com/research/harness-design-long-running-apps) 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](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex), 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](https://mindket.com/learn/ai-evals/what-are-llm-evals) shows how to measure.

**How Anthropic's harness design changed**

1. **June 13, 2025** A lead agent and parallel subagents. The research feature splits one question across workers with clean contexts.
2. **November 26, 2025** Two prompts, the same harness. An initializer sets up the feature list, init.sh and git, and each coding session then adds one feature.
3. **February 5, 2026** 16 agents, one repository. Agents in a shell loop claim tasks with lock files and write a C compiler together.
4. **March 24, 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.

Sources: [Anthropic Engineering: How we built our multi-agent research system](https://www.anthropic.com/research/multi-agent-research-system) (read 2026-11-06), [Anthropic Engineering: Effective harnesses for long-running agents](https://www.anthropic.com/research/effective-harnesses-for-long-running-agents) (read 2026-11-06), [Anthropic Engineering: Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/research/building-c-compiler) (read 2026-11-06), [Anthropic Engineering: Harness design for long-running application development](https://www.anthropic.com/research/harness-design-long-running-apps) (read 2026-11-06)

## 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](https://x.com/bcherny/status/2007179858435281082), 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](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop).

Anthropic [announced the harness post](https://x.com/AnthropicAI/status/1993733817849303409) 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
>
> Boris Cherny, Created Claude Code, works on Claude at Anthropic, [X](https://x.com/bcherny/status/2007179858435281082) (read 2026-11-06)

[![Boris Cherny (@bcherny) on X, 2 January 2026, tip 12 of his setup thread. For the longest tasks he has Claude check its work with a background agent when done, uses an agent Stop hook to do that more deterministically, or uses the ralph-wiggum plugin. He credits the plugin to Geoffrey Huntley.](https://mindket.com/blog/shots/x-bcherny-long-running-tasks.webp?v=986970e2bae1)](https://x.com/bcherny/status/2007179858435281082)

Boris Cherny on X, 2 January 2026

[![Anthropic (@AnthropicAI) on X, 26 November 2025: New on the Anthropic Engineering Blog. Long-running AI agents still face challenges working across many context windows. We looked to human engineers for inspiration in creating a more effective agent harness.](https://mindket.com/blog/shots/x-anthropicai-long-running-harness.webp?v=20627805a55d)](https://x.com/AnthropicAI/status/1993733817849303409)

Anthropic on X, 26 November 2025

[Anthropic Workshop: Build Agents That Run for Hours, Ash Prabaker and Andrew Wilson](https://www.youtube.com/watch?v=mR-WAvEPRwE)

Ash Prabaker and Andrew Wilson on the AI Engineer YouTube channel, in an Anthropic workshop titled Build Agents That Run for Hours.

> 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.json` for 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 3` and read `claude-progress.txt` and `git log` after 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

1. Why does the first session write a feature list before any app code?

   A. So a later session cannot call the job done while tests still fail
   B. Because the Agent SDK needs the file to start
   C. To make the context window larger
   D. So the agent can skip end-to-end checks

   Answer: A. Every item starts with passes set to false, so unfinished work stays visible to each fresh session.

2. What does a coding session do before it starts a new feature?

   A. Deletes the progress file
   B. Writes a new feature list
   C. Reads the notes and git log, then reruns a core passing test
   D. Asks the user for the spec again

   Answer: C. The last session may have broken something, so the quickstart checks a core feature and fixes it before new work.

3. In the harness behind the C compiler, how does one of the 16 agents claim a task?

   A. It asks a lead agent for one
   B. It writes a text file to current_tasks/
   C. It opens a pull request
   D. It edits the feature list

   Answer: B. A file such as current_tasks/parse_if_statement.txt acts as the lock on that task.

4. Which job fits a multi-agent system worst, by Anthropic's research post?

   A. A broad research question
   B. Searches that can run side by side
   C. A survey of many separate sources
   D. Coding work where every agent needs the same context

   Answer: D. 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) (read 2026-11-06)
- [GitHub: anthropics/claude-quickstarts, autonomous-coding README](https://github.com/anthropics/claude-quickstarts/tree/main/autonomous-coding) (read 2026-11-06)
- [GitHub: autonomous-coding initializer prompt](https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/prompts/initializer_prompt.md) (read 2026-11-06)
- [GitHub: autonomous-coding coding prompt](https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/prompts/coding_prompt.md) (read 2026-11-06)
- [GitHub: autonomous-coding agent.py session loop](https://github.com/anthropics/claude-quickstarts/blob/main/autonomous-coding/agent.py) (read 2026-11-06)
- [GitHub: anthropics/claude-agent-sdk-python README](https://github.com/anthropics/claude-agent-sdk-python) (read 2026-11-06)
- [Anthropic Engineering: How we built our multi-agent research system](https://www.anthropic.com/research/multi-agent-research-system) (read 2026-11-06)
- [Anthropic Engineering: Harness design for long-running application development](https://www.anthropic.com/research/harness-design-long-running-apps) (read 2026-11-06)
- [Anthropic Engineering: Building a C compiler with a team of parallel Claudes](https://www.anthropic.com/research/building-c-compiler) (read 2026-11-06)
- [Anthropic Research: Measuring AI agent autonomy in practice](https://www.anthropic.com/research/measuring-agent-autonomy) (read 2026-11-06)
- [OpenAI Developers: Run long horizon tasks with Codex](https://developers.openai.com/blog/run-long-horizon-tasks-with-codex) (read 2026-11-06)
- [GitHub: anthropics/claude-plugins-official, ralph-loop plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-loop) (read 2026-11-06)
- [X: Boris Cherny on long-running tasks](https://x.com/bcherny/status/2007179858435281082) (read 2026-11-06)
- [X: Anthropic shares its post on long-running agent harnesses](https://x.com/AnthropicAI/status/1993733817849303409) (read 2026-11-06)
- [YouTube (AI Engineer): Anthropic Workshop, Build Agents That Run for Hours](https://www.youtube.com/watch?v=mR-WAvEPRwE) (read 2026-11-06)

[Browse AI agents](https://mindket.com/agents)