Let your agents message each other and hand off work, instead of copying context between chat windows yourself

Coordinating Multiple Agents

If you run one agent per project, DorkOS lets those agents talk to each other directly. Your backend agent finishes an endpoint and tells your frontend agent to build the UI for it, without you copying the details over by hand.

Three pieces make this work: Mesh finds your agents and gives each one an id, chats carry the messages between them, and Tasks can start work on a schedule instead of waiting for you to ask.

Every message one agent sends another lands in a chat you can open. It is marked with the agent and the chat that sent it, so you can always see who asked for what.

This is a shipped capability we are still hardening end to end. Multi-agent messaging works in the setups we've tested, but treat it as early: watch what an agent actually does with a handoff before you trust it with something you can't easily undo.

Quick win: send one message between two agents

Start DorkOS pointed at the folder that holds your projects:
```
dorkos --dir /path/to/projects
```
Open the Mesh panel and run a discovery scan. Mesh walks your project folders looking for agent markers (things like a .claude/ folder or a .dork/agent.json file) and lists each project it finds as a candidate. Approve the ones you want; deny the rest. If the scan comes back empty, check that --dir points at the parent folder that actually contains your projects, not a project itself.
Open a chat with one approved agent and ask it to message another:

Tell the frontend agent about the new /users endpoint.
Watch the message arrive. The agent sends it with its chat_send tool. It lands in a chat between the two agents, and the receiving agent starts working on it. Open that chat to read the message, marked with who sent it.

That is the whole loop: discover, approve, send, watch it land. Everything past this point is reference material for when you want spin-off chats, schedules, or the exact tools.

What this looks like in practice

A monorepo with one agent per app

Say you have apps/api, apps/web, and packages/shared. Register each folder as an agent through Mesh discovery, and they can message each other with no extra setup.

Ask the API agent to add an endpoint, and in a working setup it implements the route, then messages the web agent to build the matching frontend hook. If a shared type needs to change, either agent can flag it to the other instead of reaching into a codebase it doesn't own.

Agents across separate repositories

When your backend and frontend live in different repositories, the agents can still message each other's chats. The backend agent sends the frontend agent an updated API spec, the frontend agent regenerates its client code, and once both report green, either one can tell a deployment agent to ship. That's the intended workflow: verify it against your own agents before you let it run unattended.

Handing off long work to a spin-off chat

When an agent has work that will take a while, like waiting on a CI run or a deploy, it can start a spin-off chat to do it. The spin-off is a full chat you can open, read and type in, and it reports back to the chat that started it on its own. See Spin-off chats.

Approving decisions from your phone

If you connect Telegram on the Connections page, agents can send you a message outside the DorkOS UI and wait for your reply before continuing, useful for anything you'd rather approve by hand.

Picture a nightly task that checks for risky database migrations. It finds one that would drop a column with real data in it, so instead of running it, it messages your Telegram chat and waits. You reply "approved" from your phone, and the agent picks up where it left off. Nice way to keep the final call human without opening a laptop.

Reference

The rest of this page is for the curious: exact API calls, priority numbers, and message formats. Skim it once, then come back when you need a specific detail.

Registering agents

Once a discovery scan approves a project, each agent gets:

A unique ID in the Mesh registry, which is what another agent sends to
A Relay address (a subject) shaped like relay.agent.{namespace}.{agentId}, used by programs and outside agents that reach it over Relay
A namespace derived from where it sits on disk

For example, scanning /home/user/projects might produce:

/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

Access rules decide which messages can travel over Relay between namespaces: messages from programs, from outside agents over A2A, and from scheduled tasks. They do not limit your own agents messaging each other's chats: any of your agents can message any of your chats, and every message shows who sent it.

Mesh checks every Relay message between agents against a priority-ordered list of rules:

Priority	Rule	Effect
200	System-agent allow	The system agent (DorkBot) can always reach any namespace
100	Same-namespace allow	Agents in the same namespace talk freely by default
50	Cross-namespace allow	Explicit rules you add
10	Cross-namespace deny	The catch-all: blocks anything not explicitly allowed

