Durable State

durable-state

The problem this solves: you kick off a long run — an overnight content batch, a big client audit, a job that spans a whole afternoon — and then the laptop sleeps, the app crashes, the session context fills up and resets, or you have to switch machines. The work is in the chat window, so when the window dies, the work dies with it. You come back to nothing, and you don't even know how far it got.

This skill fixes that by moving the run's memory out of the chat and onto disk. A run gets its own small folder of plain files. If anything interrupts it, the agent (or you) reopens the folder, reads three files, and picks up exactly where it left off — on the same machine or a different one. Nothing is lost, and you can always see what happened, in order.

Think of it like a save file for a long job. You don't hold your progress in your head across a whole workday; you write it down. This does the same thing for your agent.

This is the memory half of always-on. The night-shift skill is the contract that bounds an unattended run (time box, read-only-by-default, a failure ledger, fail-loud-not-silent). The host-your-agent skill is the plumbing that gets the run off your laptop and onto a schedule. durable-state is what makes any of that survive a crash. Read night-shift once for the rules of the road — this skill is the seatbelt.

Say this to your agent

"Before you start this long job, set up a durable-state run folder so a crash or a closed laptop can't lose the work. Write the objective and the stop condition into the contract, save your progress to the files as you go, and log a history line each step. If you get interrupted, resume from the three files instead of starting over."

That one line is the whole idea. Below is what it actually creates and how to resume.

The 3 files that matter

A run folder holds a handful of files, but only three carry the memory an agent needs to resume. If it ever needs more than these three to pick the work back up, the state got too complicated.

The rest of the folder is supporting evidence — the work list, a quality rubric, an append-only history log, a reviewer's verdict, and an artifacts/ folder for proof (drafts, screenshots, command output). Full list is in the table at the bottom.

The 4-step flow

Everything runs through one small command-line tool that ships with this skill (agent_loop.py). It's plain Python — nothing to install, no accounts, no network.

Step 1 — Create the run folder (before the work starts)

python3 agent_loop.py init .planning/loops/june-content-batch \
  --title "June content batch for Client X" --owner "me" --mode overnight

That creates a .planning/loops/june-content-batch/ folder with all the files filled in and a passing validation check. (.planning/loops/ is just a tidy home for run folders — use any path you like.)

Step 2 — Fill in the contract, then let the agent work

Open contract.md and write the real objective and stop condition (the template shows you exactly where). Then the agent does the work, and as it goes it updates the files: it moves the "Current Step" in progress.md, and it logs one line of history each step:

python3 agent_loop.py trace .planning/loops/june-content-batch \
  --kind step --summary "Drafted 3 of 5 GBP posts; saved to artifacts/"

Those history lines are append-only — a truthful timeline you can read later to see precisely what the run did.

Step 3 — If it gets interrupted, RESUME (don't restart)

This is the payoff. Laptop died? Crashed at 2am? Moving to your desktop? Copy the run folder over if needed, then:

python3 agent_loop.py resume .planning/loops/june-content-batch

That prints the three files an agent needs. Hand them to your agent (or read them yourself) and continue from the "Current Step" — no re-doing finished work, no guessing how far it got. Bump the restart count and log why you restarted, so the history stays honest.

Step 4 — Check it's valid any time

python3 agent_loop.py check .planning/loops/june-content-batch

PASS means the folder is complete and genuinely resumable. FAIL tells you exactly what's missing (an empty file, a broken state.json, a rubric whose weights don't add up). Run this before you walk away from a long job.

What a good result looks like

You start a big job, close your laptop, and go to sleep. Overnight the machine restarts (an update, a crash, whatever). In the morning you run resume and the agent picks up at post 4 of 5 — the first three drafts are already sitting in artifacts/, the history log shows exactly when each was written, and the contract still says what "done" means. You lost zero work. You never even had to reconstruct where it was.

Compare that to the old way: the session is gone, you don't know what got done, and you start over from scratch. That difference — "resume from a bookmark" vs. "start over" — is the entire point of this skill.

Capacity, more machines, and the one thing not to do

Durable state is what lets you spread a long run across machines and across time — start on the laptop, finish on the desktop, or split a huge batch over two nights. When that means you're tempted to add more model capacity so a long run doesn't stall, do it the clean way:

• Recommended: point long runs at a budgeted API key with a spending cap you set. It's predictable, it's yours, and a cap stops a runaway job instead of surprising you with a bill.
• Do NOT pool multiple personal-subscription logins behind a shared proxy to fake more capacity. That specific pattern violates Anthropic's terms of service and gets accounts banned. If you need more headroom, raise your API budget or split the work across more nights — the whole point of durable state is that a job can safely span more than one sitting.

For the full set of rules that make an unattended run trustworthy — the time box, read-only-by-default, the failure ledger — read the night-shift skill. This skill doesn't repeat those; it's the piece that makes the run survive an interruption.

Where things land

Read README.md in this folder for the copy-paste quickstart.

The rules it runs under (why you can trust the resume)

• Memory lives in files, not chat. Close the window, lose the session — the work is safe on disk.
• Resume from three files. If it needs more than contract.md + progress.md + state.json to continue, the state is too complicated — simplify it.
• The history is append-only. You never rewrite the past. trace.log is an honest record of what actually happened, in order.
• The doer doesn't grade itself. A separate reviewer writes the verdict in evaluator.md before a run counts as done.
• Restarts are normal. A dead laptop isn't a failure — it's expected. The whole design assumes you'll be interrupted and makes that cheap.

Trivial one-off edits don't need any of this. Reach for durable-state when the job is long, runs unattended, spans more than one sitting, or has ever cost you a session to a crash.