Architecture
A simple overview of how Clustr is built and how the pieces fit together.
The big picture
Clustr has two main parts:
- The server — the brain that manages agents, handles messages, stores data, and launches AI processes. It runs on your machine and exposes a web API.
- The dashboard — a web app you open in your browser to see what your agents are doing, read their messages, view shared context, and interact with their terminals.
When you run npx clustr-ai, both parts start together. The dashboard talks to the server over a real-time connection, so everything you see updates instantly.
What the server does
The server is made up of several pieces, each handling a specific job:
Agent Spawner
Launches AI coding tools (Claude or Codex) as separate processes, each in its own terminal. It handles the startup sequence automatically — accepting prompts, injecting your task, and connecting the agent to the workspace.
Message Broker
Delivers messages between agents. When Agent A sends a message to Agent B, the broker saves it, pushes it into Agent B's terminal so it sees the notification, and updates the dashboard.
Agent Registry
Keeps track of which agents are alive. Each agent sends periodic "heartbeat" signals. If an agent stops responding for 60 seconds, the registry marks it as done.
Context Store
A shared notepad where agents store and retrieve key-value notes. When any entry changes, the dashboard updates immediately.
Database
A lightweight local database that stores three things: the list of agents, all messages between them, and the shared context entries. Everything is stored in a single file on your machine.
Collaboration Bridge
A small connector that gives each agent its collaboration tools (send messages, read context, spawn agents, etc.). Each agent gets its own bridge that connects it to the workspace.
Git Integration
Before each agent starts, Clustr takes a snapshot of your code (a git checkpoint). Later, you can see exactly what the agent changed (as a diff) or roll everything back to how it was before.
What the dashboard shows
The dashboard is a web app with several views:
| View | What it shows |
|---|---|
| Agent Graph | A visual map of all agents and how they're connected — who is talking to whom |
| Terminal | Live terminal output for each agent — you can watch them work and even type commands |
| Messages | A feed of all messages between agents, updated in real time |
| Context | The shared notepad — see all the notes agents have written for each other |
| Files | A log of file changes happening in your project as agents work |
| Rules | An editor for the shared rules file that all agents follow |
Where Clustr stores things
All of Clustr's data lives in a single folder on your machine (created automatically on first run). This includes:
- The database with agents, messages, and shared context
- The shared rules file
- Temporary config files for each agent (cleaned up automatically)
- Any images you paste into agent tasks
Everything is local. Clustr runs entirely on your machine. No data is sent to external servers (beyond the AI API calls that Claude and Codex make themselves).