pi durable

@earendil-works/pi-durable — the durable-agent-harness package inside pi (OSS) (README captured → clippings/github-com-earendil-works-pi-tree-main-packages-durable.md; experimental, API changes without notice). One sentence: conversations, model turns, tool calls, and your own state are committed to storage before anything is shown — if the process dies mid-turn, reopening the storage picks the work up where it stopped.

The design

• Built on pi-ai (models) + chord (document state). All changes go through one line of atomic commits; nothing is visible before its commit is stored — write-ahead logging applied to the agent conversation itself (the same discipline as a database WAL: the log is the truth, the display is a projection).
• Conversations are transcripts of immutable entries; submit() durably admits work, wait() resolves done/unanswered-with-reason; cancellation semantics are honest — cancelling a wait never cancels the work.
• The grown-up feature list: extensions, tools, per-conversation agents, watching a conversation (another process observes), reset/handoff, compaction, agent events, hooks, forks, abort and subagents, child tasks, task graph, your own state, usage/cost accounting, pluggable storage.

The ecosystem that grew on it (2026 GitHub search, stars at capture)

• pi-dispatch (178★) — run pi as a self-hosted service: jobs from cron, CLI, or GitHub/GitLab/Forgejo/ADO events.
• pi-posthorse (256★) — “fresh context, same journey”: no-summary context rollover for pi.
• The-Vibe-Company/companion (2.4k★) — persistent AI companions on Box “powered by Pi… durable execution”.
• pi-pocket (74★) — durable, multiplayer, mobile-first web app for Pi agents, “built on Pi Durable”.
• ha-pi-durable / Hearth Pi (8★) — Home Assistant AI app with durable tasks, scoped reads, human-reviewed actions (the “we have cloudflare at home” tweet runs this inside a celld Durable Object — see Homelabs kin).
• acpus (40★) — orchestrate Claude/Codex/Pi/ACP agents in dynamic durable workflows (survive crashes, pause/resume).
• omp-ninfer (42★) — durable local inference (NInfer + Qwen3.8 27B on one 3090/4090/5090, restart-resumable) — the local-model lane.
• mainframe (12★) — shell safety checks + durable task checkpoints + execution evidence.

Why it matters

The Pi agent harness philosophy (“no background bash, no sub-agents”) plus durability = the state-machine-over-fragile-chat-loop convergence the State machines note tracks, shipped as infrastructure: agent work that survives crashes, pausing, handoff, and audit. Same family as Datadog Temper (spec committed before execution) — write-ahead discipline for agents — and the durable-execution lane in AI engineering (control plane). The Raspberry-Pi-in-a-celld-DO image is the thesis in one picture: durable objects (cloud primitive) hosting a durable agent (harness primitive) on hardware that reboots.

In the wild (2026-10-05)

@Howaboua’s build (tagging Zechner, who replied “lol”) — pi-durable running on a ChatGPT site: an MCP server that lets other agents chat with the durable-harness-driven site, with a forked Codex CLI at “4× less token consumption” (durable session state + forks replacing re-feeding context). “Built 95% with Pi, dw.” Two signals: pi-durable escaping the Pi bubble into agent-to-agent surfaces (an MCP server fronting a durable harness), and the token-economics claim that durability + forking beat context-refeeding — the same economics as OptChat’s fixed-window compression, achieved by persistence instead of summarization. Ecosystem row updated in spirit: the durable harness as a service, not just a library.

The canonical explainer (author-endorsed)

@lucataco’s “What is Pi Durable?” video (1080p, 24k views on the quote) — endorsed by Zechner himself: “recommended viewing if you want to understand what pi durable is. it’s 100% accurate and breaks it down real well. i should learn how to do those ai explainers.” (captured → clippings/x-2107025576771072277.md). Note the second-order observation: the author of the thing doesn’t know how to make the explainer format for it — AI-generated explainer videos as a distinct skill/tooling lane (kin: the claude.dev HTML-effectiveness thesis — explainers as HTML/video artifacts agents could generate).
Related: Pi agent harness · State machines · AI engineering · Homelabs (celld)

Monday Meditations: the durability conversation (2026-10-05)

@pidotdev (587❤ / 54k views) — Zechner + Armin Ronacher on why Pi Durable exists: “a harness built around a small task-based workflow engine so long-running, multiplayer agents can suspend and resume anywhere. Also: why not Temporal or Effect.ts.” Endorsed by @dillon_mulroy (191❤) as required viewing, bulleting the three takeaways: what durability actually is and why versions make it hard; nuanced trade-off discussion (not framework maximalism); and the surprise — Armin actually likes Effect.ts. The 515 MB video stays as a linked asset (too heavy for the vault; the why-not-Temporal/Effect reasoning is the valuable part and it’s the same versioning-the-workflow-state argument this note already carries).

