Introduction to Pi Durable: Building Agents That Survive Crashes and Run for Hours
Welcome to the Series
This is the first article in a comprehensive tutorial series that will take you from zero knowledge of Pi Durable to building production-grade, long-running AI agents.
By the end of this series you will understand how to create agents that:
Survive process crashes, restarts, and redeploys
Run for hours, days, or months without babysitting
Support multiple concurrent conversations
Allow multiple people (or clients) to watch and steer the same agent
Keep full application state alongside the conversation transcript
This first article focuses purely on introduction and mental models. We will not write production code yet. The goal is to understand why Pi Durable exists and what it actually does.
The Problem Traditional Agents Have
Most AI agents today are ephemeral.
You start a process (CLI, server, or serverless function). The agent talks to a model, calls tools, and maintains its state in memory. The moment the process dies — whether from a crash, a deployment, a laptop going to sleep, or a serverless timeout — everything is gone:
The conversation history may be partially saved
In-flight tool calls are lost or left in an inconsistent state
Queued user messages disappear
Application-level state (what the agent was trying to accomplish) is gone
You can often /resume a chat transcript, but resuming a transcript is not the same as resuming the work. The system does not know:
Which tool was running when the process died
Whether that tool already changed something in the real world
What messages were queued behind it
What the application believed was true at that moment
For interactive coding sessions where a human is watching, this is acceptable. For agents that should keep working while you sleep, handle on-call incidents, serve multiple customers, or run overnight research, it is not.
What Is Pi Durable?
Pi Durable is an experimental durable agent harness created by Earendil (the team behind the Pi coding agent).
It was released on October 1, 2026, the same day as Pi 1.0.
A harness = storage + the machinery needed to run one or more conversations with large language models in parallel.
Pi Durable is not a replacement for the Pi coding agent. The Pi coding agent remains a focused, single-user terminal tool. Pi Durable is a separate library/framework for building any kind of agentic application that needs durability.
It shares code (especially the pi-ai model layer) and philosophy (minimalism + malleability) with the Pi coding agent.
The Core Promise
Conversations, model turns, tool calls, and your own application state are committed to storage before anything is shown.
If the process dies mid-turn, reopening the same storage picks the work up where it stopped.
Key Concepts
Understanding these terms early will make the rest of the series much clearer.
Concept | What it is |
|---|---|
Harness | One open storage backend + the runtime that runs agents on it. All changes go through atomic commits. Nothing is shown until it is stored. |
Conversation | An immutable transcript of entries. You can have many concurrent conversations in one harness. |
Entry | One immutable record in the transcript (user message, assistant response, tool result, system prompt change, etc.). |
Task | A durable state machine. Every model call, tool call, and custom piece of work is a task. Tasks checkpoint before they move forward. |
Checkpoint | The saved progress of a task. On restart, unfinished tasks resume from their last checkpoint. |
Document | Typed JSON application state stored next to the transcript (agent config, inbox, live work, usage, your own data). |
Commit | An atomic write that can append entries, update documents, and create tasks together. All or nothing. |
Submission | Input you hand to a conversation (user message or entry). You can wait for it to be answered. |
Extension | A pluggable bundle of tools, system prompt sections, hooks, and tasks. |
Registry | Where extensions are installed. Conversations choose which ones to use. |
How Recovery Works
Every step (model request, tool call, custom task) is a task.
The task stores a checkpoint before proceeding.
If the process dies, a new process opens the same storage.
It finds unfinished tasks and continues each from its last checkpoint.
Tools can declare whether they are replay-safe. Replay-safe tools can be re-run. Non-replay-safe tools are reported as interrupted instead of being repeated.
Partial model responses that were cut off are kept in the transcript and marked as aborted.
Pi Coding Agent vs Pi Durable
Aspect | Pi Coding Agent | Pi Durable |
|---|---|---|
Primary use | Interactive coding in a terminal | Any long-running agent application |
Driver | One person in one terminal | Any number of clients |
Crash recovery | Manual (continue) | Automatic from checkpoints |
Storage | Session files | Memory, SQLite, JSONL, or custom |
Concurrent conversations | Limited | First-class |
Multi-client | No | Yes (same agent, many clients) |
Runs for | Minutes to hours (while you watch) | Hours, days, months |
Status | Stable (1.0) | Experimental |
Both are MIT-licensed and live in the earendil-works/pi monorepo.
Core Features That Matter
Crash resilience — Unfinished work resumes automatically.
Multiple concurrent conversations — One harness can run many independent agents at once.
Conversation forking — Start a new conversation from any point in an existing transcript (history is shared, not copied).
Multi-client access — Several people or systems can attach to the same run.
Exactly-once input — Use a requestId so retries do not create duplicate work.
Flexible storage — Memory (for tests), SQLite, JSONL. SQLite and JSONL avoid Node-specific APIs so they can run on Bun or inside Cloudflare Durable Objects.
Custom execution environments — Tools can run on your machine, a remote VM, or a sandbox.
Extensions — Add tools, system prompt sections, hooks, and custom tasks.
Subagents — Child conversations owned by a parent task.
Malleability — The entire source is ~15,000 lines. Your own agent can read and reason about it.
Who Is This For?
Pi Durable is useful when you want to build:
Overnight research or investigation agents
On-call / incident response bots
Support agents that handle multiple customers
Multi-person collaborative agents
Agents that run on serverless or edge platforms (Cloudflare, etc.)
Proactive agents that start work from external events
Any agent that must survive process death
It is less necessary for short, interactive, single-user terminal sessions — that is still the job of the regular Pi coding agent.
A Tiny Mental Model
Think of a Pi Durable harness like a durable workflow engine specialized for LLM agents:
Storage (SQLite / JSONL / Memory)
↓
Harness (owns the storage)
↓
Conversations (transcripts + agent config)
↓
Tasks (model calls, tool calls, your work)
↓
Checkpoints (saved after every step)Clients never see uncommitted state. A new process simply reopens the storage and continues.
Installation Preview
You do not need to install anything yet, but when you are ready the core packages are:
npm install @earendil-works/pi-durable @earendil-works/pi-ai @earendil-works/chordThe package is experimental. Pin versions and expect the API to evolve.
What Comes Next in This Series
In the upcoming articles we will go from zero to hero:
This article — Mental models and why it exists
Setting up a project and running your first durable conversation
Persistence: SQLite, crash recovery, and resume()
Tools, extensions, and replay safety
Multiple conversations and forking
Application state with documents
Subagents and task ownership
Multi-client access and steering
Deployment patterns (Node, Cloudflare Durable Objects, Rivet, etc.)
Building a real proactive agent end-to-end
Official Resources
GitHub repository (see packages/durable)
Package: @earendil-works/pi-durable
Related: Pi coding agent, Cloudflare Agents SDK (PiHarness), Rivet Actors
Next article: Setting Up Your First Pi Durable Project and Running a Simple Conversation.
You now have the mental model. Everything that follows builds on these concepts.
Welcome to durable agents.
Get new posts by Nelson Lin
Subscribe to receive email notifications when a new article is published.