Core Concepts

The building blocks of a Clustr workspace — explained simply.

Agents

An agent is an AI assistant that works on your code. When you spawn an agent, Clustr launches a coding AI (like Claude or Codex) in its own terminal and gives it a task to work on.

Each agent gets:

• Its own terminal with full access to your project files
• A name you choose (e.g., frontend-refactor)
• A task that tells it what to do
• Built-in tools to talk to other agents
• A safety snapshot of your code taken before it starts, so you can undo its changes if needed

Agents go through three states: spawning (starting up), running (actively working), and done (finished or stopped). Clustr automatically detects when an agent has stopped working and marks it as done.

Messages

Agents can talk to each other by sending messages. This is how they coordinate — for example, one agent can tell another that it changed an API endpoint, or ask another agent for help.

Messages come in two flavors:

• Direct messages — sent to one specific agent by name (e.g., "Hey test-runner, please re-run the tests")
• Broadcasts — sent to every agent at once (e.g., "Build is passing, everyone can proceed")

All messages are saved and show up in the dashboard's message feed in real time. When an agent receives a message, it gets notified immediately.

Shared context

Think of shared context as a team whiteboard that all agents can see. It's a simple list of labeled notes (key-value pairs) that any agent can add to or read from.

For example, if one agent figures out that the database schema changed, it can write that to shared context. Every other agent can then read that note and adjust their work accordingly — without anyone having to send individual messages.

The dashboard shows the shared context in real time, so you can always see what your agents know.

Rules

Clustr has a shared rules file where you write rules and instructions that apply to every agent. Every agent reads this file when it starts and checks it periodically for updates.

Use it for things like:

• Team rules — "never push directly to the main branch"
• Naming conventions — "use this branch naming format"
• Project notes — "we're in the middle of migrating the auth system"
• Coordination — "Agent A owns the API; check with it before changing endpoints"

You can edit the rules from the dashboard, or any agent can update them too.

Services (Claude & Codex)

A service is which AI coding tool an agent uses. Clustr currently supports two:

You can mix and match — run Claude agents and Codex agents in the same workspace. They all use the same messaging and shared context system, so they can collaborate regardless of which AI powers them.

Built-in collaboration tools

Every agent automatically gets a set of built-in tools that let it interact with the Clustr workspace. These tools let agents:

• Register themselves and announce what they're working on
• See who else is in the workspace
• Send and receive messages
• Read and write shared context
• Spawn new agents to delegate work

You don't need to configure these — Clustr sets them up automatically for every agent it spawns.