# Long-Running Agents Long-running agents are autonomous AI agents that work across multiple sessions over hours or days to build complex software. Designing harnesses for these agents extends the single-session principles of context engineering, architectural constraints, and entropy management into a multi-session lifecycle where no single session has full memory of what came before. The primary source for this document is Anthropic Engineering's "Effective Harnesses for Long-Running Agents" (Justin Young, November 2025), tested with Claude Agent SDK and Opus 4.5. --- ## The Core Problem A single-session agent starts, does work, and finishes. The human reviews the output. If the task is too large for one session, the human breaks it up and supervises each piece. This is manageable for small features and bug fixes. It does not scale. Complex applications -- full-stack web apps, mobile applications, multi-service backends -- require dozens of features, each building on previous work. No single context window can hold the entire project. And no human wants to manually shepherd every session. The challenge is continuity. Each new agent session starts with no memory of what happened in previous sessions. Imagine a software project staffed by engineers working in shifts, where each new engineer arrives with no memory of what happened on the previous shift. Without a deliberate handoff protocol, every shift wastes time rediscovering context, duplicates work, or contradicts decisions made earlier. Long-running agent patterns solve this by encoding continuity into artifacts rather than relying on memory. --- ## The Two-Part Agent Architecture A long-running agent system splits into two distinct agents with different responsibilities. This separation matters because bootstrapping a project and incrementally building on it are fundamentally different tasks. ### The Initializer Agent The Initializer Agent runs **once**, at the start of the project. Its job is to transform a high-level description ("build a task management app with authentication, drag-and-drop boards, and real-time collaboration") into structured artifacts that all subsequent agents will consume. It produces four outputs: **1. Development environment startup script (`init.sh`)** A shell script that handles all environment setup: installing dependencies, starting development servers, seeding databases, configuring environment variables. This script must be idempotent -- safe to run multiple times without side effects -- because every subsequent session will run it. ```bash #!/bin/bash # init.sh -- idempotent project setup set -euo pipefail dotnet restore dotnet build --no-restore -warnaserror dotnet ef database update --project src/Project.Infrastructure --startup-project src/Project.Web dotnet run --project src/Project.Web --no-build & echo "App running on http://localhost:5000" ``` **2. Granular feature list (`feature_list.json`)** The Initializer Agent expands the high-level requirements into specific, verifiable features. This list is structured as JSON, not Markdown, for a critical reason: **the model is less likely to inappropriately change or overwrite JSON files compared to Markdown**. Markdown's freeform nature invites editing. JSON's rigid structure resists it. ```json [ { "category": "Authentication", "feature": "User registration with email and password", "verification": [ "Navigate to /register", "Fill in valid email and password", "Submit form", "Verify redirect to /dashboard", "Verify user record exists in database" ], "passes": false }, { "category": "Authentication", "feature": "User login with session persistence", "verification": [ "Navigate to /login", "Enter valid credentials", "Submit form", "Verify session cookie is set", "Refresh page and verify user is still logged in" ], "passes": false } ] ``` Each feature has a category, a description, explicit verification steps, and a `passes` field. Coding agents may **only** modify the `passes` field. The requirements themselves are read-only. This is a hard constraint: > It is unacceptable to remove or edit tests because this could lead to missing > or buggy functionality. **3. Progress tracking file (`claude-progress.txt`)** A plain-text file that records what has been accomplished, what is next, and any blockers. This file is written for the **next agent**, not for humans. It is the primary handoff artifact between sessions. ``` ## Session 1 -- 2025-11-15 Status: COMPLETE ### Accomplished - Project scaffolding: ASP.NET Core 8 + Blazor Server, Tailwind CSS, EF Core 8 with Azure SQL - Database schema: users, boards, columns, cards tables - Basic layout: header, sidebar, main content area ### Next Priority - User registration (Authentication category, feature 1) ### Blockers - None ### Overall Progress - 3 of 24 features complete (12.5%) ``` **4. Initial git commit** The Initializer Agent commits all generated artifacts. This establishes the baseline from which all subsequent work proceeds. The commit message should clearly indicate this is the project bootstrap. ### The Coding Agent The Coding Agent runs in **every subsequent session**. It is a different agent (or the same agent with different instructions) that follows a rigid protocol: 1. Work on **one feature** per session. 2. Follow the session lifecycle (described below). 3. Leave the codebase in a clean, mergeable state. 4. Update the progress file. 5. Never attempt to build the entire project at once. The Coding Agent is deliberately constrained. It does not redesign the feature list. It does not reorganize the project structure. It picks up the next feature, implements it, verifies it, documents it, and stops. --- ## The Session Lifecycle Protocol Every Coding Agent session follows the same sequence. This is not a suggestion. It is the protocol that makes multi-session work reliable. ### Session Start Every session begins with orientation. The agent must understand the current state of the project before touching any code. ``` 1. Verify working directory (pwd) 2. Read the progress file (claude-progress.txt) 3. Read the feature list (feature_list.json) 4. Check git log for recent commits and their messages 5. Run the startup script (./init.sh) 6. Health check: verify the app starts and existing features work 7. Select ONE feature to implement 8. Begin work ``` Steps 1-6 are non-negotiable. Step 6 -- the health check -- is especially important. If the app is broken from a previous session, the current session must fix it before adding new work. Building on a broken foundation guarantees compounding failures. ### Session End Every session ends with closure. The agent must leave the project in a state that the next session can pick up without guesswork. ``` 1. Verify the implemented feature works (run tests, take screenshots, manual check) 2. Run the full verification suite (all tests, linter, type checker) 3. Commit with a descriptive message summarizing what was done 4. Update the progress file: what was completed, what is next, any blockers 5. Leave codebase in clean, mergeable state ``` Step 5 is the critical discipline. No half-implemented features. No broken tests. No uncommitted changes. The next agent should be able to run the startup script and immediately begin productive work. ### Between Sessions Continuity between sessions is artifact-based, not memory-based: | Artifact | What It Provides | |----------|-----------------| | Progress file | Human-readable context: what happened, what is next | | Git history | Machine-readable context: what changed, when, why | | Feature list | Structured scope: what is done, what remains | | Startup script | Reproducible environment: no setup guesswork | No single artifact is sufficient. Together, they give the next agent everything it needs to orient itself in under a minute. --- ## Why Compaction Alone Is Not Sufficient Most agent tools include some form of context compaction -- summarizing earlier parts of the conversation to free up context window space. This is useful within a session but insufficient across sessions. The problem is that compaction optimizes for **token efficiency**, not for **task continuity**. A compacted summary might say "implemented authentication" without specifying which authentication features were completed, which were skipped, what decisions were made, or what the next step should be. The next session's agent receives a vague summary and must rediscover specifics from the codebase itself. Explicit artifact-based bridging solves this: - **Progress files** are written specifically for the next session's agent, with concrete details about what was done and what comes next. - **Git commits** mark meaningful progress boundaries with descriptive messages. - **The feature list** provides structured, incorruptible scope tracking that cannot be accidentally summarized away. The correct approach is to combine both: artifacts for cross-session continuity, compaction for within-session efficiency. Compaction keeps the current session manageable. Artifacts ensure no information is lost when the session ends. --- ## One Feature Per Session: The Critical Constraint This is the single most important rule for long-running agents: > Each session implements ONE feature, verifies it, commits it, documents it, > and stops. ### Why This Constraint Exists Context windows are finite. A complex feature -- implementing drag-and-drop on a Kanban board, for example -- might require reading a dozen source files, writing several new files, running tests, debugging failures, and verifying the result. This work consumes a significant portion of the context window. Attempting two or three features in the same session risks **context exhaustion**: the agent reaches the end of its context window mid-implementation, loses track of earlier decisions, and produces inconsistent or broken code. ### What Happens Without It Without the one-feature constraint, agents fall into **one-shotting**: attempting to build the entire application in a single session. The pattern is predictable: 1. The agent starts strong, implementing the first few features quickly. 2. Context fills up. The agent begins losing track of earlier work. 3. Later features conflict with earlier ones. Tests break. 4. The session ends with a partially implemented, undocumented mess. 5. The next session cannot determine what was completed and what was abandoned. One-shotting is the multi-session equivalent of the single-session anti-pattern where the agent writes 2,000 lines of code before running any verification. The principle is the same: **corrections are cheap, waiting is expensive**. ### The Discipline When the agent finishes its one feature, it must stop -- even if context window space remains. The remaining space is better used for thorough verification and documentation than for starting another feature that might not be completed. --- ## Artifact Design The quality of the artifacts determines the quality of the multi-session workflow. Poorly designed artifacts produce the same confusion as no artifacts at all. ### Progress File The progress file (`claude-progress.txt` or `docs/progress.md`) is updated at the end of every session. It is the first file the next agent reads. **Design principles:** - **Written for the next agent, not for humans.** Assume the reader has zero context about what happened. Be specific: "Implemented user registration with bcrypt password hashing and email validation via regex" is useful. "Worked on auth" is not. - **Include the session number and date.** This helps the agent gauge project velocity and recency of changes. - **State what is next explicitly.** Do not leave the next agent to figure out priorities. Name the specific feature from the feature list. - **Record blockers.** If something could not be resolved -- a missing API key, an unclear requirement, a dependency conflict -- document it so the next session does not repeat the investigation. - **Keep it concise.** The progress file should be readable in 30 seconds. The next agent will read this before every session. ### Feature List The feature list (`feature_list.json`) is the structured specification for the entire project. It is created once by the Initializer Agent and treated as read-only by all Coding Agents (except for the `passes` field). **Why JSON over Markdown:** Markdown is freeform text. An agent working late in a session, with context running low, might "simplify" a Markdown specification by removing details or rewording requirements to match its implementation rather than the original intent. JSON's rigid structure makes this kind of drift far less likely. The agent sees structured data and treats it as data, not as prose to be edited. **Schema design:** ```json { "category": "string -- functional grouping", "feature": "string -- specific, implementable description", "verification": ["array of concrete steps to verify the feature works"], "passes": "boolean -- ONLY field agents may modify" } ``` **The read-only constraint:** Agents must not edit the `category`, `feature`, or `verification` fields. If an implementation does not match the specification, the implementation is wrong -- not the specification. This prevents a common failure mode where the agent quietly weakens requirements to declare premature success. ### Startup Script The startup script (`init.sh`) eliminates environment setup as a source of session overhead. Without it, every session wastes tokens on "how do I start this project?" -- installing packages, starting servers, running migrations. **Design principles:** - **Idempotent.** Running it twice must not break anything. Use guards: `npm install` is naturally idempotent; `createdb` is not (check if the database exists first). - **Fast.** The script should complete in under 30 seconds. Use `--silent` flags and skip unnecessary steps. - **Self-documenting.** Echo what each step does so the agent (and humans reviewing logs) can see the setup process. - **Error-handling.** Use `set -euo pipefail` so failures are loud and immediate, not silent and cascading. ### Git as State Machine In a long-running agent workflow, git commits are not just version control. They are **deliberate progress boundaries** that serve multiple purposes: - **Session summaries.** A descriptive commit message ("Implement user registration with bcrypt hashing, email validation, and session creation") tells the next agent exactly what changed without reading the diff. - **Rollback points.** If a session introduces a bug, the next session can revert to the previous commit and try again without losing all prior work. - **Project timeline.** The git log becomes a machine-readable history of the project's evolution, ordered by session. Commit messages should be written as if the reader is an agent that has never seen the project before. "Fix stuff" is useless. "Fix drag-and-drop z-index issue where cards appeared behind the sidebar on narrow viewports" is useful. --- ## Anti-Patterns for Long-Running Agents ### 1. One-Shotting Attempting to build the entire project in one session. Context exhaustion guarantees that later features will be poorly implemented, untested, and undocumented. The one-feature-per-session constraint exists specifically to prevent this. ### 2. Premature Victory Declaration Declaring the project "done" after implementing some features while others remain incomplete. This often happens when the agent checks the feature list, sees that many features pass, and concludes the project is finished -- without verifying the remaining features or checking for gaps. ### 3. Premature Feature Marking Marking features as `"passes": true` in the feature list without actually running the verification steps end-to-end. The agent assumes its implementation is correct and skips testing. Later sessions discover the feature is broken but trust the `passes` flag and move on. ### 4. Specification Overwriting Editing the `feature` or `verification` fields in the feature list to match a broken implementation. Instead of fixing the code to meet the spec, the agent fixes the spec to match the code. This silently weakens the project's requirements and produces software that does not meet the original intent. ### 5. Skipping Health Checks Starting new feature work without verifying that the application still works from the previous session. A bug introduced in session 5 that is not caught until session 8 is far harder to fix than one caught at the start of session 6. ### 6. Relying on Compaction Alone Expecting the agent tool's built-in context management to handle multi-session continuity. Compaction works within a session. It does not work across sessions. Without explicit artifacts, each session starts from scratch. --- ## Verification in Long-Running Projects Verification becomes more important -- and more complex -- as the project grows across sessions. ### End-to-End Testing Unit tests are necessary but not sufficient. A feature that passes its unit tests may still fail in the context of the full application because of integration issues, CSS conflicts, state management bugs, or API mismatches. End-to-end tests verify that the feature works as a user would experience it: - **Browser automation** (Puppeteer, Playwright, Chrome DevTools Protocol) for web applications. - **API integration tests** that exercise the full request-response cycle. - **Screenshot-based verification** that captures the visual state of the UI. ### Screenshot Verification Screenshot-based verification dramatically improves bug detection for frontend work. An agent that can see the rendered UI catches layout issues, missing elements, and visual regressions that text-based tests miss entirely. However, there are known limitations. Vision models may not reliably detect certain UI elements -- browser-native modals (alert, confirm, prompt dialogs), subtle color differences, or elements that require scrolling to reveal. The harness should not rely on screenshot verification alone for these cases. ### Session Verification Scope Each session should verify two things: 1. **Previous work still functions.** Run the existing test suite before making changes. If something is broken, fix it before proceeding. 2. **New feature works.** Run the new feature's verification steps and the full test suite after implementation. This dual verification prevents both regression (old things breaking) and false progress (new things not actually working). --- ## When to Use Long-Running Agent Patterns ### Use When - The project spans multiple days or sessions. - The feature count exceeds what one session can handle (generally more than 3-5 substantial features). - The application has many interdependent features where order of implementation matters. - The goal is autonomous operation with minimal human intervention between sessions. ### Do Not Use When - The task is a single-session job: a bug fix, a small feature, a refactor. - A human is actively supervising each session and providing continuity manually. - The task can be completed in under two hours of agent work. - The project is simple enough that one-shotting would actually work (a static site, a CLI tool with three commands, a single API endpoint). The overhead of setting up the two-part architecture, feature list, progress file, and startup script is not justified for small tasks. These patterns exist for projects where the cost of lost continuity exceeds the cost of the infrastructure. --- ## Relationship to Other Harness Concepts Long-running agent patterns are not new ideas. They are existing harness engineering principles applied across sessions rather than within a single one. **Context Engineering.** The progress file, feature list, and git history are context engineering artifacts. They answer the same question -- "what does the agent need to know?" -- but scoped to the cross-session boundary rather than the within-session task. See [Context Engineering](context-engineering.md). **Entropy Management.** Every session that ends with uncommitted changes, undocumented decisions, or broken tests introduces entropy that compounds across subsequent sessions. The session lifecycle protocol is entropy management applied to the workflow itself. See [Entropy Management](entropy-management.md). **Specification-Driven Development.** The feature list is a specification. Each session is an execution against that specification. The read-only constraint on requirements prevents specification drift, which is the multi-session equivalent of scope creep. See [SDD](sdd.md). **Architectural Constraints.** The one-feature-per-session rule is an architectural constraint on the workflow, not on the code. It limits the blast radius of any single session and ensures that progress is always incremental and verifiable. See [Architectural Constraints](architectural-constraints.md). --- ## Summary | Concept | Single-Session | Multi-Session | |---------|---------------|--------------| | Context source | .github/copilot-instructions.md + repository | Progress file + feature list + git log | | Scope | Defined by human in the prompt | Defined by feature list, one per session | | Verification | Run tests, check output | Health check on start + full verification on end | | Continuity | Human memory | Artifacts: progress file, git commits, feature list | | Entropy control | Clean code, good tests | Clean-state protocol at session boundaries | | Failure recovery | Human intervenes | Next session detects and fixes via health check | The fundamental insight is simple: **if the agent cannot remember, make the repository remember for it.** Every artifact -- the progress file, the feature list, the git history, the startup script -- exists to encode information that would otherwise be lost between sessions. The protocol exists to ensure that information is consistently written and consistently read. --- ## Attribution This document draws primarily from "Effective Harnesses for Long-Running Agents" by Justin Young at Anthropic Engineering (November 2025), tested and validated using Claude Agent SDK with Opus 4.5. The patterns described here extend the foundational agent design principles from Anthropic's "Building effective agents" (2024). --- ## Further Reading - [What Is Harness Engineering?](what-is-harness-copilot.md) -- The three pillars overview. - [Context Engineering](context-engineering.md) -- Deep dive into the first pillar. - [Architectural Constraints](architectural-constraints.md) -- Deep dive into the second pillar. - [Entropy Management](entropy-management.md) -- Deep dive into the third pillar. - [Anti-Patterns](anti-patterns.md) -- Common mistakes across all harness dimensions. - [SDD](sdd.md) -- Specification-Driven Development.