Rat King: the AT Proto agent network on rat-stack (joelhooks)

Follow-up tweet pair (1, 2) + rat-king (OSS) (3★ pre-alpha TS; VISION.md fetched): “my goal with rat king is to run a tailnet/Cloudflare AT Proto agent network where every agent is/has a Durable Object — ‘twitter for agents’ basically.” Named for rats bound at the tails: agents bind into one network while keeping private messages encrypted and instance details outside the public tree. Pure rat-stack (Effect + Alchemy, ratstack.sh — “gives me a better chance for success”; XState lifecycles) — “the app and its infrastructure as one typed program.” Four-phase path: encrypted mailboxes → per-agent PDS → permissioned Spaces → federated allowlisted peer networks with quotas and kill switches (“you could potentially federate with other agent networks 🖖”). Shipping discipline is the notable part for pi durable kinship: ship small reversible releases; every capability starts OFF; report code-ready / deployed / behavior-verified separately; rollback restores a known-good version without rebuilding; “each phase must prove that two agents exchange an encrypted message as the recipient would see it.” The pi-durable-in-a-celld-DO quote-tweet below it is the same week’s thread (“we have cloudflare at home”).

The technical-manual pattern (and a 190-page Pi Durable manual)

calebfahlgren: “Pi Durable is awesome! Asked Opus 5.5 to make a deep technical manual on it. It’s really good and the diagrams work really well 🤌” — PDF preserved at _research/assets/Pi-Durable-Technical-Manual.pdf (190 pages, 319 TOC entries; HF bucket link in clipping). The manual is genuinely deep: the four kinds of turn-state, four-layer architecture, the core rule and eight invariants (atomic across records/documents; publish-after-storage; effects off the commit line; immutable entries/ids never reused; drafts die with their callback; uncertain failure poisons the Session), the full anatomy of one answered input as 17 commits, mutation-line steps 1–8, three failure outcomes. His earlier tweet (quoted in the thread): “My favorite way to learn with AI right now: ask for a dense technical manual on the topic, grounded in the actual spec and source code with diagrams. Made these for Parquet and GGUF. Frontier models are shockingly good at this now.” + “such a different way to prop your feet up, get some coffee, and read for 30min–1h.” This is the 3b1b/answer-me-with-html lane in long-form: generated-but-grounded artifacts as a reading medium — kin to Vibecoding vs AI engineering’s retro docs and the socratic learning lane in Agent skills; for this vault: generate-manual-from-source is a candidate skill.

The full technical-manuals triad

The Pi Durable manual has siblings: @calebfahlgren’s HF bucket (captured) holds three — Parquet (155 pp / 277 TOC) and GGUF (105 pp / 178 TOC) join Pi Durable (190 pp / 319 TOC); all preserved at _research/assets/. Every one opens with the same honesty frame (“How to read this book”, “What it is grounded in”, “How it was made”) and uses the same signature moves: numbered goals/invariants, life-of-one-operation walkthroughs, state-over-time diagrams. Method tweet: “ask for a dense technical manual on the topic, grounded in the actual spec and source code with diagrams. Frontier models are shockingly good at this now.”

Trial run done (2026-10-05): technical-manual skill created (Hermes profile skills) and exercised — The Capture ETL — A Technical Manual (also capture-etl-manual.html in vault root, symlinked into viz.h artifacts): 8 invariants, 13-step life-of-one-capture, drift decision tree, four-layer architecture, field-notes wall table — all grounded in the ETL’s actual 1,908 lines, live manifest stats (738 rows) cited on the cover.

Rat-stack lore: structure by domain, not mechanism

@joelhooks (150❤): “the assembled lore for idiomatic effect project organization” — ratstack.sh/lore/structure-effect-by-domain (19.9 KB, captured; Effect 4 names, pinned examples + exact Effect 4.0.0 source). The core move, quoting Sam Goodwin: src/{domain} instead of src/{mechanism} — “src/coding/edit.ts instead of src/tools/edit.ts; ‘tools’ is the mechanism, ‘coding’ is the domain.” One service + Layer per file; one entrypoint + Effect.provide per file. The tree: domain folders own behavior (files/ = Service+Layer, schemas, optional XState lifecycle), platform/ supplies adapter Layers (“implementations, not domain rules”), main.ts = composition root (one per entrypoint, not one global root). Rules that hold it: capture dependencies at construction (callers need only the Service — the Layer constructor pattern), decode at boundaries with Schema (contracts.ts owns input/output/failure schemas), expected failures typed and distinct from defects (“a crash is not a domain refusal”; FileStatsError preserves the failed path). Lore pages carry reverse-link counts (tests page: 19 inbound) — the reading order is a curriculum: Effect basics → schemas → error model → services → layers → config → testing. Same author/thread family as Rat King above; the lore site is the documentation arm of the rat-stack Pi Durable runs on.