Architecture Overview

How AgentDesk is built — Next.js, SQLite, Claude Agent SDK, and the dispatch loop.

AgentDesk is a monolithic application that combines a web dashboard, API server, WebSocket hub, and autonomous agent dispatcher into a single process.

Tech Stack

Process Architecture

When you run agdesk start, a single Node.js process starts that runs:

1. HTTP Server — serves the Next.js frontend and REST API
2. WebSocket Hub — handles real-time chat streaming and status updates
3. Proactive Dispatcher — autonomous setTimeout loop that assigns work to agents
4. Session Pool — manages Claude Code SDK sessions for all agents
5. Scheduler — fires cron jobs and one-shot triggers
6. File Watcher — monitors project directories for changes

All components share a single SQLite database and communicate through in-memory events.

Data Flow

Browser ─── HTTP ──→ Next.js API Routes ──→ SQLite
   │                                           ↑
   └── WebSocket ──→ Chat Bridge ──→ Session Pool ──→ Claude Code SDK
                                           ↑
                     Dispatcher ───────────┘
                         ↑
                     Scheduler (cron/interval/one-shot)

Key Design Decisions

Single Process

Everything runs in one process to minimize operational complexity. No Redis, no message queues, no container orchestration. SQLite handles persistence, in-memory Maps handle ephemeral state.

SQLite

SQLite is the perfect fit for a self-hosted tool:

• Zero configuration — it’s just a file
• Handles concurrent reads with WAL mode
• Drizzle ORM provides type-safe queries
• Easy to backup — copy one file

Agent SDK Sessions

Rather than keeping long-lived subprocess connections, AgentDesk uses the Claude Code SDK’s resume feature. Each turn spawns a fresh query() call with the previous session ID, so the conversation context is loaded from disk. This means agent sessions survive process restarts.

Database

The SQLite database contains 27 tables covering:

• Auth — users, sessions, invites
• Projects — projects, members, access control
• Tasks — tasks, subtasks, tags, comments, mentions, activities
• Agents — agent configs, run history
• Scheduling — cron jobs, run history, contexts
• Providers — LLM provider configs (encrypted credentials)
• Integrations — Telegram, Notion connections
• Platform — app config, global settings

See Database Schema for the full table reference.