Agents working together

Wires decide which agents, notes and browser portals can work together. Agents then hand each other tasks with the cuewire command. This page shows how to wire a team and what each wire allows.

Figure: What each kind of wire shares. Writer has no wire, so Builder can’t reach it.

Wires

A wire connects two nodes on the canvas. One end of a wire is always an agent (a terminal).

Nothing is shared without a wire. An agent can’t reach an agent, note or portal that it is not wired to.

Draw a wire:

1. Point at a node, or select it. Small handles appear at the middle of each side.
2. Drag from a handle to another node. The wire appears when you let go.

Figure: Drag from a handle to the other node.

Remove a wire: right-click it and choose Disconnect. Or click it and press Delete.

Figure: A small team. Lead hands out tasks; Builder and Reviewer share the Plan note.

Tasks

Agents give each other work with the cuewire command, in their own terminal. For example, an agent runs:

cuewire ask Reviewer "Review the change in src/parser.rs"

This gives the task to the agent named Reviewer and waits for its result, for up to ten minutes. cuewire send gives a task without waiting. It prints the task’s id, and cuewire wait <id> gets the result later.

You don’t need to type these commands yourself. Ask an agent in plain words, for example “Ask Reviewer to check the parser change.” The agent runs the command.

Figure: A task’s life, from cuewire ask to cuewire result.

What happens to a task:

1. Sent. An agent runs cuewire ask or cuewire send.
2. Delivered. Cuewire types the task into the receiving agent’s terminal. It starts with [cuewire] Task <id> from <sender>, and says how to report back.
3. Working. The receiving agent does the work.
4. Done. The agent reports with cuewire result <id> <summary>. Only this completes the task. The result goes back to the sender: cuewire ask prints it, and the sender’s terminal also gets it as [cuewire] Result for Task ….

A task can also go another way:

• Held: the receiving agent is at a usage limit. The task waits and goes out when the limit clears. See Usage and limits.

• Failed: the task ends without success. This happens when:

  • the agent reports cuewire result --failed <id> <why>;
  • the task runs out of its time or tokens;
  • its sender cancels it with cuewire cancel <id>.

  In the last two cases, the agents working on it are told to stop.

Figure: A task, typed into the Builder’s terminal.

Note

Cuewire never types a task into a plain Shell, where the text would run as commands. A script in a Shell gets its tasks with cuewire next instead.

Give a task a contract

For bigger work, the sender can add a contract: rules the task must meet.

A task that an agent sends while it works on another task is a hand-off. It shares that task’s time and its limit on rounds.

Figure: The sender gets the result in its own terminal.

Notes

A note wired to an agent is shared memory. Agents use it to keep plans, decisions and findings where other agents and you can see them.

• An agent reads it with cuewire note read.
• It adds to it with cuewire note append, replaces it with cuewire note write, or changes one part with cuewire note edit.
• The canvas shows the new text right away. If the text no longer fits, the note grows taller.

To make a note read-only for agents, right-click it and choose Lock. Agents can still read it, but not change it.

If an agent changes a note while you edit it, your edits are not lost. The note’s header says Changed by an agent, and Cuewire won’t save over the agent’s text. To take the agent’s version, right-click the note and choose Discard my edits. See Terminals, notes and shapes.

Browser portals

An agent wired to a portal can drive its web page with cuewire portal commands. It can open an address, read what is on the page, click, fill in fields, press keys and take screenshots. It can also open, switch and close the portal’s tabs, and go back, forward and reload.

When an agent clicks or types in a portal, a purple cursor shows where it acted. Your own clicks don’t draw it.

Page text is data from the web. The cuewire skill tells agents never to follow instructions they read on a page.

Portals keep their own sign-ins, can have tabs, and open popups as portals of their own. See Browser portals.

The orchestrator

An orchestrator is an agent that builds the team for you. It can add agents, notes and portals, wire them together, and remove agents.

1. Right-click an agent. Under Agent, choose Orchestrator. A check mark shows it is on. You can also turn it on in Configure….
2. If the agent is running, right-click it and choose Restart. It learns its new job when it starts.
3. Tell it what you need in plain words, for example “Set up a builder and a reviewer for the parser work.”

Before it adds an agent, the orchestrator asks you which agent to run (Claude Code, Codex and so on). New agents appear around it, already wired to it. It can give them a role, such as Builder or Reviewer: a built-in role or one of your own.

Only the orchestrator can change the canvas. Agents it adds never become orchestrators themselves. It needs Cuewire open, with this canvas, to change it.

Figure: Lead, an orchestrator, added Builder and Reviewer and wired them to itself.

Note

An agent learns that it is the orchestrator from instructions Cuewire gives it at launch. Claude Code, Codex, Grok and Copilot CLI take these instructions. Gemini CLI, OpenCode and Antigravity don’t, so don’t use them as an orchestrator.

How agents learn the cuewire command

Cuewire sets up each agent so it can work with the others:

• Every terminal on the canvas has the cuewire command on its PATH.
• Cuewire installs a skill named cuewire, which explains the command to agents. A skill is a short guide an agent reads when it needs it. Cuewire puts it in the skills folder of each agent you have: ~/.claude/skills, ~/.codex/skills, ~/.config/opencode/skills and ~/.agents/skills. It refreshes the skill each time it starts.
• Each task typed into a terminal also says how to report back.

The full list of commands is in the cuewire CLI reference.

Note

To stop Cuewire from installing the skill, for example on a managed computer, set the environment variable CUEWIRE_NO_SKILLS=1 before you start Cuewire.

Gemini CLI with variable redaction

Gemini CLI can hide environment variables that look like secrets from the commands it runs. Its security.environmentVariableRedaction.enabled setting turns this on.

Cuewire gives each agent three variables: CUEWIRE_BRIDGE_SOCKET, CUEWIRE_PEER_ID and CUEWIRE_PEER_TOKEN. With redaction on, Gemini hides the token, and two things stop working:

• Cuewire no longer hears when a Gemini agent finishes or asks something. It reads the agent’s screen instead, which is slower and less exact.
• The agent can’t give or take tasks.

To keep redaction on and Cuewire working, allow the three variables in Gemini’s settings:

{
  "security": {
    "environmentVariableRedaction": {
      "enabled": true,
      "allowed": ["CUEWIRE_BRIDGE_SOCKET", "CUEWIRE_PEER_ID", "CUEWIRE_PEER_TOKEN"]
    }
  }
}

The token only lets that agent act as itself, through its own wires on the canvas.

What’s next

• Roles, models and options
• Usage and limits
• cuewire CLI reference