> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cadenzalabs.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-robot coordination

> Connect robots into one terminal so they can message each other and split a goal — over MCP.

`cadenza.connect(...)` wires two or more robots into a single **coordination
terminal** so they can talk to each other and share one human goal. It reuses
each robot's user-facing narration channel for robot↔robot messages, routed
through a [FastMCP](https://github.com/jlowin/fastmcp) server under the hood.

```python theme={null}
import cadenza_lab as cadenza

go1, g1 = cadenza.go1(), cadenza.g1()

with cadenza.connect(go1, g1) as term:
    go1.comm.tell("g1", "I'll scout left, you hold position")
    g1.comm.broadcast("copy that")
    print(g1.comm.messages())
```

<Note>
  FastMCP is an optional extra. Install it with `pip install "cadenza-lab[mcp]"`.
</Note>

## `connect()`

```python theme={null}
connect(*robots, narrate=True, out=None) -> CoordinationTerminal
```

Pass the robot controllers you want to link. The returned `CoordinationTerminal`
is a context manager (it owns the MCP server for the session); each robot passed
in gains a `.comm` link.

| Param     | Description                                                           |
| --------- | --------------------------------------------------------------------- |
| `*robots` | The robot controllers to connect (`go1`, `g1`, `arm`, …).             |
| `narrate` | Echo coordination messages to the narration channel (default `True`). |
| `out`     | Optional stream to write narration to.                                |

```python theme={null}
term.robots         # the connected robot identifiers
term.history()      # the full message log for the session
term.close()        # tear down (handled automatically by `with`)
```

## Robot-to-robot messaging

Each connected robot exposes a `.comm` link:

| Method                                | Description                                    |
| ------------------------------------- | ---------------------------------------------- |
| `robot.comm.tell(recipient, message)` | Send a direct message to one robot by id.      |
| `robot.comm.broadcast(message)`       | Send a message to every other connected robot. |
| `robot.comm.messages()`               | Return the messages this robot has received.   |

```python theme={null}
with cadenza.connect(go1, g1) as term:
    go1.comm.tell("g1", "obstacle ahead, going around right")
    g1.comm.broadcast("holding at the doorway")
    for msg in g1.comm.messages():
        print(msg["from"], "→", msg["text"])
```

## Splitting one goal across robots

`term.coordinate(goal)` takes a single human goal and splits it into per-robot
subgoals, then delegates each over the MCP. Routing is by **explicit target**
(name a robot in the goal), then **capability** (match the subtask to what each
robot can do), then **round-robin**.

```python theme={null}
with cadenza.connect(go1, g1) as term:
    term.coordinate("scout the room and then both meet at the door")
    # -> go1 gets the scouting subgoal, g1 gets the hold/meet subgoal
```

```python theme={null}
coordinate(goal: str, *, route_by_capability: bool = True)
```

Set `route_by_capability=False` to fall back to simple round-robin assignment.

```mermaid theme={null}
flowchart LR
    GOAL["goal: 'scout the room,<br/>then meet at the door'"] --> COORD[term.coordinate]
    COORD -->|target / capability / round-robin| SPLIT{split}
    SPLIT -->|subgoal A| GO1[go1.comm]
    SPLIT -->|subgoal B| G1[g1.comm]
    GO1 -. messages .-> G1
    G1  -. messages .-> GO1
```

## Demo: two robots, one goal

```python theme={null}
"""demo_coordination.py: connect two robots and split a goal over MCP.
Requires the mcp extra:  pip install "cadenza-lab[mcp]"
"""
import cadenza_lab as cadenza

go1, g1 = cadenza.go1(), cadenza.g1()

with cadenza.connect(go1, g1) as term:
    term.coordinate("one of you scout left while the other holds the doorway")
    go1.comm.broadcast("left flank clear")
    print("log:", term.history())
```

```bash theme={null}
python demo_coordination.py
```

<Card title="Drive each robot" icon="dog" href="/sdk/robots">
  The `go1` / `g1` / `arm` controllers each robot in the terminal drives.
</Card>