Building Pico: A Local-First Workspace for Coding Agents

How Pico keeps coding-agent sessions true and durable: a web workspace on one local server, a live stream that recovers from any gap, and runs that survive a crash without repeating their side effects.

Most coding-agent interfaces begin and end with the transcript. I started Pico (opens in a new tab) with a different question: what does the workspace around that conversation need, if I use it all day?

A useful agent session can run for many minutes. It touches many files, starts follow-up work, and leaves decisions that I must review. During that time, my phone locks, the Wi-Fi changes, and the server restarts after a rebuild. The screen must still show the true state of the session, and the agent must not do the same work twice.

Pico is a web workspace for durable Pi coding-agent sessions. One Node server on my machine hosts the agent runtime and serves the React app. The app works on a desktop and on a phone. This note replaces an earlier version that described native macOS and iOS clients. Pico is web-only now, and its sessions are durable.

The workspace is the product

Pi (opens in a new tab) gives the important part: the models, the tools, and the agent loop. I did not want to build that again. I wanted to build what my daily work kept asking for:

  • Sessions grouped by project, active and old, so that each conversation is not a lost tab.
  • A composer that does not wait for the agent: queue the next prompt, or steer the current run.
  • Slash commands and skills, @ references to project files, and a switch for the model and the thinking level, all from the keyboard.
  • Git review beside the agent: changed files, diffs, stage, discard, commit, pull and push. I can comment on a line of a diff and send that comment to the agent.
  • A file browser with syntax highlighting, and terminals.
The transcript is only one surface. The workspace is the product.

Local-first, with honest edges

The Pico server runs on the developer’s machine. Project files, Git operations and provider credentials stay where the work already is. There is no cloud layer between a prompt and the project.

One local server hosts the durable agent runtime and serves the web app. Terminals and jobs live in a separate host process.

Local-first has a cost that I want to state clearly: Pico has no login. Anyone who can reach the server can run commands as my user. So it stays on localhost or on a Tailscale network, never on the public internet. From that boundary, one Pico can also act as a hub: it connects to the Pico on another computer over SSH and shows that machine’s sessions in the same sidebar. Those sessions run on their own machine and continue when the hub goes offline.

The live stream is a state machine

A coding agent does not return one neat response. Text streams in, tools start and finish, a queued prompt starts, and Git changes under the agent. The browser gets all of this through one Server-Sent Events stream. The hard part is not to open the stream. It is to know what the browser has, after any gap.

The live event stream: a full baseline first, then patches, and a clear path back after a drop.
  • Every event has an ID. The browser keeps the last ID in session storage and sends it back on a new stream. The server replays the missed events from a window of the last 512.
  • A baseline comes first. The first message on a new stream is always the full state of the session. After it, the server sends only patches: where the change starts, how many items it removes, and the new items. Streamed text arrives as deltas.
  • Too old means a resync, not a guess. When the window no longer covers the ID, the server says so and sends a new baseline. The browser never applies a patch to the wrong base.
  • Event IDs survive restarts. They start from the clock when the server starts, so they keep growing. An ID from before a restart gets no replay; the baseline covers it.

When the server goes away

When the server is down, every request fails at the same time. Without care, the page shows one error for each request. In Pico, one small store holds the connection state: unknown, online or unreachable. A failed request asks the health endpoint once. While the server is down, the store checks again after 1, 2 and 3 seconds, and then every 5 seconds, and the page shows one “server unreachable” view. When the server answers, the page opens a new stream with the saved event ID. A tab that comes back after 30 seconds in the background reconnects at once.

Runs that survive a crash

Sessions live in one SQLite database. The pi-durable runtime stores a checkpoint at each step of a run and continues unfinished runs when Pico opens again. That runtime is open source and not mine. My part is to make Pico’s own tools follow its replay rules, because a tool with a side effect is the dangerous case.

One tool call across a crash. Only replay-safe tools run again, and each one reads its memo first.
  • The runtime stores the intent of each tool call before the tool runs. After a crash, a tool that is not replay-safe gives the model an “interrupted” result with its output so far, and the model decides what to do.
  • Pico marks its tools with external effects as replay-safe, and each one checks a stored memo before it acts. A rerun of job_start reports the job that it already started. A rerun of spawn_session finds the child that the same call made.
  • Tool state lives in documents, not in server memory, so a restart does not lose a todo list, a timer, a question or a child-session link. A timer that was due during the downtime fires one time at startup.
  • Terminals and background jobs run in a separate pico-pty-host process. After a server restart, the server takes them over again with their output. A job whose process is gone is reported as lost, not as finished.

One gap stays open, and I want to say so: the side effect and its memo are two steps. A crash between them can repeat the effect. Where the effect is a message to a session, a fixed request ID closes the gap, because the runtime refuses a second submission with the same ID.

Agents that work in parallel

An agent can start child sessions, each in its own Git worktree, so parallel work does not collide in one checkout. A child gets a tool profile from its parent: full, builder, researcher, reviewer, read-only, or a custom one. It cannot ask the user, send notifications or start more children unless the parent allows it, and its shell refuses git push to main and sudo. When a run ends or the agent asks a question, Pico can send a Web Push or ntfy notification, so I do not have to watch the screen.

What I learned

The workspace around AI matters as much as the model

Models will keep changing. The durable product work is to make sessions understandable, context visible, actions reversible and parallel work manageable.

Streaming is a state and data-modeling problem

A smooth stream can hide a weak state model for a while. It cannot survive reconnects, restarts and long sessions without explicit rules: a baseline, patches against a known base, and a clear answer to “what does the client have now?”

Durability is a contract, not a feature

A run that continues after a crash is only safe if every tool says what happens when it runs twice. The runtime stores the steps. The product must define that rule for each tool, and name the gap that remains.

Local-first needs honest edges

Keeping the runtime near the code improves ownership and removes infrastructure. It does not solve network security. The supported boundary must be clear in the product and in the documentation.

Try Pico

Pico is open source under the AGPL-3.0 license. The code is on GitHub (opens in a new tab), and the package is @alivault/pico (opens in a new tab) on npm. It needs Node.js 22.19 or later.

npm install -g @alivault/pico
pico-app

The workspace opens at http://127.0.0.1:3141. The Pico case study shows the same state machines with tables of each state and transition, and the source files behind each claim.

Comments

Sign in to write a comment.

Loading

Ali Abbas