Looped

Your AI employee with its own computer. Each user gets a persistent cloud VM (Sprite) running an AI coding agent that remembers everything, reads and writes files, runs scripts, and works autonomously. The interface feels like an operating system, not a chat app.

Core loop: Talk to agent -> AI reads context, runs tools, writes files -> Results appear as workspace cards -> Agent learns and remembers across sessions

Mental model: The agent IS the operating system. The UI is a window into the agent's workspace. Files, documents, and results are objects on a desk, not messages in a chat thread. The filesystem is the memory.

Architecture

Browser (Next.js 16 on Vercel)
    |
    | WebSocket (wss://)
    |
Fly.io Bridge (Node.js)
    |  - Clerk auth (JWT on connect)
    |  - Route user_id -> sprite_name (Supabase)
    |  - OpenRouter API key proxy
    |  - Pi RPC event -> Looped event translation
    |  - Sleep/wake reconnection + keepalive
    |
    | TCP Proxy WebSocket (Sprites.dev API)
    |
Sprites.dev (one VM per user)
    |
    | stdin/stdout JSON lines
    |
pi-coding-agent (persistent RPC process)
    - LLM: MiniMax M2.5 via OpenRouter (default, configurable)
    - Tools: bash, read, write, edit, grep, find, ls
    - Extensions: pi-subagents, pi-web-access
    - Sessions: JSONL files on disk with auto-compaction
    - Memory: AGENTS.md + .looped/ markdown files
    - Database: SQLite for task metadata

Codebases

Directory	Stack	Purpose
frontend/	Next.js 16, React 19, Zustand, shadcn/ui, TailwindCSS v4	Workspace UI, WebSocket client
bridge/	Node.js 22, TypeScript, ws, Clerk, Supabase	WS proxy, auth, pi RPC translation
sprite/	Bootstrap scripts, AGENTS.md, looped-docs CLI	Sprite provisioning assets

Tech Stack

Frontend: Next.js 16 (App Router) . React 19 . TypeScript . TailwindCSS v4 (OKLch) . Zustand . shadcn/ui . TanStack Table . Tabler Icons . Vercel AI Elements (ported)

Bridge: Node.js 22 . TypeScript . ws . Clerk (JWT auth) . Supabase (user routing) . busboy (uploads)

Agent: pi-coding-agent . MiniMax M2.5 via OpenRouter . SQLite . JSONL session persistence

Infrastructure: Vercel (frontend) . Fly.io (bridge) . Sprites.dev (per-user VMs) . Supabase (auth routing) . Clerk (identity)

Features

Workspace

• Grid layout with file, folder, document, and profile cards
• Task management with create/switch/complete/delete lifecycle
• Streaming output with real-time text + reasoning deltas
• Activity log showing agent thinking, tool execution, and transcript
• Syntax highlighting via Shiki
• Multi-tab support with shared sprite connection

Document System

• Upload documents (multipart to bridge, forwarded to sprite filesystem)
• OCR + extraction pipeline via looped-docs CLI
• FTS5 full-text search across all documents
• Status tracking: pending -> ocr -> extracting -> validating -> complete
• Three folders: uploads/, outputs/, tmp/

Skills System

• Create, edit, save, and delete reusable agent skills (markdown files)
• Skills loaded into agent context for domain-specific capabilities

Voice I/O (optional)

• Deepgram STT via WebSocket with interim results
• Custom TTS pipeline with AudioWorklet processor
• Feature-flagged via NEXT_PUBLIC_VOICE_ENABLED

Agent Memory

• Profile and preferences files updated as the agent learns
• Session transcripts with auto-compaction (pi handles persistence)
• Task metadata in SQLite for fast bridge queries
• Chat history persisted to sprite filesystem
• Full workspace state reconstructed on reconnect

Protocol

Bridge translates pi RPC events to Looped workspace events. Flat message format (no payload nesting).

Pi sends: agent_start, agent_end, message_update, tool_execution_start/update/end

Bridge emits: text_delta, reasoning_delta, tool_start, tool_end, task_status, files_changed, workspace_sync, heartbeat

Bridge handles directly: task CRUD, file listing/reading, skill CRUD, document processing

Auth flow: WS connect -> {type: "auth", token} -> connected -> sprite_ready

Protocol types defined in bridge/src/protocol.ts (source of truth) and frontend/types/ws-protocol.ts (frontend copy).

Development

# Frontend
cd frontend && npm install && npm run dev

# Bridge
cd bridge && npm install && npm run dev

# Type check
cd frontend && npx tsc --noEmit
cd bridge && npx tsc --noEmit

# Tests
cd frontend && npx vitest run
cd bridge && npx vitest run

# E2E (requires frontend + bridge running)
cd frontend && npx playwright test

Key Design Decisions

1. pi-coding-agent over Claude Agent SDK -- multi-provider, cheaper, TypeScript, RPC mode with stdin/stdout JSON lines
2. OpenRouter over direct provider APIs -- 461 models, 10x cheaper default with MiniMax M2.5, single API key
3. Filesystem as memory -- agent reads/writes markdown files, pi handles session compaction, SQLite for structured metadata
4. Workspace grid over canvas -- mobile-friendly, faster to build, task-oriented UX
5. Bridge translates, pi executes -- bridge converts pi RPC events to workspace events, handles task/file/skill CRUD without touching the agent
6. Per-user sprite singletons -- one active sprite connection per user, shared across browser tabs
7. Message buffering during wake -- queue up to 50 messages (60s TTL) while sprite wakes from CRIU checkpoint
8. Flat protocol messages -- no payload nesting, all data at top level for simplicity
9. API key proxy -- sprites never hold API keys, bridge injects them server-side to prevent prompt injection credential theft
10. Lazy provisioning -- VMs created on-demand during signup, bootstrap scripts run once, lazy updates on reconnect