Architecture Overview

Agor is a multi-client agent orchestration platform with real-time collaboration, built on a local-first daemon architecture.

System Architecture

Technology Stack

Backend

• FeathersJS - Unified REST + WebSocket API framework
• Drizzle ORM - Type-safe database layer with LibSQL support
• LibSQL - Local SQLite-compatible database (future: cloud sync via Turso)
• simple-git - Git operations for worktree management

Frontend

• React 18 + Vite - Fast development with HMR
• Ant Design - Enterprise UI component library
• React Flow - Interactive session canvas with drag-and-drop
• Socket.IO Client - Real-time WebSocket connection

CLI

• oclif - Enterprise-grade CLI framework

Agent Integration

• @anthropic-ai/claude-agent-sdk - Claude Code capabilities with CLAUDE.md auto-loading
• OpenAI SDK - Codex integration with custom permission system
• Google Generative AI SDK - Gemini integration (beta)

Real-Time Multiplayer

Agor achieves multiplayer collaboration through FeathersJS real-time events:

WebSocket Event Flow

Key Features:

• Automatic broadcasting - FeathersJS emits events to all connected clients
• Service-level events - created, patched, removed, updated
• Custom events - Cursor position, presence updates (100ms throttle)
• Optimistic UI - React hooks listen to events and update state immediately

Core Services

The daemon exposes 12 FeathersJS services via REST and WebSocket:

MCP Integration: Self-Aware Agents

Agor exposes itself as a Model Context Protocol (MCP) server, enabling agents to introspect and manipulate their own environment.

Why MCP?

Instead of parsing CLI output:

# ❌ Brittle approach
$ agor session list | grep running | wc -l

Agents use structured MCP tools with typed responses:

// ✅ Structured approach
→ agor_sessions_list({ status: 'running' })
← { total: 3, data: [...] }

HTTP Transport

Endpoint: POST /mcp?sessionToken={token} Protocol: JSON-RPC 2.0

Each session gets a unique token on creation (24h expiration), automatically injected into the agent’s MCP config:

mcpServers: {
  agor: {
    type: 'http',
    url: 'http://localhost:3030/mcp?sessionToken=cd5fc175...'
  }
}

Available Tools (First Batch - Read-Only)

Example Agent Workflow

User: "What other sessions are running on this board?"

Agent thinking:
→ agor_sessions_get_current()
← { session_id: "019a1...", board_id: "019a2...", status: "running" }

→ agor_sessions_list({ boardId: "019a2...", status: "running" })
← { total: 3, data: [
    { session_id: "019a3...", agentic_tool: "claude-code", title: "Schema design" },
    { session_id: "019a4...", agentic_tool: "claude-code", title: "API implementation" }
  ]}

Agent: "There are 2 other sessions running on this board:
       - Session 019a3... (Claude Code, schema design)
       - Session 019a4... (Claude Code, API implementation)"

Service Layer Integration

MCP tools route through FeathersJS services (not direct ORM) for:

• ✅ Consistent business logic
• ✅ Hook execution (validation, auth)
• ✅ Future RBAC support
• ✅ Cross-database compatibility

Future: Write Operations (Second Batch)

Planned tools for multi-agent orchestration:

• agor_sessions_create - Create new session
• agor_sessions_spawn - Spawn child session (subtask delegation!)
• agor_sessions_fork - Fork session at specific point
• agor_boards_create - Create new board
• agor_worktrees_create - Create new worktree

This will enable fully autonomous multi-agent workflows.

Data Architecture

Hybrid Schema Strategy

Agor uses a hybrid materialization approach for cross-database compatibility (LibSQL → PostgreSQL):

Materialized Columns (indexed):

• Primary keys, foreign keys, status, timestamps
• Used for filtering, joins, sorting

JSON Blobs (flexible):

• Nested objects (git_state, genealogy, config)
• Arrays (tasks, contextFiles, children)
• Rarely queried metadata

Benefits:

• Migration-free schema evolution
• Fast indexed queries
• Cross-database compatibility (LibSQL ↔ PostgreSQL)

Worktree-Based Isolation

Every session requires a worktree (foreign key constraint):

~/.agor/
├── agor.db              # Database
├── repos/               # Bare repositories
│   └── myapp/
└── worktrees/           # Session worktrees
    └── myapp/
        ├── main/        # Session 1 worktree
        └── feat-auth/   # Session 2 worktree

Why worktrees?

• Parallel development without branch switching
• Session isolation (no shared working directory)
• Natural mapping for fork/spawn operations

Authentication

Three authentication strategies:

1. Anonymous (default) - No auth required for local development
2. Local (email/password) - JWT-based authentication
3. JWT - Token refresh and validation

All strategies use FeathersJS authentication with configurable storage.

Next Steps

• Getting Started - Install and run Agor
• API Reference - REST endpoints and WebSocket events
• CLI Reference - Command-line interface