Circulo

Local multi-agent orchestrator — run several coding agents at once on your PC, control them from desktop and phone.

One circle. Many agents. Full control.

Status

Phase 0.1 — monorepo scaffold in place.
Next: protocol expansion + fake adapter sessions (Phase 1), then real adapters.

See docs/IMPLEMENTATION-PLAN.md.

---

Table of Contents

• Quick start
• Configuration
• RPC (WebSocket)
• Product snapshot
• Architecture
• Monorepo layout
• Docs
• Development
• Project skills
• License

---

Quick start

bun install
bun test                 # includes WS integration (fake agent)
bun run dev:server       # watch mode
# → http://127.0.0.1:7420/health
# → ws://127.0.0.1:7420/v1/ws?token=<bootstrap>
# Bootstrap token: ~/.circulo/bootstrap-token

Run once (no watch):

bun run start:server

Desktop

bun run dev:desktop      # Tauri + Vite (requires Rust + Xcode CLT)

---

Configuration

Config is created on first run under ~/.circulo/:

Path	Purpose
~/.circulo/config.json	host/port, pairing defaults, agent bins
~/.circulo/bootstrap-token	WS auth (reused across restarts)
~/.circulo/circulo.db	SQLite sessions/messages/permissions

Precedence: env > config.json > defaults.

Var	Default
CIRCULO_HOST	from config / 127.0.0.1
CIRCULO_PORT	from config / 7420
CIRCULO_AUTH_TOKEN	existing bootstrap-token or random
CIRCULO_DB_PATH	~/.circulo/circulo.db

---

RPC (WebSocket)

Connect with token, then JSON-RPC style messages { id, method, params }.
Server pushes { type: "event", event } for stream/permission updates.

Core methods: hello, agents.list, sessions.create|list|get|close|subscribe, chat.send, chat.interrupt, permissions.respond, permissions.listPending, server.status.

---

Product snapshot (MVP)

Piece	Choice
Orchestrator	Bun + TypeScript (separate process)
Desktop	Tauri 2 + React
Mobile	React Native + Expo (remote control)
Agents	OpenCode + Command Code (own adapters, not ACP)
Comms	WebSocket + typed RPC (Zod)
Data	SQLite under ~/.circulo/
Pairing	Local code/QR; remote via Tailscale (optional)

---

Architecture

Desktop / Mobile  ──WebSocket──►  Circulo Server (Bun)
                                      ├── OpenCode adapter
                                      ├── Command Code adapter
                                      ├── Sessions + permissions
                                      └── SQLite

Agents run only on the PC. The phone never executes agent processes.

---

Monorepo layout

packages/protocol      # Zod schemas + shared types
packages/client-core   # Shared client helpers (desktop + mobile)
packages/server        # Bun orchestrator
packages/desktop       # Tauri UI
packages/mobile        # Expo remote (placeholder)
adapters/core          # AgentAdapter interface
adapters/fake          # Test double
adapters/opencode      # Native: opencode serve + SSE
adapters/command-code  # Native: command-code -p JSON stream

Protocol spikes: docs/spikes/.

Live adapter smoke (optional, needs CLIs + auth):

CIRCULO_LIVE=1 bun test adapters/opencode adapters/command-code

---

Docs

Document	Description
docs/PRD.md	Product requirements
docs/TRD.md	Technical design
docs/UX-UI.md	UX / UI
docs/FLOWS.md	User & system flows
docs/IMPLEMENTATION-PLAN.md	Phased delivery
AGENTS.md	Instructions for coding agents

---

Development

bun install
bun run dev:server
bun test
bun run typecheck       # all workspace packages

---

Project skills

Agent skills from skills.sh are installed under .agents/skills/. See AGENTS.md for the list.

npx skills list   # from repo root

---

License

MIT