Externalized State

Store an agent’s plan, progress, and intermediate results in inspectable files so that workflows survive interruptions and humans can see what the agent intends to do, not just what it has done.

Understand This First

• Agent – agents are stateless between sessions; externalized state compensates.
• Plan Mode – the plan is the most common artifact to externalize.
• Checkpoint – checkpoints save state at verification gates.

Context

This is an agentic pattern. You’re directing an agent through a multi-step workflow: a migration, a feature build, a documentation overhaul. The agent holds its intentions and intermediate results in the context window — a space that is invisible to you, volatile, and bounded. If the session crashes, the window closes, or the context fills up and gets compacted, that internal state vanishes. You’re left guessing where the agent was and what it planned to do next.

Externalized state solves this by moving the agent’s working state out of its head and into files you can read, edit, and version-control. The plan becomes a document. Progress becomes a checklist. Intermediate results become artifacts on disk. The work becomes inspectable at every stage, not just at the end.

Problem

How do you make an agent’s intentions, progress, and intermediate results visible and durable when the context window is opaque, volatile, and finite?

An agent working through a twelve-step migration holds its mental model of which steps are done, which are in progress, and which remain. That model lives in the context window. If the session ends — because the window fills up, the API times out, or the developer closes the laptop — the mental model disappears. The next session starts from zero, and the agent has no way to know what was already accomplished unless someone tells it.

The same problem appears in team workflows. A second developer picks up where the first left off, but the first developer’s agent held all the context internally. The handoff is a conversation: “I think it finished the first three steps, maybe four.” That’s not engineering. That’s guesswork.

Forces

• Agent context windows are bounded and volatile. Long workflows exceed them.
• Invisible state can’t be reviewed, corrected, or audited. You can’t fix a plan you can’t see.
• Resuming from a crash or timeout requires knowing exactly where the work stopped and what intermediate results exist.
• Writing state to disk takes tokens and time. Not every piece of internal state is worth externalizing.
• Multiple agents or humans working on the same project need a shared understanding of what’s been done and what remains.

Solution

Write the agent’s working state to files in the project repository. The state includes three categories of information, each serving a different purpose.

The plan. A document listing what the agent intends to do, in what order, with dependencies between steps. This is the agent’s to-do list, written before it starts working. It can be as simple as a numbered list in a markdown file or as structured as a task graph with status fields. The plan separates intent from execution — you can review what the agent plans to do before it does it.

Progress markers. As the agent completes each step, it updates the plan to reflect what’s done, what’s in progress, and what remains. This turns the plan from a static document into a living tracker. A checkpoint that passes becomes a progress marker. A step that fails gets annotated with what went wrong.

Intermediate artifacts. Results that the agent produces along the way — generated code waiting for review, analysis reports, extracted data, partial configurations. These artifacts live on disk where they can be inspected, tested, and used as inputs to later steps. If the workflow restarts, the agent doesn’t need to regenerate work that already exists.

The pattern works because files are durable, inspectable, and shareable. They survive session boundaries. They can be version-controlled with git. They can be read by other agents, other developers, or automated systems. They turn an opaque process into a transparent one.

In practice, the implementation is straightforward. At the start of a workflow, instruct the agent to write a plan file. At each stage, have it update the plan with status. At key points, have it write intermediate outputs to disk rather than holding them in context. Hooks can automate the state-writing, triggering plan updates at session boundaries or after each completed step.

How It Plays Out

A developer asks an agent to migrate a REST API from Express to Fastify across fourteen endpoints. The agent writes MIGRATION_PLAN.md listing each endpoint, its current test status, and the migration order (least-coupled endpoints first). As it works, it checks off completed endpoints and notes any that required unexpected changes. After nine endpoints, the developer’s laptop runs out of battery. The next morning, a new session reads MIGRATION_PLAN.md, sees that nine of fourteen endpoints are done, and picks up at endpoint ten. The intermediate artifacts — the already-migrated files — are on disk and passing tests. No work is lost, and no work is repeated.

A team of three developers splits a large refactoring project among their agents. Each agent works in its own worktree, but they share a STATE.json file in the main branch that tracks which modules have been claimed, which are in progress, and which are complete. When Developer B’s agent finishes its batch and looks for more work, it reads the state file, sees three unclaimed modules, and picks one up. The state file is the coordination mechanism, visible to every agent and every human on the team.

An agent building a data pipeline writes each stage’s output to a staging/ directory: extracted CSVs, cleaned DataFrames serialized as Parquet files, validation reports. When stage four fails because of a schema mismatch in the source data, the developer can inspect the stage-three output directly, diagnose the problem, and fix the source configuration. The agent resumes from stage four using the existing stage-three artifacts. Without externalized intermediate results, the developer would have to rerun stages one through three just to see what data stage four received.

Consequences

Externalized state transforms agent workflows from opaque, single-session processes into transparent, resumable, auditable operations. Workflows can survive crashes, timeouts, and context window exhaustion. Handoffs between sessions, agents, or developers become reliable because the state is a shared artifact rather than a verbal summary.

The cost is overhead. Writing state to disk takes tokens, and maintaining a plan file adds steps to every stage of the workflow. For short, single-session tasks, the overhead isn’t worth it. The pattern earns its keep on workflows that span multiple sessions, involve multiple collaborators, or carry enough risk that you need an audit trail. A five-minute fix doesn’t need a plan file. A two-week migration does.

There’s also a fidelity risk. If the agent stops updating the plan, or updates it inaccurately, the externalized state becomes misleading. Stale state is worse than no state because it creates false confidence. The remedy is the same as for any shared document: treat state updates as part of the work, not an afterthought, and verify the state file against reality at the start of each session.

Related Patterns

• Depends on: Agent – agents are stateless between sessions; externalized state compensates.
• Depends on: Plan Mode – the plan is the most common artifact to externalize.
• Uses: Checkpoint – checkpoints save state at verification gates; externalized state is where that state gets written.
• Complements: Progress Log – a progress log records what happened; externalized state tracks what’s planned, what’s in progress, and what remains.
• Contrasts with: Memory – memory persists learnings across sessions; externalized state persists workflow state within a single multi-session effort.
• Uses: Hook – hooks can automate state-writing at session boundaries or stage completions.
• Enables: Worktree Isolation – shared externalized state coordinates multiple agents working in separate worktrees.
• Informed by: Source of Truth – the externalized state file is the source of truth for workflow progress.

Sources

The Hugging Face agentic coding implementation guide (2026) formalized the principle that no long-running agent should operate without an explicit plan object. Their framework requires agents to post intermediate artifacts to a shared store, with coordinators merging results — establishing externalized state as an infrastructure requirement rather than a nice-to-have.

LangGraph’s checkpointing system (LangChain, 2024-2025) implemented externalized state at the framework level, writing workflow snapshots to persistent storage after every node in the execution graph. This made pause, resume, replay, and human-in-the-loop review possible without any custom state management.

The plan-as-artifact pattern appears across multiple agentic coding tools shipping in 2025-2026: AWS Kiro enforces a three-phase plan (requirements, design, tasks) that persists as files in the project; GitHub’s Spec Kit treats the spec as a living document that agents update as they work; Anthropic’s Claude Code uses CLAUDE.md and progress files as externalized project context that loads automatically at session start.