Clone it and it runs. Add tools, extensions, skills, knowledge, or a new persona — and it becomes a vertical agent.
release v0.4.2
node >=22.19
license MIT
upstream pi-coding-agent 0.83.0
What it solves
A runnable skeleton, not a demo
The SDK's createAgentSession is wrapped once into buildAgent(); HTTP+SSE, WebSocket, an in-process CLI and the official RPC stdio transport all sit behind that single core.
Vertical by injection, not by fork
Business logic enters through extraTools, extraSkillPaths, extraKnowledgeDirs, extraExtensions. User-level ~/.pi scanning stays off, so nothing leaks into a deployed agent.
Safety is a first-class axis
Three built-in-tool tiers, a fail-closed path guard, read-only SQL, and an approval gate whose deny rules cannot be overridden and whose timeout closes the turn.
Architecture
Simplified from docs/architecture.svg, which is generated from source; the full page keeps every layer and count.
Tech stack
TypeScript, strict ESM
Node.js (built-in node:sqlite)
@earendil-works/pi-agent SDK
Express
ws
TypeBox
React + Vite frontend
What stands out
One buildAgent() core behind CLI, HTTP+SSE, WebSocket, library and official RPC.
Pluggable RAG: zero-dependency keyword search, opt-in vector retrieval with swappable embedder and store.
Approval gate with non-overridable deny rules, a watchdog, and cross-session memory at owner-only file modes.
MCP bridge, plan mode, subagents, web tools, process execution — all optional, all injectable.
Docs are code: every number on this card is generated from source and re-checked in CI.
By the numbers
505test cases, offline, no real model call
47HTTP route handlers
84backend source files
9gates in npm run verify
Quickstart
npm install
cp .env.example .env # fill PI_API_KEY / PI_MODEL
npm run setup && npm run dev # CLI — or npm run web for HTTP + SSE + the built UI