Agents in the same namespace (say, backend) need no configuration. Cross-namespace traffic (backend to frontend) needs 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"}'

Rules are one-directional. For two-way communication, add a second rule with the namespaces swapped.

Let all my agents talk to each other

Pairs add up fast: five namespaces need twenty rules for everyone to reach everyone over Relay. If you'd rather not think about walls at all, Team → Access has a single switch, Let all my agents talk to each other. Turn it on and every Relay message between agents on this machine is allowed, whatever project it lives in. Turn it off and you are back to the defaults, with any pairs you added still exactly where you left them.

It is on when you install DorkOS, so your agents can message each other whatever project they live in. Turn it off and it stays off: DorkOS turns it on once, and never again. Behind the scenes it is one more rule, at the same priority 50, using * on both sides:

# The switch, from the command line
curl -X PUT http://localhost:4242/api/mesh/topology/access \
  -H 'Content-Type: application/json' \
  -d '{"sourceNamespace": "*", "targetNamespace": "*", "action": "allow"}'

GET /api/mesh/topology reports it as openMesh, and so does an agent's own mesh_query_topology tool. * has to be on both sides or neither — a half-wildcard is rejected.

Messaging another agent

Every agent DorkOS runs has its DorkOS tools, and three of them are for talking to other chats:

Tool	What it does
`chat_send`	Send a message to a chat, or to another agent (it goes into the two agents' own direct chat).
`chat_read`	Check on a chat: whether it is working, done or needs you, and what is new since last time.
`chat_stop`	Stop a chat's running turn, like pressing its Stop button.

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

> chat_send to: web
> message: "I added a GET /users endpoint that returns { id, name, email }.
>           Please update the UserList component to fetch from it."

The web agent works on it in its own folder, with the same context it always has. Its answer comes back as a new message in the api agent's chat, so nobody has to wait or keep checking.

A few things hold for every message:

You can see it. It lands in a chat you can open, marked with the agent and the chat that sent it, never as you.
It waits its turn. A message waits until the other chat finishes what it is doing. An agent can choose to steer a running turn instead, or stop it and start on the new message. Anything you typed there yourself runs ahead of waiting agent messages.
Nobody can fake the sender. DorkOS stamps who sent each message. An agent cannot claim to be another agent, or you.

Nothing limits how long two agents can keep messaging each other. You can see it in both chats and stop either one. Each round uses your plan's usage, so keep an eye on agents you set talking to each other for long stretches.

Scheduling messages with Tasks

Tasks can start work instead of waiting for a person to ask. When Relay is on, a scheduled task dispatches through Relay, so it follows Relay's access rules and budget limits.

A task is a SKILL.md file (a small text file with a YAML header) with a name, a cron schedule, a timezone, and a prompt written below the header:

---
name: nightly-review
display-name: Nightly Code Review
description: Review the day's changes and flag anything risky
cron: '0 2 * * *'
timezone: America/New_York
enabled: true
---
Review all files changed today. Check for missing error handling,
untested code paths, and inconsistent naming. Create a summary report.

Creating a task from the Tasks panel (or via POST /api/tasks with name, description, prompt, cron, timezone, and a target agent) writes exactly this file to disk; DorkOS never asks you to hand-edit JSON. Set the cron for the middle of the night on a machine that stays on, and you come back to a report, not a fire.

Chaining tasks and messages

Combine a scheduled trigger with agent-to-agent messages for a multi-step pipeline. A deployment pipeline might look like:

Tasks triggers a test run on the backend agent at 6 AM.
Backend agent runs the suite. If it's green, it uses chat_send to tell the infrastructure agent.
Infrastructure agent builds the image and deploys to staging.
Infrastructure agent tells the agents that need to know that staging is updated.

Each step runs in the right working directory because Mesh already told DorkOS where each agent lives.

Agent Coordination