How yayasoumah/pocket-server works
Project type and purpose
• Pocket Server is a local-first Node.js “OS”/runtime for AI agents, exposing HTTP + WebSocket APIs for a mobile app and CLI.
• It orchestrates agent sessions (OpenAI/Anthropic), filesystem & terminal operations, background “Cursor” agents, notifications, and optional Cloudflare tunneling.
Top-level analysis of the file tree
• CLI entrypoint: cli.ts
• Core server: src/server (router.ts, websocket.ts) using Hono for REST + WS.
• Authentication: src/auth (pairing, token, middleware, device registry).
• Agent runtime: src/agent (providers, orchestrator, tools for both OpenAI + Anthropic).
• File system API: src/file-system (handlers, service, telescope search).
• Terminal API: src/terminal (routes, manager, registry).
• Background/cloud agents: src/background-agent/cursor.
• Notifications: src/notifications.
• Tunnel: src/tunnel/cloudflare.
• Shared utilities: src/shared (logger, paths, public-URL, types).
• Session store: src/agent/store (FS based).
• Config & scripts: package.json, scripts/release.mjs, CI workflows.
Key architectural patterns & principles
• Server-authoritative: all state lives under ~/.pocket-server/data.
• Event-driven UI: clients subscribe over WebSocket to server-emitted events.
• Modular, adapter-based providers: OpenAI vs. Anthropic share a common interface.
• Clean separation of concerns: auth, agents, FS, terminal, background tasks, notifications, tunnel.
Main components & their interactions
A. External clients
• Mobile App (iOS/Android)
• CLI (local terminal commands, desktop attach)
B. Pocket Server runtime (Node.js bundled)
1. HTTP REST API (Hono router)
2. WebSocket endpoint (/ws)
3. Auth module (pairing, token issuance)
4. Agent Orchestrator
• Context Loader → injects CLAUDE.md / AGENTS.md
• Provider Adapters → OpenAI / Anthropic
• Tools → editor, bash, web-search, planning
5. File System Service → browse/edit/diff via FS handlers
6. Terminal Service → PTY sessions, streaming
7. Background-Agent (Cursor) → GitHub VM jobs, webhooks
8. Notifications Service → device push events
9. Tunnel Module → Cloudflare quick-tunnel
10. Session Store (FS) → persists all session data
C. External services
• OpenAI API
• Anthropic API
• Cloudflare tunnel
• GitHub (for background-agent jobs)
Relationships & data flows
• Mobile App / CLI ⇄ HTTP REST (JSON) & WebSocket (events, streaming)
• Auth tokens secure both REST & WS (Authorization: Pocket <token> / ?token=)
• Agent Orchestrator calls external LLM APIs via provider adapters
• File System & Terminal API modules interact with local FS and spawn PTYs
• Background-agent triggers jobs on GitHub VMs, receives updates via webhooks
• Notifications module publishes device notifications via push API
• Tunnel module uses Cloudflare CLI under the hood to expose public URL
• Session Store persists across all modules (authoritative state)
Architectural patterns & design principles
• Adapter pattern for LLM providers (common interface for OpenAI/Anthropic)
• Modular plugin-style tools for agents (editor, bash, search)
• Event-driven communication over WebSocket for UIs
• Server-authoritative state with FS-backed store
• CLI orchestrates lifecycle (pair, start, stop, attach, update)