Agent Coordination

DorkOS provides three subsystems that work together to coordinate multiple AI agents: Relay handles messaging, Mesh handles discovery and identity, and Tasks handles scheduling. This guide covers practical patterns for combining them to build multi-agent workflows.

For Relay internals — message envelopes, budget enforcement, delivery pipeline — see Relay Messaging.

Multi-Agent Project Setup

A typical multi-agent setup involves several agents working on different parts of a codebase: a backend API, a frontend client, an infrastructure layer. Each gets its own agent with specialized context.

Registering Agents

Enable Relay, then start DorkOS:

export DORKOS_RELAY_ENABLED=true
dorkos --dir /path/to/projects

Open the Mesh panel and trigger a discovery scan. Mesh walks your project directories looking for agent markers (.claude/, .cursor/, .dork/agent.json, and others). Each discovered project appears as a candidate to approve or deny.

Once registered, each agent gets:

• A unique ID in the Mesh registry
• A Relay endpoint at relay.agent.{namespace}.{agentId}
• A namespace derived from its filesystem location

For example, with /home/user/projects as the scan root:

/home/user/projects/backend/api/      -> namespace: backend, agent: api
/home/user/projects/backend/worker/   -> namespace: backend, agent: worker
/home/user/projects/frontend/web/     -> namespace: frontend, agent: web

Access Rules

Mesh enforces a three-tier priority scheme on inter-agent communication:

Agents in the same namespace (backend) can communicate without any configuration. Cross-namespace communication (backend to frontend) requires an explicit allow rule:

# Allow backend agents to message frontend agents
curl -X PUT http://localhost:4242/api/mesh/topology/access \
  -H 'Content-Type: application/json' \
  -d '{"sourceNamespace": "backend", "targetNamespace": "frontend", "action": "allow"}'

Access rules are unidirectional. To enable two-way communication, add a second rule with the namespaces swapped.

Agent-to-Agent Messaging

Once agents are registered and access is configured, they communicate through Relay subjects. When a message arrives on a relay.agent.* subject, the Claude Code adapter creates or resumes a Claude session in the target agent's working directory and passes the message as a prompt.

Direct Messaging

An agent sends a message to another by publishing to its Relay subject — available through the MCP tool server injected into every Claude session:

Agent "api" notifies "web" about an API change:

> Use relay_send to tell the frontend agent about the new /users endpoint.
> Subject: relay.agent.frontend.web
> Content: "I added a GET /users endpoint that returns { id, name, email }.
>           Please update the UserList component to fetch from this endpoint."

The Claude Code adapter receives this, starts a session in the web agent's working directory, and passes the content as a prompt. The web agent processes the request with full access to the frontend codebase.

Request-Reply

For conversations where an agent needs a response, set the replyTo field:

Agent "api" asks "web" a question:

> Use relay_send with replyTo set to relay.agent.backend.api
> Subject: relay.agent.frontend.web
> Content: "What TypeScript interface do you use for the User type?
>           I want to make sure the API response matches your expectations."

The web agent's response routes back to relay.agent.backend.api automatically.

Scheduled Coordination with Tasks

Tasks adds time-based automation to agent coordination. When Relay is enabled, Tasks dispatches through the Relay bus rather than calling agents directly — so scheduled tasks follow the same access rules and budget limits as manual messages.

Nightly Code Review

{
  "name": "nightly-review",
  "cron": "0 2 * * *",
  "timezone": "America/New_York",
  "prompt": "Review all files changed today. Check for: missing error handling, untested code paths, inconsistent naming. Create a summary report.",
  "cwd": "/home/user/projects/backend/api"
}

Chained Workflows

Combine scheduled triggers with agent-to-agent messaging for multi-step pipelines. For example, a deployment pipeline:

1. Tasks triggers a test run at 6 AM on the backend agent.
2. Backend agent runs the test suite. If all pass, it uses relay_send to notify the infrastructure agent.
3. Infrastructure agent builds the Docker image and deploys to staging.
4. Infrastructure agent notifies all agents that staging is updated.

Each step executes in the correct working directory with the right codebase context, because Mesh tells the Claude Code adapter where each agent lives.

Use Cases

Monorepo with Specialized Agents

A monorepo with apps/api, apps/web, and packages/shared benefits from three agents, each with deep context about their slice of the codebase.

Setup: Register each app directory as an agent via Mesh discovery. They all land in the same namespace (derived from the monorepo root), so they can communicate without extra access rules.

Workflow: When you ask the API agent to add a new endpoint, it implements the route and messages the web agent to create the corresponding frontend hook. If shared types need updating, either agent can message the other about the required change.

Outcome: Each agent operates with full context of its own codebase slice, but can coordinate changes across boundaries through Relay rather than trying to edit code in unfamiliar directories.

Cross-Repository Coordination

When your system spans multiple repositories, each gets its own namespace.

Setup: Register agents from each repository. Add cross-namespace access rules between backend and frontend, and between both and the deployment namespace.

Workflow: The backend agent finishes an API change and publishes the new OpenAPI spec to Relay. The frontend agent receives it, generates updated API client code, and runs its own tests. Once both are green, either agent notifies the deployment agent to trigger a release.

Human-in-the-Loop via Telegram

Connect a Telegram adapter so agents can escalate decisions and receive approvals from outside the development environment.

Setup: Configure the Telegram adapter in Relay settings with your bot token. Messages from your Telegram chat arrive on relay.human.telegram.{chatId}.

Workflow: A Tasks-scheduled job runs a database migration check. The agent finds a migration that would drop a column with existing data. Instead of proceeding, it sends a message to your Telegram chat asking for confirmation. You reply "approved", the message flows back through Relay, and the agent continues.

Outcome: Critical decisions stay under your control even when agents are operating on schedule. Telegram gives you a natural interface for quick approvals without opening the DorkOS UI.

Next Steps