Know when an agent needs you

Cuewire watches every agent and tells you when one needs you: a question, a request for approval, or a failure. This page explains the signs, and how to answer quickly.

Figure: An agent’s status. Needs you and failed also show in the Needs you rail.

Status dots

Each terminal has a dot at the left of its header. The dot’s colour is the agent’s status. Some statuses also show a word at the right of the header, when the node is wide enough.

A running agent’s dot takes the node’s own colour, if you gave the node one.

When a program rings the terminal bell, the header flashes and the dot turns amber. It stays amber until you click into that terminal.

Figure: Status dots and header words on five agents.

How Cuewire knows: most agents tell Cuewire when they start and finish a turn. They do it through hooks: small reports that Cuewire sets up when it starts the agent. Cuewire also reads the terminal’s screen, for example to spot a question. A plain Shell only reports bells, notifications and when its program exits.

Trust Cuewire’s hooks in Codex

With hooks, Codex tells Cuewire what it wants to do, for example “needs approval: wants to run npm test”. This needs Codex 0.162 or newer. Codex runs hooks only after you trust them.

The first time Cuewire starts Codex, Codex shows Hooks need review. The Needs you rail shows “needs input: Hooks need review”. Tasks from other agents wait until you answer.

1. Click inside the Codex terminal.
2. Press 2 to choose Trust all and continue, then press Enter. To read the hooks first, choose Review hooks instead.

Codex remembers that you trust them and does not ask again. An agent account with its own Codex folder asks once more.

You can also choose Continue without trusting (hooks won’t run). Codex still works. Cuewire then reads Codex’s screen, and the reason is the question there, for example “Would you like to run the following command?”. Codex asks again the next time you open Cuewire.

To trust the hooks later, type /hooks in that Codex terminal and press Enter. Then press t.

The Needs you rail

When an agent needs you, the Needs you rail appears at the top right of the canvas. It lists the agents that wait for you, most urgent first:

1. needs approval
2. needs input
3. failed
4. bell rang

Each entry shows the agent’s name and its reason, for example “needs approval: Do you want to run npm test?”. The rail’s title shows how many agents wait, for example Needs you · 3. It lists up to six.

Click an entry. Cuewire brings that agent into view and gives its terminal the keyboard, so you can answer there.

Figure: The Needs you rail. Approve and Deny answer a question without leaving the canvas.

Approve or deny in one step

An entry that asks for approval can have Approve and Deny buttons. They press the agent’s own keys for you:

Grok, OpenCode and Antigravity get no buttons for their own approval menus yet. Click the entry and answer in the terminal.

From the keyboard:

• Ctrl+Shift+Y approves the first question in the rail that has buttons.
• Ctrl+Shift+N denies it.

On a Mac, use Cmd+Shift+Y and Cmd+Shift+N. A message names the agent, for example “Approved Worker”.

Note

These keys work when the canvas has the keyboard. While you type in a terminal, every key goes to the program. Press Shift+Esc first to leave the terminal.

Warning

Approve lets the agent do what it asked, such as run a command. Read the reason first. If it is cut short, click the entry and read the whole question in the terminal.

You can also answer from your phone. See Your phone as a companion.

Notifications and sounds

When an agent’s status changes while you are not looking, Cuewire shows a system notification. “Not looking” means Cuewire is in the background, or the agent’s node is off the screen. The notification’s title is the agent’s name:

At the same time, Cuewire plays a short sound:

• a tap when an agent is done;
• a lower tone when it fails;
• a double tap when it needs you.

Sounds are on at first, at a quiet volume.

To change them, press Ctrl+K and run one of these commands:

• Turn sound cues off (or Turn sound cues on)
• Sound volume: quiet, Sound volume: medium or Sound volume: full

While you were away

Your agents keep working while you are away. When you come back to Cuewire after five minutes or more, the While you were away panel opens at the top left of the canvas.

It sums up what each agent did since you left, with how long ago, for example:

• finished a turn
• asked for approval: …
• asked: …
• failed: …
• exited

It shows up to ten events per agent. Click Dismiss to close it.

The panel also works when you quit Cuewire. Agents keep running in Cuewire’s background service, and the panel shows what they did when you open Cuewire again.

Figure: The While you were away panel.

What’s next

• Agents working together
• Usage and limits
• Your phone as a companion