A desktop app for managing multiple pi agentic coding sessions. Each session runs in its own isolated process, streaming conversation history, tool calls, and status in real time.
Status: Early development — M1 Foundation milestone in progress.
- Multiple sessions — run several pi sessions side by side, switch between them instantly
- Streaming conversation view — see messages, thinking blocks, and tool calls as they arrive
- Session lifecycle — create, close, reopen, and delete sessions; archived sessions show their full history without needing to restart
- Session browser — discover and open existing pi session files from disk
- Monitoring — token counts, cost, context window usage, compaction and retry status
- Offline history — click any archived session to read its conversation without spinning up a host process
- App icon & About panel — native macOS About dialog via the ⓘ button in the sidebar
- macOS (arm64) — Windows and Linux support is planned but not yet built or tested
- Node.js 18 or later
- pi configured with at least one model and API key (
~/.pi/agent/auth.json)
# Install dependencies
npm install
# Start in development mode (hot reload)
npm run devOn first launch, pi Manager reads your pi configuration from ~/.pi/agent/ (or $PI_CODING_AGENT_DIR if set). You'll need API keys configured for at least one provider before sessions will run.
| Command | Description |
|---|---|
npm run dev |
Start dev server with Electron hot reload |
npm run build |
Production build |
npm run dist |
Build and package as a .dmg (macOS arm64) |
npm test |
Run unit tests (Vitest) |
npm run test:watch |
Run tests in watch mode |
npm run typecheck |
TypeScript type check |
npm start |
Preview the production build |
Pi Manager is a three-process Electron app:
┌─────────────────────────────────────┐
│ Main Process │
│ Supervisor — spawns/tracks hosts │
│ IPC bridge — renderer ↔ main │
│ Session store — disk persistence │
└──────────┬──────────────────────────┘
│ parentPort.postMessage
▼
┌──────────────────────────┐ ┌──────────────────┐
│ Session Host │ │ Renderer (React) │
│ (Electron utilityProcess)│ │ │
│ Wraps AgentSession SDK │ │ Sidebar │
│ Dispatches commands │◄───│ SessionView │
│ Forwards events │ │ PromptInput │
└──────────────────────────┘ └──────────────────┘
Each pi session runs in its own utilityProcess — a crash in one session cannot take down the app or other sessions. The renderer communicates through a contextBridge API; nodeIntegration is disabled.
Session files (JSONL) live on disk at ~/.pi/agent/sessions/. Pi Manager reads them directly for offline history display, without needing a running host.
For full details see docs/architecture.md.
node --version # 18+
npm --version # 9+src/
├── main/ # Electron main process (CJS)
├── preload/ # contextBridge API surface
├── host/ # Session host (ESM — runs in utilityProcess)
├── renderer/ # React UI
└── shared/ # Types shared across all processes
tests/
└── unit/ # Vitest unit tests (mirrors src/ structure)
docs/ # Architecture, plans, roadmap
resources/ # App icon assets
npm test # All unit tests
npm run test:watch # Watch mode
npm run typecheck # TypeScript onlynpm run dist # macOS arm64 DMG → dist/Cross-platform builds (Windows, Linux) require the appropriate CI runners. See electron-builder.yml for the build configuration.
npm run release:patch # bug fixes 0.0.1 → 0.0.2
npm run release:minor # new features 0.0.1 → 0.1.0
npm run release:major # breaking change 0.0.1 → 1.0.0This bumps package.json, commits the change, creates a v*.*.* tag, and pushes both. GitHub Actions picks up the tag and builds mac (universal), windows, and linux artifacts, then publishes them as a GitHub release.
Issues and pull requests are welcome. Please read AGENTS.md for coding conventions, architecture decisions, and the task-with-tests contract before contributing.
MIT — © 2026 Nick Perkins