pi on Pi Durable: one daemon per host owns every pi session, and terminals (later web and phone) attach to it as thin clients. Like a pier: it stays put, and boats tie up and cast off.
Status: a deliberately thin slice, in daily use: a daemon, a Unix socket, and a
terminal client drawn with pi's own components. Claude runs on a Durable Harness
through Claude Code, with your Claude subscription, and survives a crash mid-tool, Esc,
compaction and forks (pi 1.5.2). See todos/ for what's next.
pier daemon # the daemon, in the foreground (dotfiles runs it as a user service)
pier # in a project: continue its newest conversation, or start one
pier new # start a new one
pier resume <n> # attach to conversation #<n>
pier list [--all] # conversations here (or everywhere)
pier --tui-mode regular … # the client in the terminal's own scrollback, not fullscreenIn this repo, npm run pier -- <args>, or node src/host/cli.ts; the package (dotfiles
builds it with Nix) runs dist/, from npm run build. In the client,
/help lists the keys and commands. Enter sends, and steers while Claude works;
Alt+Enter queues a follow-up, and Alt+Up takes what's queued back into the editor; Esc
stops the run; Ctrl+C on an empty editor leaves, and the run carries on. Up in an empty
editor recalls the conversation's earlier messages, from every session, as in pi. When
the daemon restarts, the client reconnects and carries on where it left off. Queued
messages stay above the editor until the run takes them in; the client's own lines
("new conversation #3", "compacting in the background", errors) go into
the transcript, and scroll away with it.
Typing / opens pi's menu of commands, which more letters filter; a command's
argument is picked from a menu of its own, with the arrows and Enter:
/modeland/thinking: the models the daemon has credentials for, and the levels the conversation's model supports (one it doesn't is clamped, as pi clamps it)./resume: every conversation, those in this directory first./fork: one of your messages. A new conversation starts with the history before it, and the message goes back into the editor, as pi's/forkdoes./tree: the conversation's family of forks, from the root down, to switch between. A fork is shown by its first message of its own, with how many it has, its newest, and when it was last used. A fork from before the first message belongs to the family too. Each branch is a conversation of its own, with its own Claude Code prompt cache: going back to one reads its context from the cache (99.8%, by hand on 2026-11-16), as long as it's been idle under the hour pi-claude-code's cache entries last.
The client runs fullscreen, on the alternate screen, as pi does by default: it scrolls
(PageUp, Ctrl+Home, Ctrl+End), jumps between your messages (Ctrl+Up, Ctrl+Down),
searches (Ctrl+Shift+F), copies a mouse selection, and leaves the transcript in the
terminal's scrollback when you leave. --tui-mode regular, pi's flag, draws it in the
terminal's own scrollback instead.
It looks like pi, as it's drawn by pi's components, in pi's theme, with your theme,
hideThinkingBlock and showHardwareCursor from pi's settings.json (the last puts
the terminal's own cursor in the editor, so a pane that loses focus shows none, or a
hollow one when the terminal's window does):
- Model responses with their thinking (Ctrl+T hides it), tool calls in pi's coloured blocks (grey while running, green done, red failed), with edits as diffs and long output collapsed (Ctrl+O expands it), and compaction summaries (Ctrl+O too).
- pi's working line in the editor's border while a run goes, and after each run a
run line, with the facts pine-of-glass's cachemire prints:
◍ run: 3 turns · 9s · read 5.8k (99.9% cached) · wrote 1.2k · out 0.1k. - A footer as pi's: the conversation and directory; tokens, what its model responses would have cost at API prices ("(sub)": you're on the plan), the context used, the model and thinking level; and the Claude plan's 5-hour and 7-day windows, as pi-quotas shows them.
- A long outage leaves no hole: the client loads what it missed.
/earlierloads older messages.
The terminal must answer pi's color query for tool blocks' backgrounds; a tmux pane no client is showing may not, and then they're blank.
pier says what Durable says (its README, "Concepts"): a turn is one model response and its tool calls; a run is the turns from an input to its final answer, the response with no tool calls that ends it. A conversation is busy while a run is going.
Conversations are numbered #1, #2, … on each host. Any number of panes can attach to one conversation. Each conversation's tools run in its directory, with the environment of the last pane that attached to it.
The socket is $XDG_RUNTIME_DIR/pier/pier.sock and the storage
$XDG_STATE_HOME/pier/pier.sqlite; PIER_SOCKET, PIER_STATE_DIR, PIER_MODEL
(claude-code/claude-opus-5-5) and PIER_THINKING (high) override them. The daemon
refuses to start with a model it can't run, or a thinking level that isn't pi's.
PIER_SKILLS lists the skills the daemon offers (below, "Skills").
src/layer/is what carries over to p3 (docs/vision.md), and never imports the host:claude-code.tsloads Earendil's pi-claude-code, the provider that sends requests through Claude Code (below);prompt.tsbuilds the system prompt from AGENTS.md files, found the way pi finds them;skills.tslists the skills the model is offered (below).
src/host/is what's thrown away when p3 takes over:daemon.tsruns the Harness and serves it on the socket,protocol.tsis what goes over it (the daemon checks each request against its schemas),client.tsandtui.tsare the client (commands.tsits slash commands and their menus), andcli.tsispier(defaults.tsthe model it runs).experiments/gate/holds the gate: real Claude Code turns against a Durable Harness, each step in its own process so it can be killed.experiments/wire/measures what a conversation watch sends.experiments/transcript/measures the terminal client with a long transcript.test/holds offline tests, with a faux model in place of Claude: the daemon and its clients over a real socket, the prompt, and the provider's loading.todos/holds specs for work not yet done.docs/vision.mdsays what pier is for, and how it changes as p3 does.docs/principles.mdholds the principles all work on pier keeps to.docs/releasing.mdsays how release-please makes versions.docs/history.mdrecords Will's decisions, the gate's findings and the wrong turns.docs/upstream.mdholds what pier relies on from Earendil, and where Earendil is going, as last read.
direnv allow # once; or `devenv shell`. Installs node_modules and the git hooks.
npm test # offline unit tests (also a pre-commit hook)
npm run check # typecheck (also a pre-commit hook)
npm run build # compile src/ to dist/, which the package's `pier` runs
devenv test # both
npm run gate # the gate: about twenty Opus turns on your Claude Code loginThe gate prints a PASS/FAIL line per check and leaves its state directory in /tmp: the
SQLite storage, and every event (transcript.jsonl).
pier talks to Claude with Earendil's pi-claude-code. It sends each request through
claude -p, on Claude Code's own login, so it uses your Claude subscription. Claude
Code only talks to the model; Durable runs the tools. It's a plain pi-ai provider,
registered with ModelRuntime.registerNativeProvider(), so it needs nothing from pi's
extension API. Its models are claude-code/<model>.
Things a host must know, all found by the gate:
- Release each conversation's warm Claude Code process. pi-claude-code keeps one
per conversation for straight continuations, and frees it when pi-ai's
cleanupSessionResources(sessionId)is called with the conversation's provider session id. pi does that when a session ends; Durable never does. - Claude Code would run in the host's directory, which it reports to the model as
its working directory: pi-claude-code starts it in
process.cwd(), and nothing in a request names a directory. pier'sConversationDirectoriesextension records each conversation's directory before its requests, and the provider pier loads runs each request in a scope whereprocess.cwd()answers it (src/layer/claude-code.ts). A provider option upstream would replace that. - It spawns Claude Code detached, as Durable spawns tools, so only a control-group kill reaps them if the host dies.
- The prompt cache survives an idle conversation for up to an hour: every entry is written with a 1-hour lifetime.
Until 2026-11-13 pier used pi-claude-bridge instead, through a shim standing in for
pi's extension API. It's in git history, and docs/history.md records what it took.
The prompt lists the skills the model may use, in th
6A82
e
agentskills.io format: each skill's name, description and
SKILL.md. When a task matches one, the model reads its SKILL.md with the read tool,
then runs the command it describes with bash, in the pane's environment. So the
command must be on the pane's PATH. They come from two places, read before each
request, so a change shows on the next one:
PIER_SKILLS: the daemon's skill directories, absolute paths separated by:as inPATH. Each is one skill (holdingSKILL.md) or a directory of them. Point it at a package'sshare/skills/<pname>, where nixpkgs'installAgentSkillshook puts a package's skills (share/skills/<pname>/<skill>/SKILL.md). The daemon reads it when it starts, and logs the list.- The project's own:
.agents/skillsand.pi/skillsin the conversation's directory and each one above it, up to the repository's root (.git); outside a repository, only its own directory.
When two skills share a name, the project's wins, then the nearer directory, then the
earlier one in PIER_SKILLS. pier reads nothing of classic pi's for skills: not
~/.pi/agent/skills, not settings.json, not pi packages. Without PIER_SKILLS, only
projects' skills are offered.
No trust check. A project's skills load without asking, as its AGENTS.md does (Will, 2026-11-17: "No, let's not ask"). A repository you open can put instructions in the prompt either way, and a prompt on skills alone would protect little. agentskills.io suggests gating them on trust, as classic pi does. Isolating what a conversation can reach is the place to revisit this.
- A tool call has no timeout unless the model sets one: Durable's bash has no default.
- One environment per conversation: two panes in different shells on one conversation take turns deciding it.
pier(continue) scans up to 500 conversations each time.- The protocol has no backpressure: a slow client's socket buffers.
- The socket is chmodded to 0600 just after it starts listening; in its 0700 directory that gap doesn't matter.
- A project's skills load without asking, as its AGENTS.md does (below, "Skills").
- Images show only as pi's placeholders (
[Image: [image/png] 64x64]): Alacritty has no image protocol, and pi-tui shows none under tmux. Claude sees them: it read a PNG and named its colour, by hand on 2026-11-16.
pi's packages are pinned exactly in package.json, all to one release (1.5.2). Pi
Durable is experimental, and breaking changes land in minor releases, so bump them
together and deliberately: read their changelogs, then run the tests and the gate.
pier doesn't follow the pi that nixpkgs ships (1.5.0 on 2026-11-12). Its packages come
from its own lockfile, so nothing ties the two together. What pier shares with classic
pi is ~/.pi/agent: settings and credentials.
pi-claude-code isn't on npm. It's pinned to a commit, as a GitHub tarball
(codeload.github.com), so installs need no git and no SSH key.
MIT