agentd

A persistent local daemon that wraps Pi's agent execution engine behind a stable API.

Sessions are the primary runtime object. Events are the interface. The filesystem is the source of truth.

Vision

agentd is not a replacement for Pi, a new agent framework, or a chat server. It is a thin orchestration layer that exposes Pi's core capabilities — sessions, tools, models, and extensions — through a durable, composable API.

The daemon owns:

• Session lifecycle — create, resume, branch, and persist agent sessions
• Event distribution — runtime events streamed to subscribers as they happen
• Profile discovery — resolve settings, models, and extensions from disk
• Command routing — dispatch actions to the right runtime context

Everything else stays in Pi.

Design principles

Pi first — If Pi already provides it (settings, sessions, packages, extensions), we expose it rather than replacing it.

Sessions are primary — The fundamental runtime object is a session, not an agent, chat, or conversation. Sessions map directly to Pi SDK sessions.

Events are the API — Commands mutate state; events communicate state. Fully functional interfaces can be built from event streams alone.

Clients are disposable — Clients never own sessions. A session survives websocket disconnect, terminal closure, browser refresh, or bot restart. Clients simply subscribe.

Filesystem is the source of truth — Profiles, settings, and sessions are files. No database, no migrations, no schema evolution layer.

Current implementation

The current codebase is a zero-dependency HTTP + SSE bridge around Pi's RPC protocol:

main.py         → asyncio HTTP server, raw HTTP/1.1 parsing
wrapper.py      → async PiClient wrapping `pi --mode rpc`
webui/          → single-file dark-theme chat UI
docs.md         → endpoint reference and client examples

Key characteristics

• Zero dependencies — stdlib only (no FastAPI, aiohttp, or frameworks)
• Persistent sessions — conversations saved to ~/.pi/agent/sessions/
• SSE streaming — real-time thinking blocks and text deltas from /prompt
• CORS-enabled — designed for cross-origin web UIs
• Session management — list, switch, fork, name, and inspect sessions
• Composable — the wrapper can be imported and used from Python directly

Endpoints

Endpoint	Purpose
POST /prompt	SSE-streamed agent conversation
POST /bash	Run commands in agent context
POST /abort	Abort in-flight operations
POST /steer	Queue steering message
POST /follow_up	Queue follow-up message
GET /state	Session state snapshot
GET /messages	Conversation history
GET /sessions	List saved sessions
POST /switch_session	Load a different session
POST /new_session	Start a fresh session
POST /fork	Branch from a previous message
GET /fork_messages	List forkable message points
POST /set_session_name	Name the current session
GET /session_stats	Token usage and cost

Future direction

The long-term vision is for agentd to become a multi-transport daemon:

• Unix socket protocol — a compact, formal IPC layer for local companion services
• Multi-client support — concurrent web UIs, terminal clients, messenger bridges, and service-to-service integration
• Deeper session tree support — branch graphs, navigation, summaries, tree-aware UIs
• Event-driven architecture — clients build fully functional interfaces from event streams alone
• Agent-as-user host model — leverage OS user accounts and permissions for agent identity and isolation

These extensions must remain additive — no new core abstractions, configuration formats, or security architectures.