Welcome to Cuewire

Cuewire is a desktop app for running several AI coding agents at once. This page explains what it does and the main ideas behind it.

Figure: Agents work on a canvas and share work over wires. When one needs you, Cuewire tells you, on the desktop or on your phone. A background service keeps them running.

What Cuewire is

Coding agents such as Claude Code and Codex run in a terminal. With one agent, one terminal is enough. With five, it is hard to see who is doing what.

Cuewire gives each agent its own terminal on a large canvas. You arrange the terminals like cards on a table. You draw wires between them, so agents can hand work to each other. Cuewire watches every agent and shows you the one that needs you.

Cuewire works with these agents:

• Claude Code
• Codex
• OpenCode
• Grok
• Antigravity
• Copilot CLI (GitHub Copilot CLI)
• Gemini CLI

A terminal can also run a plain shell. There you can start any program you like.

Figure: A canvas with two agents and a note. The Needs you list, top right, shows the agent that is waiting for you.

Who it is for

Cuewire is for developers who already use a coding agent and want to run several. For example:

• one agent builds a feature while another one reviews it;
• two agents try two ideas, each in its own copy of the project;
• you leave agents working and check on them from your phone.

You still need each agent’s own command-line tool. Cuewire runs those tools. It does not replace them.

The main ideas

The canvas

The canvas is a large surface that you pan and zoom. Everything on it is a node: terminals, notes, browser portals, file trees, labels and shapes. Each project in the sidebar is a workspace, and a workspace can hold several canvases.

See Move around the canvas.

Agents

An agent is an AI coding tool that runs in a terminal node. You choose which agent a terminal runs. You can type into it like any terminal, or send it a prompt from Cuewire.

See Add an agent.

Wires

A wire connects two nodes. Wires decide who may work with whom:

• Two wired agents can give each other tasks and wait for the results.
• An agent wired to a note can read and change that note.
• An agent wired to a browser portal can use that web page.

Nothing is shared without a wire.

See Agents working together.

Needs you

Agents often stop and wait. They wait for an answer, or for your approval to run a command. Cuewire notices. The terminal’s title bar says needs input or needs approval. The Needs you list shows every agent that waits, most urgent first.

See Know when an agent needs you.

Layers

A layer is a separate copy of your project for one task. It is a git worktree with its own copy of the canvas. Agents in a layer can try changes without touching your main checkout.

See Projects and layers.

Review

When agents finish their work in a layer, Cuewire helps you check it. Review changes adds a reviewer agent and a review note to the canvas. Then you can commit the changes and open a pull request.

See Review your agents’ work.

Your phone as a companion

Pair your phone with Cuewire. Away from your desk, the phone shows which agents need you, and you can answer them there. Messages between the phone and your computer are end-to-end encrypted.

See Your phone as a companion.

Agents keep running

A background service runs your terminals, not the Cuewire window. Close Cuewire, and your agents keep working. Open it again, and every terminal is still there.

Agents can also run on another machine, over SSH or in WSL. See Remote projects.

See Workspaces and canvases.

Note

Cuewire is new and still growing. This manual describes what the current build does.

What’s next

• Install Cuewire
• Your first canvas
• A tour of the window

Install Cuewire

This page shows how to install Cuewire on Windows, update it and remove it.

Figure: Setup puts the app in %LOCALAPPDATA%\Programs\Cuewire. Your canvases, notes and settings live in %LOCALAPPDATA%\Cuewire. Setup never changes that folder.

What you need

• A 64-bit Windows PC (x86_64).
• The command-line tools of the agents you want to use, such as Claude Code or Codex. Install them on their own. Cuewire runs them, but it does not install them.

Note

Today Cuewire comes as a Windows setup program only. There is no download for macOS or Linux yet. A Linux machine or a WSL distribution can still run your agents as a remote project.

Install on Windows

1. Get the setup program, CuewireSetup-<version>-x86_64.exe.
2. Double-click it.
3. If Windows shows Windows protected your PC, follow the steps in the next section.
4. Wait a few seconds. Setup has no window and asks no questions. Cuewire starts by itself.

Setup does this for you:

• It installs Cuewire for you alone, in %LOCALAPPDATA%\Programs\Cuewire.
• It needs no administrator rights.
• It adds Cuewire to the Start menu.
• It adds Cuewire to the apps list in Windows Settings, so you can remove it later.
• It starts Cuewire.

Next, see Your first canvas.

If Windows says “Windows protected your PC”

Some Cuewire builds are not signed yet. For an unsigned program, Windows SmartScreen shows a warning before the first start.

1. Click More info.
2. Check that the app name is the setup file you downloaded.
3. Click Run anyway.

Warning

Do this only for a setup file that you got from the Cuewire team. If you are not sure where the file came from, click Don’t run and get it again.

If setup fails

Setup writes what it did to %TEMP%\cuewire-setup.log. When something goes wrong, it also shows a message. For example, This setup file is damaged (…). Download it again.

Update Cuewire

Run the setup program of the newer version. It installs over the old version, in the same folder.

1. Quit Cuewire with Ctrl+Q. Your agents keep running in the background service.
2. Run the newer CuewireSetup-<version>-x86_64.exe.
3. Wait a few seconds. Cuewire starts again, and every terminal reconnects.

Your canvases, notes and settings stay as they were. Setup does not stop your agents, even while it replaces files that they use.

Restart the terminal service

The new Cuewire works with the background service that is already running. That service is still the old version. If no terminal is running, Cuewire updates the service by itself. If terminals are running, Cuewire waits for you:

1. In the sidebar, click Update ready · restart 2 terminals (the number matches your terminals).
2. Read the dialog, Update the terminal service? The running terminals stop and start again, in the same folders.
3. Click Restart now (Enter). Or click Later (Esc) to keep working on the old version.

Tip

Pick a moment when your agents are idle. Agents that can resume pick up their last conversation when they start again.

Uninstall Cuewire

1. Open Windows Settings, then Apps.
2. Find Cuewire in the list of installed apps.
3. Choose Uninstall.

Uninstalling removes the app, its Start menu entry and its entry in Settings. If some files are still in use, Windows removes them the next time you sign in.

Your data stays in %LOCALAPPDATA%\Cuewire: canvases, notes, settings and logs. If you install Cuewire again, it finds them.

Note

Uninstalling does not stop agents that are still running. Delete their terminals in Cuewire first.

To remove your data as well, run this in a terminal:

"%LOCALAPPDATA%\Programs\Cuewire\uninstall.exe" --uninstall --remove-data

Warning

--remove-data deletes your canvases, notes and settings for good. Nothing can bring them back.

For scripts

uninstall.exe is in the folder where Cuewire is installed.

What’s next

• Your first canvas
• A tour of the window
• Troubleshooting

Your first canvas

This page takes you through your first few minutes: open your project, add an agent, and give it a first task.

Figure: Cuewire the first time it opens. The Start here card has three steps.

First launch

The first time Cuewire opens, you see:

• the sidebar on the left, with one workspace called Home;
• an empty canvas with the Start here card in the middle.

The Home workspace works in your user folder. For real work, open your project folder first.

Note

Agents start in the project folder of the canvas. They can read and change the files there.

Open your project

1. On the Start here card, click Open a project folder….
2. Choose your project’s folder.
3. Click Use this folder.

Cuewire adds a workspace for the folder to the sidebar. It is named after the folder. Its first canvas opens, with the Start here card again.

Tip

+ Add project at the bottom of the sidebar does the same.

Add an agent

Step 2 of the Start here card lists every agent Cuewire knows. Terminal gives you a plain shell.

1. Click an agent, for example Claude Code.

The agent starts in a new terminal in the middle of the canvas. The terminal is named after the agent, for example Claude Code. It shows Starting… until the program is up.

Figure: A new agent. Its name and a status dot are in the title bar.

An agent that is not on your computer shows (not installed), and you can’t click it. Install its command-line tool first. Then quit Cuewire (Ctrl+Q) and open it again, so Cuewire finds the new tool.

Tip

You can also add a terminal yourself. Press Ctrl+T and click the canvas. Then right-click the terminal and choose an agent under Runs. Cuewire asks before it replaces the shell that is running; press Enter to go ahead.

Give it a first task

The first time an agent starts in a folder, it may ask a question of its own. For example, it may ask whether you trust the folder. Answer it in the terminal first.

You can give the agent a task in two ways.

Type in the terminal

1. Click inside the terminal. Your keys now go to the agent.
2. Type your request and press Enter, as in any terminal.
3. Press Shift+Esc when you are done. The keyboard goes back to the canvas.

Write a prompt

1. Click the terminal’s title bar. This selects the terminal without typing into it.
2. Press Ctrl+Enter (Cmd+Enter on a Mac). The prompt box opens, named Prompt · Claude Code.
3. Write your request. For example: “Read the README and list three small improvements.”
4. Press Enter to send it. Shift+Enter starts a new line.

Cuewire types the prompt into the agent and sends it. A message says Sent to Claude Code.

Figure: The prompt box. Enter sends, Shift+Enter starts a new line, Esc keeps the draft.

Tip

Esc closes the prompt box and keeps what you wrote. It is there the next time you open it.

Watch it work

The agent works in its terminal. You can watch, or do something else. Cuewire tells you when the agent stops:

• The title bar says needs input or needs approval when the agent waits for you.
• It says done when the agent has finished its turn, and failed when something broke.
• The Needs you list appears at the top right. It shows every agent that waits for you. Click an entry to jump to that agent.
• When some agents ask to run a command, the list has Approve and Deny buttons.

If the Cuewire window is in the background, or the agent is off screen, you also get a Windows notification.

Figure: The agent asks for approval. Answer in the terminal, or with Approve or Deny.

See Know when an agent needs you for the details.

Connect a second agent

Agents can work together when you wire them. Step 3 of the Start here card says how: drag from one node’s edge to another. The card is gone once the canvas has a node, so do it like this:

1. Right-click an empty part of the canvas and choose New terminal here.
2. Right-click the new terminal. Under Runs, choose an agent, for example Codex. Press Enter when Cuewire asks to restart the terminal.
3. Point at the first agent. Small round handles appear on its four edges.
4. Drag from a handle to the new agent, and let go.

A wire now joins the two agents. They can hand each other tasks. See Agents working together.

Close Cuewire whenever you like

Your agents keep working when you close the window. Open Cuewire again, and every terminal is still there. See Workspaces and canvases.

What’s next

• A tour of the window
• Move around the canvas
• Add an agent

A tour of the window

This page names every part of the Cuewire window and says what it is for.

Figure: The Cuewire window. 1 sidebar, 2 canvas, 3 toolbar, 4 layer chip, 5 Needs you list, 6 usage chip, 7 zoom controls, 8 account button.

On a Mac, Cuewire uses Cmd where this page says Ctrl.

The sidebar

The sidebar on the left lists your projects.

• Each project is a workspace. Click a workspace to fold or unfold it.
• Under each workspace are its canvases. Click one to open it.
• The + on a workspace’s row adds a canvas to it.
• Double-click a workspace or a canvas to rename it.
• Drag a row to change the order.

At the bottom of the sidebar:

• the account button (see below);
• + Add project, to open a project folder as a new workspace;
• + Remote project (SSH or WSL), to work on another machine. See Remote projects.

Press Ctrl+B to hide the sidebar or show it again. See Workspaces and canvases.

The canvas

The canvas fills the rest of the window. It is a large surface with a grid of dots. Your terminals, notes and other nodes sit on it, joined by wires. An empty canvas shows the Start here card.

Short messages from Cuewire appear at the top of the canvas, for example View 3 saved · Alt+3 returns here. They go away when you click the canvas or press Esc.

See Move around the canvas.

The toolbar

The toolbar sits at the bottom of the canvas. It has one tool for each kind of node you draw:

Figure: The toolbar. The active tool is highlighted.

To use a tool:

1. Click the tool, or press its key.
2. Click the canvas for a node of the usual size. Or drag to draw the size you want.

The toolbar goes back to Select after each node. Press Esc to stop without adding one.

See Terminals, notes and shapes.

The layer chip

The layer chip is at the top left of the canvas. It shows Layer and the name of the layer you are in, for example Layer Base. Base is your project folder itself.

Click the chip to open its menu:

• the canvas’s layers, to switch between them;
• New layer from this one;
• in a layer other than Base: Review changes, Commit all changes, Open pull request, and Archive to leave the layer.

A layer is a separate copy of your project for one task. See Projects and layers.

The Needs you list

The Needs you list appears at the top right when an agent waits for you. Its heading counts them, for example Needs you · 2. Click an entry to jump to that agent. Some entries have Approve and Deny buttons.

See Know when an agent needs you.

The usage chip

The usage chip is at the bottom left. It shows how many tokens your agents used in the last 24 hours, for example Usage 1.2M tokens · 24 h.

Click it to open the usage panel. The panel shows your tokens over 5 hours, 24 hours and 7 days, the agents’ rate limits, and what each agent on this canvas used. It also sets how many agents of each kind may run at once.

See Usage and limits.

The zoom controls

The zoom controls are at the bottom right:

• − zooms out.
• The number, for example 100%, is the zoom level. Click it to go back to 100%.
• + zooms in.
• Fit zooms so that every node is in view.

The account button

The account button is at the bottom of the sidebar. It says Sign in until you sign in. Then it shows your plan, for example Free plan, Pro trial or Pro plan. Click it to open your account.

See Sign in.

The command palette

The command palette lists everything Cuewire can do. It is the quickest way to find a command.

1. Press Ctrl+K (or Ctrl+Shift+P). The palette opens at the top of the canvas.
2. Type a few letters of what you want, for example fit or new note.
3. Use Up and Down to pick a command. Press Enter to run it.

Press Esc to close the palette. Each command shows its shortcut, if it has one, on the right.

Figure: The command palette. Type to filter, then press Enter.

The palette also lists every named node as Go to: …, for example Go to: Builder. Choose one to jump to it.

Tip

Inside a terminal, Ctrl+K goes to the program in it. Press Ctrl+Shift+P to open the palette from there.

See the full list in Commands.

Right-click menus

Right-click almost anything for a menu of what you can do with it.

On an empty part of the canvas:

• New terminal here, New note here, New browser portal here and New file tree here add a node where you clicked;
• Select all, Tidy up and Fit all.

Figure: Right-click the canvas to add a node where you clicked.

On a node: Rename, Lock, Bring to front, a row of colours, and Delete. A terminal’s menu also has:

• Runs, to choose the shell or the agent it runs;
• when it runs an agent, that agent’s options: Orchestrator, Skip permission prompts, Role, Model and Account;
• Configure… and Restart, and Send prompt… when it runs an agent.

Figure: A terminal’s menu. Runs chooses its agent. The sections under it set the agent’s options.

On a wire: Disconnect.

See Roles, models and options for the agent options.

Dialogs

When Cuewire asks before it does something, the buttons name their keys. For example, Keep (Esc) and Delete (Enter). Press Enter to go ahead or Esc to keep things as they are.

What’s next

• Move around the canvas
• Terminals, notes and shapes
• Keyboard shortcuts

Move around the canvas

The canvas is much larger than your screen. This page shows how to pan, zoom, select and move nodes, with the mouse or with the keyboard alone.

Figure: A busy canvas, zoomed out. The zoom controls are at the bottom right.

On a Mac, use Cmd where this page says Ctrl.

Pan

To move the view, do one of these:

• Scroll with the mouse wheel or the touchpad.
• Hold Space and drag with the mouse.
• Drag with the middle mouse button.

Note

Over a terminal you clicked into, the wheel scrolls the terminal’s history instead. The same goes for a browser portal, a file tree or a file you clicked. Move the pointer off it to pan.

Zoom

• Hold Ctrl and scroll. The canvas zooms around the pointer.
• Press Ctrl+= to zoom in and Ctrl+- to zoom out.
• Press Ctrl+0 to go back to 100%.
• Or use the zoom controls at the bottom right: −, the zoom level, + and Fit. Click the zoom level to go back to 100%.

You can zoom from 25% to 300%. When you zoom far out, Cuewire draws less: first the text inside nodes goes, then their titles. This keeps the canvas fast. Zoom in again to read.

Fit and focus

Save a view and come back to it

You can keep up to nine views of a canvas: a place and a zoom level.

1. Pan and zoom to a view you want to keep.
2. Press Ctrl+Alt+3 (any number from 1 to 9). Cuewire says View 3 saved · Alt+3 returns here.
3. Later, press Alt+3 to go back there.

The command palette (Ctrl+K) lists your saved views as Go to view 3, and Delete view 3 removes one. Saved views are kept with the canvas.

Select

A selected node has a coloured outline. A drag across empty canvas draws a box. Every node the box touches is selected.

Figure: Drag across empty canvas to select every node the box touches.

Clicking inside a terminal, a note, a browser portal or a file does more than select it. A click in a terminal or a portal sends your keys there. A click in a note or a file lets you edit it. To only select one of these, click its title bar.

Move nodes

• Drag a node by its title bar. Labels, text and rectangles have no title bar: drag them anywhere.
• To move several nodes, select them, then drag one of them.
• Press the arrow keys to move the selection one grid step. Hold Shift to move four steps.

The dots on the canvas are a grid. When you drop or resize a node, it snaps to the grid. This keeps your canvas tidy.

A node you click or drag comes to the front. A locked node does not move. See Terminals, notes and shapes.

Tip

Tidy up in the command palette arranges your agents for you. Agents line up by who hands tasks to whom, with their notes and portals under them. Press Ctrl+Z to undo it.

Use the keyboard only

You can reach every node without a mouse.

Figure: Tab visits nodes row by row, left to right. Nodes whose tops are nearly level count as one row.

1. Press Tab to select the next node. Shift+Tab selects the one before. If the node is off screen, the view moves to it. The zoom level stays the same.
2. Press Enter to go into the selected node:
   • a terminal or a browser portal takes your keys;
   • a note or a file opens for editing;
   • a file tree takes the mouse wheel.
3. Press Shift+Esc to come back out. The node stays selected. In a note or a file, Esc also works.

In a terminal, every other key goes to the program in it, including Esc and Tab. That is why leaving takes Shift+Esc.

Screen readers hear which node is selected. See Keyboard shortcuts.

What’s next

• Terminals, notes and shapes
• Workspaces and canvases
• Keyboard shortcuts

Terminals, notes and shapes

Everything on the canvas is a node. This page shows each kind of node, and how to add, move, resize, rename and delete them.

Figure: A terminal, a note, a rectangle, a label and a text block. The two notes on the right are in a group.

On a Mac, use Cmd where this page says Ctrl.

Kinds of node

Browser portals, file trees and files have pages of their own: Browser portals and Files and the editor.

Add a node

1. Click a tool in the toolbar, or press its key.
2. Click the canvas for a node of the usual size. Or drag to draw the size you want.

The toolbar goes back to Select after one node. Press Esc to stop without adding one.

You can also add a node in these ways:

• Right-click an empty part of the canvas. Choose New terminal here, New note here, New browser portal here or New file tree here. The node appears where you clicked.
• In the command palette (Ctrl+K), choose New terminal, New note, New browser portal or New file tree. The node appears in the middle of the view.

Each new node gets a name, such as Terminal 1 or Note 2.

The parts of a node

Figure: A selected terminal. 1 title bar, 2 status dot, 3 status word, 4 connection handle, 5 edge to resize.

Terminals, notes, portals, file trees and files have a title bar:

• The dot at the left shows the node’s state. On a terminal it turns amber when the agent needs you, green when it is done, and red when it fails.
• The name comes next.
• A word on the right says what needs a look, such as needs approval or done. A locked node says Locked.

When you point at a node with a title bar, or select it, small round handles appear on its four edges. Drag from one to another node to connect them with a wire. See Agents working together.

Rectangles, labels and text blocks have no title bar.

Move and resize

• Move: drag a node by its title bar. Drag a rectangle, label or text block anywhere.
• Resize: drag any edge or corner of the node.

Nodes snap to the grid of dots when you drop or resize them. Each kind has a smallest size. A terminal you resize gets more or fewer rows and columns.

See Move around the canvas for selecting and moving several nodes.

Rename a node

Agents find each other by name, so give your agents clear names, such as Builder and Reviewer.

1. Select the node.
2. Press F2. Or double-click its title bar. Or right-click it and choose Rename.
3. Type the new name and press Enter. Esc keeps the old name.

A name can have up to 64 characters. Two nodes on one canvas can’t have the same name.

Change the words of a label or text block

A new label or text block shows its first name, such as Label 1. To write your own words:

1. Double-click the label or text block. Or select it and press F2. Or right-click it and choose Edit text.
2. Type. Shift+Enter starts a new line.
3. Press Enter, or click somewhere else, to keep the words. Esc keeps the old ones.

Long lines wrap to the width of the node. Make it bigger to show more. Ctrl+Z takes a change back.

Terminals

A new terminal runs a shell. To run an agent in it:

1. Right-click the terminal.
2. Under Runs, choose an agent, for example Claude Code.
3. If the terminal is running, Cuewire asks first. Press Enter to restart it as the agent.

Work in a terminal as you would anywhere:

• Click inside it, or select it and press Enter. Your keys now go to the program.
• Press Shift+Esc to give the keyboard back to the canvas.
• Drag to select text. Double-click selects a word, and a triple-click selects a line.
• Ctrl+C copies the selected text. With nothing selected, Ctrl+C goes to the program, as usual.
• Ctrl+Shift+C copies. Ctrl+Shift+V or Shift+Insert pastes.
• Ctrl+Shift+F finds text in the terminal’s history. In the find box, Enter finds the older match and Shift+Enter the newer one. Esc closes it.
• Some programs print links that you can open. Ctrl+click such a link to open it in your browser.
• Scroll to see the terminal’s history.

To start the program again, right-click the terminal and choose Restart.

The terminal itself tells you when something is off:

See Troubleshooting when an agent does not start.

Notes

A note holds text that you and your agents share: plans, decisions, findings. An agent wired to a note can read it and change it.

1. Click inside the note, or select it and press Enter.
2. Write. Lines that start with # show as headings.
3. Click somewhere else or press Esc. The note saves. Ctrl+S saves too.

While your edits are not saved yet, the note says Unsaved.

When an agent writes more than the note can show, the note grows taller to fit, up to about twice its usual height. Beyond that, its last line says More below: click in, or make the note taller. Click inside the note and scroll, or drag its bottom edge down.

If an agent changes the note while you have unsaved edits, the note says Changed by an agent. Cuewire does not save your edits then, so the agent’s work is never overwritten unseen. Copy anything you want to keep. Then right-click the note and choose Discard my edits to see the agent’s version.

Colours, locks and order

Right-click a node, or several selected nodes:

• The row of colours: gives the node a colour. A rectangle, label or text block takes the colour. Other nodes show it in their title bar’s dot. The empty circle takes the colour away.
• Lock: stops the node from moving, resizing, being renamed or being deleted. Unlock frees it again.
• Bring to front: puts the node on top of the others.

Groups

A group keeps nodes together, so you can move them as one.

1. Select two or more nodes.
2. Press Ctrl+G.

A dashed outline appears around them, with a tab at its top left, such as Group 1. Drag the tab to move the whole group. Click the tab to select every node in it.

To take a group apart, select a node in it and press Ctrl+Shift+G. A node can be in one group only.

Delete nodes

1. Select the nodes.
2. Press Delete or Backspace. Or right-click and choose Delete.

Deleting a running terminal stops the program in it, so Cuewire asks first: Delete 1 running terminal? Press Enter to delete it, or Esc to keep it.

To delete a wire, click it and press Delete. Or right-click it and choose Disconnect.

Locked nodes are not deleted. Unlock them first.

Figure: Cuewire asks before it stops a running terminal.

Undo and redo

• Ctrl+Z undoes the last change to the canvas.
• Ctrl+Shift+Z or Ctrl+Y redoes it.

Undo covers what you do to nodes and wires: adding, moving, resizing, renaming, colouring, grouping, wiring and deleting. It keeps up to 100 steps. It does not undo what happens inside a terminal, and it can’t bring back a program that was stopped.

What’s next

• Workspaces and canvases
• Add an agent
• Agents working together

Workspaces and canvases

The sidebar holds your projects. This page shows how workspaces and canvases fit together, and why your agents keep running when you close Cuewire.

Figure: The sidebar. 1 a workspace, 2 the + that adds a canvas, 3 the open canvas, 4 + Add project, 5 + Remote project (SSH or WSL).

Workspaces

A workspace is one project folder. Every agent in the workspace starts in that folder, or in a layer’s copy of it.

To add a workspace:

1. Click + Add project at the bottom of the sidebar.
2. Choose your project’s folder and click Use this folder.

The new workspace is named after the folder. It has one canvas, which opens at once.

The first time Cuewire opens, it makes a workspace called Home for your user folder.

To work on another machine, click + Remote project (SSH or WSL) instead. See Remote projects.

In the sidebar:

• Click a workspace to fold or unfold it.
• Double-click a workspace to rename it. Press Enter to save the name, or Esc to keep the old one.
• Drag a workspace up or down to change the order.

Canvases

A canvas is one surface of nodes. A workspace can hold several canvases, for example one per feature. All canvases of a workspace work in the same project folder.

• Click the + on a workspace’s row to add a canvas. It is called Canvas 2, Canvas 3 and so on, and it opens at once.
• Click a canvas to open it. The open canvas is highlighted.
• Double-click a canvas to rename it.
• Drag a canvas to change its place in its workspace. A canvas can’t move to another workspace.

Cuewire shows one canvas at a time. The agents on your other canvases keep running. The Needs you list and the notifications cover the canvas that is open.

Cuewire saves your canvases by itself, as you work. You never need to save them.

Note

A name can have up to 64 characters.

Agents keep running when you close Cuewire

Figure: The Cuewire window only shows your terminals. The background service runs them, so closing the window stops nothing.

The Cuewire window does not own your terminals. A background service, cuewired, runs them. Cuewire starts it for you, and it keeps going on its own.

So you can close Cuewire at any time:

• Close the window, or press Ctrl+Q (Cmd+Q on a Mac). Your agents keep working.
• Agents go on handing tasks to each other while the window is closed.
• Open Cuewire again. Every terminal reconnects, with its screen as the agent left it.

If you were away for five minutes or more, a While you were away card sums up what each agent did meanwhile. See Know when an agent needs you.

The background service keeps the last 4 MiB of each terminal’s output. If an agent printed more while you were away, scrolling back shows History lost where the kept output starts.

Note

Restarting your computer stops the background service and every terminal in it. When you open Cuewire again, it starts each terminal again in its folder. Agents that can resume pick up their last conversation.

When the background service updates

After you install a new version of Cuewire, the background service may still run the old one. When terminals are running, the sidebar shows Update ready · restart 2 terminals. Nothing restarts until you choose. See Update Cuewire.

Figure: Cuewire asks before it restarts your terminals for an update.

Where your workspaces are kept

Your workspaces, canvases and notes are on your computer, in %LOCALAPPDATA%\Cuewire. Updating or uninstalling Cuewire leaves that folder alone.

What’s next

• Add an agent
• Projects and layers
• Remote projects

Add an agent

An agent is an AI coding tool, such as Claude Code or Codex, that runs in a terminal on your canvas. This page shows how to add one, give it its first prompt, and pick up its conversation later.

Figure: The Start here card. Click an agent to put it on the canvas.

The agents Cuewire can run

Cuewire runs each agent’s own command-line program (CLI) in a terminal node. You choose it under Runs in the node’s menu.

A Shell is a plain terminal. The Start here card calls it Terminal.

Install the agents first

Cuewire does not install agents. Install each one with its own installer, and sign in to it.

When Cuewire starts, it looks for each program on your PATH:

• If it finds the program, the agent’s button on the Start here card works.
• If not, the button says (not installed), for example Codex (not installed), and you can’t click it.

After you install an agent, quit and open Cuewire again. Cuewire then finds the new program.

Tip

Codex is OpenAI’s coding agent, and it now lives under ChatGPT. Get it at chatgpt.com/codex and sign in with your ChatGPT account. Its command is still codex, so in Cuewire it is still called Codex. On Windows, OpenAI’s installer adds the real program, codex.exe, which Cuewire can start.

Tip

For OpenCode on Windows, use the standalone download from opencode.ai (Windows x64). Unzip opencode.exe into a folder of your own and add that folder to your PATH. The npm package adds a script that Cuewire can’t start. Cuewire works with OpenCode 2; choose models inside OpenCode with /models.

Tip

Gemini CLI no longer lets you sign in with a personal Google account. Google now points people to Antigravity (agy) instead, and Cuewire runs Antigravity too. To keep using Gemini CLI, use a Gemini API key from Google AI Studio, or Vertex AI. You can keep the key in an agent account.

Note

On Windows, Cuewire starts an agent’s real program file, such as claude.exe. npm adds only a script for a tool, such as gemini.cmd. Most of these scripts only start Node.js on the tool’s JavaScript file. Cuewire then starts Node.js on that file itself, without the script. So npm install -g @google/gemini-cli works for Gemini CLI. Node.js must be installed: Cuewire uses the node.exe next to the script, or the one on your PATH.

Cuewire does not run other scripts, such as .bat, .ps1 or other .cmd files. Windows runs them through cmd.exe, which could read parts of a prompt as commands. If only such a script is found, the agent’s node says which file it found. Install the agent’s native build instead.

On a remote canvas, the Start here card shows the agents that the remote computer has. See Remote projects.

Add an agent from the Start here card

The Start here card shows on an empty canvas.

1. Click Open a project folder… and choose your project. Agents work in this folder.
2. Under Add an agent, click an agent, for example Claude Code. A terminal node appears in the middle of the view, and the agent starts in it.

The new node takes the agent’s name, such as “Claude Code”. A second one is “Claude Code 2”.

Add an agent to a canvas with nodes

1. Right-click an empty part of the canvas and choose New terminal here. Or press Ctrl+K (Cmd+K on a Mac) and run New terminal. A terminal opens with your usual shell.
2. Right-click the terminal. Under Runs, choose an agent, for example Claude Code.
3. Cuewire asks Restart Terminal 1 as Claude Code? Press Enter. The shell stops and the agent starts in its place.

Figure: Under Runs, choose the agent this terminal runs.

Tip

Give each agent a short, clear name. Double-click its header, or select it and press F2. Other agents reach it by this name, for example cuewire ask Reviewer ….

When an agent can’t start

If an agent can’t start, its node says why, for example “Codex can’t start: codex is not installed (it is not on PATH)”. Common reasons:

• The program is not installed, or on Windows only a script was found (see above).
• The agent was installed with npm, but Node.js is not installed or not on your PATH.
• Its role is read-only, and this agent can’t be held to read-only. See Roles, models and options.
• Your organisation does not allow this agent or model. See Teams and organisations.
• Its sandbox setup changed and waits for you. See Sandboxes and safety.
• One of its Extra arguments is managed by Cuewire.

Fix the cause. Then right-click the node and choose Restart.

Figure: The node says what is wrong, so you know what to fix.

Give the first prompt

You can talk to an agent in two ways.

Type in its terminal:

1. Click inside the agent’s terminal. The terminal gets the keyboard.
2. Type your prompt and press Enter, as in any terminal.
3. Press Shift+Esc to give the keyboard back to the canvas.

Use the prompt composer: see the next section.

Note

The first time an agent runs, it may ask its own setup questions, for example to sign in or to trust the folder. Answer them in its terminal. Codex also asks you to trust Cuewire’s hooks (Hooks need review). See Trust Cuewire’s hooks in Codex.

The prompt composer

The composer writes one prompt and sends it to one agent or to several at once.

1. Click an agent’s header to select it. Shift-click more headers to add more agents.
2. Press Ctrl+Enter (Cmd+Enter on a Mac). You can also right-click an agent and choose Send prompt…, or run Prompt selected agents… from the command palette.
3. Write the prompt. Shift+Enter starts a new line.
4. Press Enter to send it. Cuewire types the prompt into each agent’s terminal and presses Enter for you. A message says “Sent to …”.

Figure: The composer. Type @ to name a note, an agent or a file.

Name a note, an agent or a file with @:

• Type @. A list shows the canvas’s notes and agents, then your project’s files.
• Up and Down move through the list. Enter takes an item. Esc closes the list.
• A note: its current text goes with the prompt, under “Referenced notes”.
• An agent: its name goes with the prompt, under “Referenced peers”.
• A file: it stays as @path/to/file. Claude Code reads the file it names.

Attach files: click Attach files… and choose files on your computer.

• A file inside the project goes as @path/to/file.
• A file outside it goes as its full path.
• Attached files are listed under “Attached files”. Click a file’s chip to take it off.

Keep a draft: press Esc. The composer closes and keeps your text and files for next time.

Note

The composer sends only to agents that are running. If none of them is, it says “None of them is running; start them first”.

Tip

Ctrl+Enter works when the canvas has the keyboard. If you are typing in a terminal, press Shift+Esc first.

The agent sheet

The agent sheet shows all of an agent’s settings in one place. Right-click the agent and choose Configure…. Or select it and run Configure agent… from the command palette.

Figure: The agent sheet. Save and restart applies your changes now.

The sheet has these parts:

• Name: the agent’s name on the canvas.
• Runs: which agent runs in this terminal.
• Role, Model and Options: see Roles, models and options.
• Account: which login the agent uses. See Usage and limits.
• Extra arguments: more options for the agent’s command line.
• Session: the agent’s conversation (see the next section).

At the bottom:

• Save keeps your changes. They apply the next time the agent starts.
• Save and restart keeps them and restarts the agent now.
• Cancel closes the sheet without changes.

Pick up a conversation

A session is an agent’s conversation. Cuewire keeps each agent’s session on its node. When you restart the agent, or quit and open Cuewire again, the agent goes on with the same conversation.

If Cuewire doesn’t know an agent’s session, the agent continues its latest conversation in the project folder. When two agents of the same kind are on the canvas, each starts a new conversation instead. So they never take over each other’s conversation.

Resume another conversation:

1. Right-click the agent and choose Configure….
2. Under Session, paste the session’s id into the Resume session by id field. Or click Find a session of this project… and pick one. The list shows the newest first. Type in its box to filter it.
3. Click Save and restart.

Find a session of this project… works for Claude Code, Codex, Copilot CLI and Gemini CLI, on canvases on this computer.

To copy the current session’s id, click Copy next to it.

Figure: Past sessions of this project, newest first. Click one to resume it.

Note

A session belongs to the account the agent used. If you give the agent another account, it starts a new conversation.

What’s next

• Know when an agent needs you
• Agents working together
• Roles, models and options

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

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

Roles, models and options

Each agent has options: which model it uses, what role it plays, and whether it asks before it acts. This page explains each option and where to set it.

Figure: Right-click an agent to change its options.

Where to find the options

Right-click an agent. Its menu has these sections:

• Runs: which agent runs in this terminal.
• Agent: Orchestrator and Skip permission prompts.
• Role: No role, the built-in roles, your own roles, and Edit roles….
• Model: Agent default and the agent’s models.
• Account: which login the agent uses. See Usage and limits.

Below them are Configure…, Send prompt… and Restart. Configure… opens the agent sheet, which shows all the options in one place.

Most options apply when the agent starts. If the agent is running, Cuewire tells you to restart it, for example “Restart Builder to apply its new settings”. Right-click it and choose Restart.

Choose a model

Under Model, choose a model, or Agent default to let the agent pick.

The other agents have no list in Cuewire. They use Agent default: choose the model inside the agent itself.

Cuewire can update these lists without a new release. Your organisation can also limit the models you may use. Models it does not allow are not shown.

Roles

A role tells an agent what it is for. Cuewire gives the role’s instructions to the agent when it starts. A role can also have rules, which hold the agent to them whatever it is asked.

Built-in roles:

• A Builder makes the changes it is asked for, in small, tested steps. It leaves other files alone.
• A Reviewer looks for bugs, missing tests and risks, and says what must change. It fixes nothing unless you ask it to.

Give an agent a role: right-click it and choose the role under Role. Choose No role to take the role away.

Note

Claude Code, Codex, Grok and Copilot CLI get a role’s instructions when they start. Gemini CLI, OpenCode and Antigravity take no instructions at launch, so they don’t get them yet. A role’s rules still apply to them where the agent supports them.

Make your own roles

1. Press Ctrl+K (Cmd+K on a Mac) and run Agent roles…. Or right-click an agent and choose Edit roles….
2. Click Add role.
3. Type a Name, up to 40 characters.
4. Under Instructions: what this role does, and what it leaves alone, write what the agent should do.
5. Under Rules, turn on the rules you want (see below).
6. Click Add.

Your role now shows in every agent’s Role list.

Figure: The Agent roles sheet. Built-in roles can’t be changed.

To change a role, click Edit next to it. To delete it, click Remove, then Remove now. Agents that had a removed role keep its name, but not its instructions or rules.

• A changed role reaches a running agent when the agent restarts.
• Your roles follow you to your other computers when settings sync is on.
• In a team, an admin can Share a role with everyone. Shared roles show “From your organisation”. See Teams and organisations.

Role rules: read-only and always asks

A role can hold its agents to two rules:

• Read-only: may read, never change files. The agent starts in its own read-only mode. This works with Claude Code, Codex and Gemini CLI (in its plan mode). Any other agent given a read-only role won’t start, and its node says why.
• Always asks before acting, even with skip permission prompts on. The agent asks you before it acts, even if Skip permission prompts is on for it. Its menu then says Skip permission prompts (its role always asks).

A read-only role also turns off Skip permission prompts for its agents.

Figure: A new role with the read-only rule turned on.

When you review a layer’s changes, Cuewire adds a Reviewer that always runs read-only. See Review your agents’ work.

Skip permission prompts

Agents normally ask you before they run a command or change a file. Skip permission prompts starts the agent with its own option to stop asking:

Warning

With this on, the agent acts without asking you. It can change or delete any file it can reach and run any command. For Codex, it also turns off Codex’s own sandbox. Prefer to run such agents in a sandbox.

Skipping does not apply, or the agent won’t start, when:

• its role is read-only or always asks;
• your organisation allows skipping only inside a sandbox, and the agent is not in one;
• the agent’s own managed settings on this computer forbid it (Claude Code’s managed settings, or Codex’s requirements). The node names the file.

Agents that an orchestrator adds never skip permission prompts.

The agent sheet (Configure…)

Right-click an agent and choose Configure…. The sheet shows:

• Name and Runs
• Role and Model
• Account (for agents that can have one)
• Options: Skip permission prompts and Orchestrator. With skipping on, the sheet warns you and suggests a sandbox.
• Extra arguments
• Session

Save keeps your changes for the next start. Save and restart applies them now.

For the orchestrator, see Agents working together.

Extra arguments

Add options to the agent’s command line, for example --add-dir "my docs". Separate them with spaces. Use quotes around a value with spaces.

• Extra arguments are saved with the canvas. Never put keys or tokens here.
• Cuewire refuses arguments it manages itself, for example --session-id for Claude Code. The sheet says “Extra arguments: argument –session-id is managed by Cuewire”.
• Cuewire refuses commands that don’t start a session you can talk to, for example claude mcp.

Session id and resume

Under Session:

• The current session’s id shows, with Copy to copy it. A new agent shows “No session yet”.
• Resume session by id: paste an id. The agent resumes that conversation at its next start.
• Find a session of this project… lists this project’s past sessions, newest first.

See Pick up a conversation.

What’s next

• Usage and limits
• Sandboxes and safety
• Review your agents’ work

Usage and limits

Agents use tokens, and their accounts have limits. Cuewire shows how much your agents use, holds tasks when an agent reaches its limit, and can run agents on other accounts. This page explains how.

Figure: The usage panel. Click the chip at the bottom left to open it.

The usage chip

The usage chip sits at the bottom left of the canvas. It shows the tokens your agents used in the last 24 hours, for example Usage 1.2M tokens · 24 h.

Click it to open the usage panel. Or press Ctrl+K (Cmd+K on a Mac) and run Show usage.

Cuewire reads these numbers from the agents’ own logs on this computer: Claude Code, Codex, Copilot CLI and Gemini CLI. It reads them again every half minute. Nothing leaves your computer.

The panel has these parts:

Note

Claude Code’s logs don’t report its 5-hour window, so Cuewire estimates it. Live totals can be a few percent lower than your bill.

When an agent reaches its limit

Cuewire notices when an agent can’t take more work:

• the agent shows its own usage-limit message, for example that a limit was reached and when it resets; or
• a Codex agent’s account has used 95% or more of its current window.

Then new tasks for that agent are held. A held task is not lost:

• The agent’s header shows 1 task held (or more).
• The usage panel lists it under Held tasks (they go out when the limit clears), with the reason and who sent it.
• The sender’s cuewire ask or cuewire send says why the task waits.

The task goes out by itself when the limit clears. Two things can get it moving sooner:

• A key pool: Cuewire moves the agent to its next key. See Key pools below.
• --reroute: if the sender allowed it, an idle agent with the same role takes the task. Cuewire tries an agent of the same kind first. The sender is told who took it.

Figure: Three ways a held task gets done.

Figure: The header shows how many tasks wait for this agent.

Concurrency caps

A concurrency cap limits how many agents of one kind run at once. It stops parallel agents from using up an account’s limit together.

1. Open the usage panel.
2. Under At once (concurrency caps), find the agent. It shows no cap at first.
3. Click − to set a cap. Each click lowers it, from 8 down to 1. Click + to raise it. Above 8, it goes back to no cap.

An agent over the cap waits on its node, for example “Waiting: 2 Claude Code agents are already running (the cap; change it under Usage)”. It starts when another agent of its kind stops, or when you raise the cap.

Figure: This agent starts when a slot frees up.

Agent accounts

An agent signs in with this computer’s own login, shown as This computer’s sign-in. You can give an agent another account: a separate login, a set of API keys, or another service.

Add an account:

1. Press Ctrl+K and run Agent accounts…. Or right-click an agent and choose Manage accounts….
2. Click Add account.
3. Under Agent, choose the agent the account is for.
4. Under Signs in with, choose a kind:
   • Its own folder: the agent keeps its login and history in a folder of its own.
   • API keys: one or more keys, separated by spaces.
   • Another endpoint: an address (https://…) and its token, for a proxy or a compatible service.
5. Type a Name, then click Add.

With Its own folder, start an agent on the account and sign in there once.

Figure: The Agent accounts sheet. Keys go into masked fields.

Each agent supports these kinds:

Keys and tokens are kept in your system’s keychain (Credential Manager on Windows, Keychain on a Mac), never in a file. When you remove an account, its keys leave the keychain. An account’s own folder stays, with its login and history.

Put an agent on an account:

1. Right-click the agent.
2. Under Account, choose the account.
3. Restart the agent. The account applies when it starts.

Figure: The Account section of an agent’s menu.

Note

A conversation belongs to the account it ran on. When you change an agent’s account, the agent starts a new conversation.

The usage panel shows each own-folder account’s usage under the account’s name, in Accounts, last 24 hours.

Key pools and the next key

An account with more than one API key is a key pool. Each new agent on it takes the next key in turn. An agent keeps its key when it restarts, and when you restart Cuewire.

• To move an agent to the following key, right-click it and choose Restart with next key (now 1 of 3). The numbers show which key it uses now.
• Move to the next key when one reaches its limit is on for a new pool. With it on, Cuewire does this for you. When a task is held because the agent is at its limit, Cuewire restarts the agent on the next key. The agent resumes its conversation and takes the task. Each key is tried once, a minute apart.

A message tells you, for example “Worker reached a usage limit; restarted on key 2 of 3”.

What’s next

• Sandboxes and safety
• Agents working together
• Know when an agent needs you

Sandboxes and safety

A sandbox runs an agent inside a Docker container that sees only its project files. Use one when you let agents work without asking you. This page shows what a sandbox allows and how to turn it on.

Figure: In a sandbox, the agent sees only the worktree, mounted at /workspace.

What an agent in a sandbox can reach

A worktree is the copy of your project that a layer works in. On the base layer, it is your project folder.

The sandbox applies to agents, not to a plain Shell. It is for projects on this computer, not on remote ones.

Turn on a sandbox

You need Docker on this computer, and an image that has your agents’ programs installed (for example Claude Code and Codex). Cuewire does not publish such an image yet.

1. Build or choose an image with your agents in it, for example my-agents:latest.

2. In your project, create the file .cuewire/layers.toml and add a [sandbox] section:

   [sandbox]
   image = "my-agents:latest"
   network = "bridge"
   env = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]
   

3. Restart your agents: right-click each one and choose Restart. Each agent now starts in its own container.

The settings:

Note

On Windows, agents in a sandbox reach Cuewire over Docker’s network. Set network = "bridge". Without it, the agent won’t start, and its node tells you to add it.

Sign in inside the sandbox

The container can’t see your login files. That is the point. Agents sign in with variables you pass in by name, in env:

• Claude Code: CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token) or ANTHROPIC_API_KEY.
• Codex: OPENAI_API_KEY.

Use your project’s dev container

If your project has a dev container, the sandbox can use it instead of an image:

[sandbox]
devcontainer = ".devcontainer/devcontainer.json"
network = "bridge"
env = ["ANTHROPIC_API_KEY"]

• Cuewire uses the dev container’s image, or builds its Dockerfile when the agent starts. The build’s progress shows in the agent’s terminal.
• Cuewire leaves out settings that would widen the sandbox, such as extra mounts and admin rights. It also skips start-up commands, such as postCreateCommand. The agent’s terminal says which settings were left out.
• Dev container features don’t run. Install the agent’s program in the Dockerfile.

Warning

Building a Dockerfile always has network access, whatever network says. A Dockerfile can download things, and it can send out files from the project. It gets nothing else of yours.

When the sandbox setup changes

An agent in a sandbox can change files in its worktree, including .cuewire/layers.toml, the dev container and its Dockerfile. So Cuewire remembers the setup that agents first started with in each project.

When the setup changes, for example the network is opened or another variable is passed in, agents in that project don’t start. Their nodes say that the sandbox setup changed.

Figure: The setup changed, so the agent waits for you.

To go on:

1. Look at what changed in .cuewire/layers.toml, the dev container or the Dockerfile.
2. If you agree with it, press Ctrl+K (Cmd+K on a Mac) and run Trust this project’s sandbox setup. Cuewire says “Agents in this project now start with its current sandbox setup.”
3. Right-click each waiting agent and choose Restart.

All layers of a project share one trusted setup.

Figure: Trust the new setup only after you have read the change.

Skip permission prompts and the sandbox

In a sandbox, it is safer to let an agent work without asking: it can only touch its worktree. To turn this on, see Skip permission prompts.

Without a sandbox, the agent sheet warns you when you turn skipping on. Your organisation can go further. With the policy Skip permission prompts only in a sandbox, an agent with skipping on won’t start outside a sandbox. Its node says: “your organisation allows skipping permissions only inside a sandbox; add a [sandbox] to .cuewire/layers.toml or turn skipping off”. See Teams and organisations.

Other ways Cuewire keeps you safe

• Wires: an agent can reach only the agents, notes and portals it is wired to. See Agents working together.
• Read-only roles: a role can hold an agent to reading only. See Roles, models and options.
• Approvals: you see every question in the Needs you rail. See Know when an agent needs you.
• The agents’ own rules: this computer’s Claude Code or Codex settings may forbid running without asking. Cuewire then won’t start the agent that way, and says why.

What’s next

• Projects and layers
• Review your agents’ work
• Privacy and security

Projects and layers

Layers let several agents change the same project at the same time without getting in each other’s way. This page shows how to make a layer, get it ready to run, and put it away when the task is done.

Figure: One project, three layers. Base is your own project folder. Each task layer has its own folder, branch, ports and agents.

What a layer is

When you add a project folder, Cuewire opens it as a workspace with one canvas. That canvas starts on the Base layer: your project folder, as it is.

A layer is a separate copy of your project for one task. It is a git worktree: a folder of its own, on a branch of its own, that shares your repository’s history. Each layer also has its own copy of the canvas.

• Agents in a layer work in that layer’s folder. Your own checkout stays as it is.
• Agents work with the agents, notes and portals of their own layer only.
• Switching layers never stops an agent. Agents in the other layers keep working.

Note

Layers need a git repository with at least one commit. Remote projects can’t have layers yet.

The layer chip

The layer chip is at the top left of the canvas. It shows the layer you are looking at, for example Layer Base ▾. Click it to open the layer menu.

Figure: The layer menu. The tick marks the layer you see.

The top of the menu lists the canvas’s layers:

• ✓ marks the layer you see. Click another layer to switch to it.
• restore marks an archived layer. Click it to bring the layer back.
• creating… shows while Cuewire makes the layer.
• failed · remove marks a layer Cuewire could not make. Click it to clean up what was made.

Below the list are the actions:

• New layer from this one makes a new layer.
• Review changes, Commit all changes and Open pull request check and ship the layer’s work. See Review your agents’ work.
• Archive Fix login (back to Base) puts the layer away. The name is the layer’s own.

The last four show on task layers only, not on Base.

Tip

The command palette has the same actions. Press Ctrl+K (Cmd+K on a Mac) and type “layer”: New layer from this one, Switch to layer: … and Archive layer: ….

Make a layer

1. Open the layer whose canvas you want to copy. Usually that is Base.
2. Click the layer chip, then New layer from this one. The New layer from this one sheet opens.
3. Type a Name for the task, for example Fix login. Cuewire suggests Layer 1, Layer 2 and so on.
4. Leave Branch (optional) empty, or type a branch name. The line under the field says what will happen.
5. Click Create layer, or press Enter. Esc cancels.

Figure: The New layer sheet. An empty branch gives the layer a branch of its own.

Cuewire makes the layer’s folder, gets it ready (see below) and switches to it. This can take a few seconds on a large repository.

The branch field decides where the layer’s code comes from:

A new branch starts at the commit of the layer you made it from. From Base, that is the commit your project folder is on now. From another layer, it is that layer’s latest commit, so the new layer builds on its work. Changes you have not committed are not in the new layer.

Start the layer’s agents

A new layer’s canvas is a copy of the one you came from. Its notes come along with their text. Its terminals come along as drafts: they are not running yet. A draft terminal says Draft in this layer · right-click → Start to run it here.

1. Right-click a draft terminal.
2. Choose Start in this layer. The agent starts in the layer’s folder.

Figure: A new layer. Its terminals wait as drafts until you start them.

Get a layer ready to run

A fresh worktree has your code but not everything you need to run it. Untracked files such as .env are missing, packages are not installed, and two copies of a server would fight over one port. Cuewire fixes this when it makes a layer. You describe what to do in .cuewire/layers.toml at the top of your repository:

copy = [".env*", "config/local.json"]   # files to copy into each new layer
setup = "npm install"                   # runs once in each new layer
ports = ["web", "api"]                  # ports each layer gets for itself

Every line is optional. Without the file, Cuewire copies the .env files and does nothing else.

Copied files

copy lists files to copy from your project folder into each new layer. The default is [".env*"].

• A name that ends in * matches files at the top of the project, such as .env and .env.local.
• A full path, such as config/local.json, can point into a folder.
• A file that is already in the layer is not replaced.

The setup command

setup runs once in each new layer, through your system’s shell. Use it to install packages or seed a database. It may run for up to 10 minutes. Its output goes to the layer’s setup.log in Cuewire’s state folder.

If the setup command fails, the layer is still made. The canvas says Fix login was created, but its setup failed: … with the reason.

Ports

ports names the ports your project’s servers need. Each layer gets its own numbers, so servers in two layers never clash.

• Cuewire gives each layer a block of ten ports, starting at 41000. The first layer you make gets 41010 and up, the second 41020 and up.
• A port that something else already uses is skipped.
• Two layers never get the same port.

The layer’s terminals get these variables:

Make your servers read PORT or CUEWIRE_PORT_<NAME>. Then each layer runs on its own ports.

A database per layer

If your database can make branches (Neon, for example), each layer can have its own. Add a [database] section:

[database]
create = "neon branches create --name $CUEWIRE_LAYER_BRANCH --output connection-string"
delete = "neon branches delete $CUEWIRE_LAYER_BRANCH"
env = "DATABASE_URL"

• create runs before the setup command. The last line it prints becomes the layer’s DATABASE_URL (or the variable env names). The setup command already sees it.
• delete runs when you archive the layer.
• If create fails, Cuewire says so and skips the setup command.

Note

.cuewire/layers.toml can also run agents in a sandbox. See Sandboxes and safety.

Archive a layer

Archive a layer when its task is done or on hold. Archiving keeps the work and frees the disk space.

1. Stop the agents in the layer.
2. Switch to the layer, click the layer chip and choose Archive Fix login (back to Base).

Cuewire switches back to Base and then:

1. commits anything not yet committed, as WIP: Fix login archived from Cuewire;
2. removes the layer’s folder;
3. runs the delete command of [database], if there is one.

The branch stays, with all the work on it. The layer stays in the menu, marked restore.

Warning

Cuewire refuses to archive a layer while its agents run. It says Stop the agents in this layer before archiving it. Stop them first, so no agent is cut off in the middle of a change.

Restore a layer

1. Click the layer chip.
2. Click the archived layer, marked restore. Cuewire checks its branch out into a folder again.
3. Click the layer in the menu to switch to it.

Restoring does not copy files or run the setup command again. If a folder is already where the layer’s folder goes, Cuewire stops and says a directory is already in the way of this layer.

What’s next

• Review your agents’ work: check a layer’s changes, then commit and open a pull request.
• Files and the editor: see a layer’s files and diffs on the canvas.
• Sandboxes and safety: run a layer’s agents in a container.

Review your agents’ work

When agents finish a task in a layer, check what they changed before it goes anywhere. This page shows how to review a layer, spot clashes with other layers, commit the work and open a pull request.

Figure: From a layer’s changes to a pull request. The review also warns about files other layers changed too.

You review, commit and open pull requests from the layer chip at the top left of the canvas. These actions work on task layers, not on Base. To learn about layers, see Projects and layers.

Review a layer

1. Switch to the layer you want to check.
2. Click the layer chip and choose Review changes.

Cuewire adds two things to the canvas, wired together:

• A review note, named after the layer (for example Review: Fix login). It lists what the layer changed.
• A Reviewer agent. It reads the changes and writes its findings into the note.

Figure: A review. The note lists collisions with other layers, then the changes, riskiest first. The Reviewer adds its findings at the end.

What the review note shows

The note starts with the totals: the commit the layer started from, the number of files, and the lines added and removed. It also counts changes that are not committed yet.

Then it has these sections:

• Collisions with other layers: files that another layer changed too. See below.
• Changes, riskiest first: every changed file, with how it changed and its line counts. Files that deserve a closer look come first, with the reason. For example: “changes CI”, “changes the database schema”, “changes locked dependencies”, “touches authentication”, “touches environment settings”, “deletes a file” or “a large change”.
• Findings: empty at first. The Reviewer writes here.

The note counts everything the layer changed since it began: commits, changes not yet committed, and new files.

The Reviewer agent

The Reviewer is held to read-only: it can read files and run git diff and git log, but it can’t change files. It gets the built-in Reviewer role. Cuewire uses an agent you already have on the canvas, if that agent can be held to read-only. Otherwise it uses Claude Code.

Cuewire types a short brief into the Reviewer. The brief asks it to read the diff. Then it adds to the note what must change before merging, with file and line. It also lists risks, missing tests and a one-line verdict.

Note

Sometimes Cuewire can’t tell whether the agent is ready for the brief. Then it types the brief but does not send it, and says The review brief is typed into Reviewer; press Enter there to start. Click into the Reviewer’s terminal and press Enter.

You can run a review again at any time. Each review adds a new note and a new Reviewer.

Collisions with other layers

Two layers that change the same file may not merge cleanly. The review compares the layer with every other layer that is not archived. It also compares it with your project folder (Base) since the layer began.

In the Collisions with other layers section:

• ⚠ … on the same lines; merging will likely conflict: another layer changed the same lines, or lines right next to them. Git will most likely stop with a conflict.
• … on other lines: another layer changed the same file, but in other places. Git can most likely merge both.

Tip

A likely conflict is cheaper to fix now. Ask one of the agents to rebase on the other layer’s branch, or merge one layer first and then review the other again.

Commit the work

1. Switch to the layer.
2. Click the layer chip and choose Commit all changes.

Cuewire stages everything in the layer’s folder, new files included, and makes one commit on the layer’s branch. The message is the layer’s name, for example Fix login: changes from Cuewire. The canvas then says, for example, Committed 3 files in Fix login (1a2b3c4). If there is nothing to commit, it says Nothing to commit in Fix login.

Note

Your git hooks run first, such as pre-commit, as with any commit. While they run, the canvas says Committing Fix login…. If a hook fails, nothing is committed, and the canvas shows the end of what the hook said. Fix the problem, or ask an agent to, and commit again.

To pick files one by one instead, stage them in a file node and commit from a terminal. See Files and the editor.

Open a pull request

Cuewire opens pull requests with the GitHub CLI (gh) or the GitLab CLI (glab). It uses your own sign-in in that tool, and never sees your tokens.

Before the first time:

1. Install gh (for GitHub) or glab (for GitLab).
2. Sign in once in a terminal: gh auth login or glab auth login.

Then, for each layer:

1. Commit the layer’s work (see above). Cuewire refuses to open a pull request while there are uncommitted changes.
2. Click the layer chip and choose Open pull request. The canvas says Pushing Fix login and opening a pull request….
3. Cuewire pushes the layer’s branch and opens the pull request. It opens the page in your browser and says Opened with its address.

Figure: The pull request is open. Cuewire shows its address and opens it in your browser.

What the pull request contains:

• Into: your repository’s default branch, for example main.
• Title: the commit’s message if the layer has one commit. With more commits, the layer’s name.
• Description: a list of the layer’s commits, then “Opened from a Cuewire layer.”

On GitLab, Cuewire opens a merge request instead. If a pull request for the branch is already open, Cuewire says A pull request was already open: with its address, and opens it.

If it does not work

Cuewire pushes to the remote named origin. Without one, it uses the first remote it finds.

Note

Reviews, commits and pull requests run on your own computer. They don’t work for remote projects.

What’s next

• Files and the editor: read a file’s diff and stage files one by one.
• Projects and layers: archive a layer once its pull request is merged.
• Agents working together: hand the review’s findings back to the builder.

Files and the editor

You can browse your project, read and edit files, and check diffs on the canvas, next to the agents that change them. This page shows the file tree, the file node and its diff views.

Figure: A file tree, left, and a file opened from it, right. The letters show each file’s git status.

Add a file tree

A file tree lists the files of the canvas’s project folder. On a layer, it lists that layer’s folder.

1. Right-click an empty spot on the canvas.
2. Choose New file tree here.

You can also press Ctrl+K (Cmd+K on a Mac) and choose New file tree.

In the tree:

• Click a folder to open or close it. Folders come first.
• Double-click a file to open it in a file node beside the tree.
• Click ↻ at the top right to read the folder again.

The tree leaves out what your .gitignore ignores, and the .git folder. It shows at most 5000 entries.

Git badges

A letter next to a file shows its git status:

A folder shows M when something inside it changed.

Read a file

A file node shows one file of the project. Its strip, at the top, has six buttons:

The button for the view you see is highlighted. A file node reads its file again every few seconds while it is on screen. So you see your agents’ changes as they make them.

Figure: The Diff view. Added lines are green, removed lines red.

When a view is empty, the node says so: No unstaged changes. or Nothing staged.

Tip

Use Diff, Stage and Staged to build a commit file by file. Then commit from a terminal. To commit everything in a layer at once, see Review your agents’ work.

Edit a file

1. Click into the file’s text. Or select the file node and press Enter.
2. Type. A caret and selection work as in any editor.
3. Press Ctrl+S (Cmd+S on a Mac) to save.

Leaving the file also saves it: press Esc, or click somewhere else. Closing the canvas saves too.

While you edit, the strip says Unsaved until you save, then Saving….

The editor keeps the file’s own line breaks and indent style. Useful keys:

On a Mac, use Cmd where the table says Ctrl.

When an agent changes the file you edit

While you have nothing unsaved, your agents’ changes to the file show up by themselves.

If an agent changes the file while you have unsaved edits, the strip says Changed on disk. Cuewire then refuses to save, so the agent’s work is never overwritten without you seeing it.

Figure: Changed on disk. Your edits are still on screen, but saving is refused.

To go on:

1. Copy anything from your edits that you want to keep.
2. Click Reload. The agent’s version replaces your edits.
3. Paste your changes back in, and save.

Warning

Reload drops your unsaved edits. Copy what you want to keep first.

What a file node can open

• Text files up to 1 MiB, in UTF-8.
• Files inside the project folder only. A symbolic link is refused: open its target instead.

On a remote project, files and diffs come from the host. There, files and diffs larger than 512 KiB are not opened. See Remote projects.

What’s next

• Review your agents’ work: review a whole layer at once.
• Browser portals: see the web app your agents are building.
• Terminals, notes and shapes: notes are edited the same way as files.

Browser portals

A browser portal shows a live web page on the canvas. You can use the page yourself, and agents wired to the portal can read it, click and type in it. This page shows how to open a portal, wire it to agents, and choose how it keeps sign-ins.

Figure: A portal wired to an agent. The purple arrow shows where the agent clicked last.

Before you start

Portals use Chrome, Edge or Chromium, so one of them must be installed. Cuewire starts it in the background, without a window, on a browser profile of its own. It never uses your own browser profile, your history or your saved passwords.

If Cuewire finds none, the portal says no Chrome or Edge was found; install one, or set CUEWIRE_BROWSER to its path. Install a browser, or set the CUEWIRE_BROWSER variable to the browser’s program file.

Open a portal

1. Right-click an empty spot on the canvas and choose New browser portal here. Or press Ctrl+K (Cmd+K on a Mac) and choose New browser portal.
2. Double-click the address strip at the top of the portal. Or right-click the portal and choose Edit address.
3. Type an address and press Enter. The page opens.

You can leave out https://. An address such as localhost:3000 opens with http://, so your own dev server works. Any other address opens with https://.

An empty portal says No page yet. Double-click the address bar above to open one, or let an agent wired here open it.

Use the page

• Click the page to click on it. The portal takes the keyboard, so typing goes to the page.
• Scroll with the mouse wheel.
• Use the buttons at the left of the address strip to go back, forward or reload.
• Press Shift+Esc to give the keyboard back to the canvas.

Tip

Without a mouse, select the portal with Tab and press Enter to type into the page.

Cuewire draws the page only while the portal is on screen and not zoomed far out. Deleting a portal closes its page.

Wire a portal to agents

Drag from an agent’s edge to the portal. Now that agent can drive the page. Agents that are not wired to the portal can’t reach it.

An agent drives the page with the cuewire portal command, which Cuewire teaches it. For example, it can read the page, click, fill in forms, type, scroll, go back and take a screenshot:

cuewire portal snapshot Shop
cuewire portal click Shop @e12
cuewire portal fill Shop @e3 ada@example.com

The full list is in the cuewire CLI reference.

When an agent clicks or types in the page, a purple arrow glides to that spot and fades after a few seconds. So you can follow what the agent does. Your own clicks don’t show it.

Note

An orchestrator agent can open a portal by itself with cuewire portal create. The new portal appears on the canvas, wired to that agent.

Sign-ins

Each portal keeps its own sign-ins, that is its cookies and site storage. They are separate from your browser and from other portals. You can share them instead. Right-click the portal and choose one:

The choice in use has a ✓. Changing it reloads the portal at its address.

Figure: Sign-ins for one portal, for a workspace, or for all portals.

Tip

Sign in to your app once in a portal that shares in the workspace. Every other portal of the workspace that shares is signed in too.

Figure: A portal’s menu. The tick shows how this portal keeps its sign-ins.

Popups

When a page opens a popup, such as a sign-in window, the popup appears as a portal of its own beside the first one. It is named after the first portal, for example Shop #2. It has the same sign-ins and is wired to the same agents. When the popup closes itself, its portal goes away.

Figure: A sign-in popup gets a portal of its own, wired to the same agent.

This happens while the portal is on screen in the Cuewire window that drives the project. At other times the popup opens inside its portal, and agents work with it there. That is the case when the app is closed, the portal is scrolled out of view, or another computer drives a remote project.

Tabs

A portal can have up to 10 tabs. All tabs share the portal’s sign-ins.

1. Right-click the portal and choose New tab.
2. Numbered chips appear on the address strip, with a + for another tab. Click a chip to show that tab.
3. To close the tab you see, right-click the portal and choose Close tab 2 (the number is the tab’s). You can’t close the first tab: it is the portal’s own page.

Agents work with the tab you see. They can also open, switch and close tabs themselves.

What’s next

• Agents working together: wire agents to each other, to notes and to portals.
• cuewire CLI reference: every cuewire portal command.
• Files and the editor: see the code behind the page.

Remote projects

A remote project’s agents run on another machine, reached over SSH or in a WSL distribution. The canvas stays on your computer. The terminals, and the agents in them, run on the host. This page shows how to add a remote project and what happens when the connection drops.

Figure: The canvas is on your computer. The Cuewire server, the terminals and the project folder are on the host.

What you need

• A host that runs Linux on x86_64 or ARM64 (aarch64). A WSL distribution counts.
• For SSH: a host you can reach with ssh from your computer. Keys, an SSH agent or a password all work.
• The agents you want to run, installed on the host.

Add a remote project

1. In the sidebar, click + Remote project (SSH or WSL). A field opens.
2. Type where the project is, in one of these forms:
   • devbox:/srv/app or me@devbox:/srv/app: a folder on an SSH host. A name from your SSH config works.
   • wsl:Ubuntu:/home/me/app: a folder in a WSL distribution.
   • devbox, me@devbox or wsl:Ubuntu alone: Cuewire connects and lets you pick the folder.
3. Press Enter.

Figure: Add a remote project from the sidebar.

The project opens as a workspace named after the folder and the host, for example app on devbox. If Cuewire can’t read what you typed, the field stays open and lists the forms it accepts.

Pick the folder on the host

If you typed only a host, Cuewire connects and opens Choose a folder on devbox.

1. Click a folder to go into it. Click ../ at the top of the list to go back up.
2. When the folder you want is shown, click Open app (Enter). The button names the folder.

Figure: Choose a folder on the host.

The picker lists only folders inside your home folder on the host, or the folders the host’s owner allows. It never follows symbolic links, and shows at most 2000 folders. If the connection fails, it says why and offers Try again.

The first connection

Cuewire needs its server on the host. When it is missing, Cuewire installs it under ~/.cuewire/bin, over the same SSH or WSL connection. It uploads only server files that this build signed. Each file is checked on the host before it is used.

If SSH needs your password or a key passphrase, or sees the host’s key for the first time, Cuewire asks in a dialog:

• Sign in to devbox: type your password or passphrase. The field hides what you type, and nothing you type is stored. Sign in (Enter) sends it; Cancel (Esc) stops.
• Trust devbox?: shows the key’s fingerprint. Choose Yes, trust it (Enter) only if you recognise it. Otherwise choose No (Esc).

Warning

A host key you don’t recognise can mean you are talking to the wrong machine. Check the fingerprint with the host’s owner before you trust it.

Agents on the host

On an empty remote canvas, the Start here card offers the agents installed on the host. Agents that are not installed there are marked (not installed).

• Terminals start in the remote project folder.
• They use your login shell on the host, with its environment. So agents installed through tools such as nvm are found.
• Agents on the host follow the host’s own settings for those agents.

Some features work on your own computer only:

• Layers are not available on remote projects yet.
• Reviews, commits from the layer chip and pull requests run on this computer only.
• Sandbox profiles apply only to agents on your own computer.

Files on the host

File trees and file nodes show the project on the host: its folders, git changes, text and diffs. You can stage and unstage files there too. See Files and the editor.

• Edits are saved on the host.
• If an agent changed the file on the host since you opened it, your save is refused rather than overwriting its change. Reload takes the host’s version.
• Files and diffs larger than 512 KiB are not opened over the connection.

When the connection drops

Agents keep running on the host. Cuewire reconnects by itself. It waits a little longer after each failed try, up to 30 seconds.

While it is not connected, a banner says Reconnecting to devbox · attempt 3, with why the last try failed and when the next one is. Click Reconnect now to try at once. Terminals say Waiting for devbox….

Figure: The connection dropped. The agents keep running on the host while Cuewire reconnects.

When the connection is back, every terminal shows what happened while you were away.

The host keeps the last 4 MiB of each terminal’s output. Sometimes more was printed while you were away. Then, when you scroll back, a strip shows where the kept output begins: History lost · output before the last 4 MiB was not kept.

Two computers, one host

Cuewire keeps the canvas on the host too. So another computer can open the same project.

• If only one side changed the canvas, the change is taken over quietly.
• If both sides changed it, Cuewire asks This canvas changed here and on devbox. Choose Use the host’s copy (Enter), Keep mine, or press Esc to decide later.

One computer drives a host at a time. A second computer watches, read-only. It shows Read-only · another desktop is driving devbox and offers Take over. Taking over makes the other computer read-only.

Figure: Another computer drives this host. Take over to drive it from here.

Note

Your organisation can limit which hosts you may use. Cuewire then says why a host is refused. See For administrators.

What’s next

• Files and the editor: read and edit files on the host.
• Your phone as a companion: answer your agents while you are away.
• Privacy and security: how passwords and server files are handled.

Your phone as a companion

Away from your desk, your phone, or a browser on another computer, can show what your agents need and answer them. This page shows how to pair a device, what it shows, and how its messages stay private.

Figure: Your desktop and your phone talk through Cuewire’s relay. The messages are encrypted end to end, so the relay passes them on but can’t read them.

Before you start

• The companion is part of Cuewire Pro. Sign in first (see Sign in).
• Cuewire must be open on your desktop. The phone talks to the app, not to your agents directly.
• Nothing needs to be installed on the phone. The companion is a web page.

Pair a device

1. On the desktop, press Ctrl+K (Cmd+K on a Mac) and choose Pair a phone or browser…. The Companion sheet opens.
2. Click Pair a device. A QR code and a link appear.
3. On the phone, scan the QR code with the camera. Or copy the link with Copy link and open it on the device.
4. The companion page opens on the device and connects. Its top line says Connected.

Figure: Pair a device. Scan the QR code with the phone’s camera.

The QR code and link are shown only once. Close the sheet and they are gone. To pair another device, click Pair a device again. You can have up to 8 pairings.

Warning

The link holds the key to your pairing. Anyone who opens it can see what your agents ask and answer their questions. Open it only on your own devices. Don’t send it in a chat or an email.

Tip

Add the page to your phone’s home screen. It then opens like an app.

What the companion shows

Figure: The companion on a phone. An agent asks for approval under Needs you.

• Needs you: each question an agent is asking, with the agent’s and the canvas’s name. When one key answers the question, Approve and Deny buttons appear. They press the same keys as the Needs you list on the desktop. When nothing waits, it says Nothing needs you.
• Agents: each agent on the canvas that is open on the desktop, and what it is doing.
• Recently: what the agents did over the last day, such as finished turns, questions and failures.
• Send a prompt: type to an agent. This shows only when the device may send prompts (see below).

If Cuewire is closed on the desktop, the page says The desktop is offline. Open Cuewire there.

Let a device send prompts

A paired device can look and answer questions. It can’t type to your agents until you allow it.

1. On the desktop, open Pair a phone or browser… again.
2. Find the device in the list. It shows the device’s name, when it was paired and whether it is open now.
3. Click May send prompts. It shows a ✓ when it is on.

Figure: A paired device. May send prompts is on.

On the device, Send a prompt appears. Choose the agent under To, type under Prompt and tap Send. Cuewire types the prompt into that agent.

Notifications

The companion can notify you when an agent needs you, even while the page is closed.

1. Open the companion page on the device.
2. Tap Notify me on this device.
3. Allow notifications when the browser asks.

The page then says Notifications are on when this page is closed. To stop them, tap Stop notifications.

Note

On an iPhone or iPad, notifications work only from the home screen. In Safari, tap the share button, choose Add to Home Screen, then open Cuewire from the home screen. Now Notify me on this device appears.

Your desktop sends each notification once, and only while no companion page of that pairing is open.

Unpair a device

To cut a device off:

1. On the desktop, open Pair a phone or browser….
2. Click Unpair next to the device, then Unpair it to confirm.

Cuewire says Unpaired: those devices can no longer reach this computer.

On the device itself, tap forget it here at the bottom of the page. That removes the pairing from that browser.

Privacy

What your desktop and your devices say to each other is end-to-end encrypted.

• The key is in the pairing link, after the #. Browsers never send that part to a server. The key stays on your desktop, in its keychain, and on your paired devices.
• The relay in between passes the messages along without being able to read them. It sees only an anonymous channel id and when messages pass. It keeps nothing.
• Notifications are encrypted for your browser too. The phone’s push service delivers them but can’t read them.

See Privacy and security for more.

When you come back

Were you away from the desktop for five minutes or more? Then a While you were away card sums up what each agent did in the meantime.

What’s next

• Know when an agent needs you: the Needs you list on the desktop.
• Plans, the free trial and pricing: what Cuewire Pro includes.
• Remote projects: run agents on another machine.

Arrangements

An arrangement is a saved set of nodes and wires that you can stamp onto any canvas. Use one for a team of agents you set up again and again, such as a lead, a builder and a reviewer with their notes. This page shows how to save, stamp and manage arrangements.

Figure: Save a canvas or a selection once. Stamp a fresh copy wherever you need it.

Save an arrangement

1. To save part of the canvas, select those nodes first. To save the whole canvas, select nothing.
2. Press Ctrl+K (Cmd+K on a Mac) and choose Save selection as arrangement… or Save canvas as arrangement….
3. Type a name and press Enter. Esc cancels.

Cuewire says, for example, Saved arrangement “Review team” (3 nodes); stamp it from the arrangements panel or the palette.

An arrangement keeps:

• the nodes, where they sit relative to each other, and how they look;
• each agent’s settings, such as which agent runs and its role;
• the wires between the saved nodes;
• the text of its notes.

It leaves out agents’ sessions, unsent prompt drafts and the files notes are kept in. A stamped agent starts a fresh session.

The arrangement library

Press Ctrl+K and choose Show arrangements. The Arrangements panel opens on the right of the canvas. Each card shows a small picture of the arrangement, its name and how many nodes it has.

Figure: The arrangement library. Drag a card onto the canvas, or double-click it.

On each card:

• Stamp adds a copy to the canvas.
• Rename lets you type a new name. Press Enter to keep it.
• Delete removes the arrangement.

After you rename or delete one, the bottom of the panel shows Undo. Click it to take the change back.

To close the panel, click Close, or choose Hide arrangements in the palette.

Stamp an arrangement

Use any of these:

• Drag a card from the panel onto the canvas. The copy lands where you drop it.
• Double-click a card, or click its Stamp button.
• In the palette, choose Stamp arrangement · Review team.

Without a drop point, the copy goes in the middle of the view if there is room. Otherwise it goes to the right of everything on the canvas. Cuewire selects the copy and brings it into view. It says Stamped “Review team”.

Each stamp is a fresh copy. Agents get names that are not taken yet on the canvas. Press Ctrl+Z to take a stamp back in one step.

Tip

Stamp the same arrangement into a new layer’s canvas to give each task the same team. See Projects and layers.

Delete an arrangement

Click Delete on its card, or choose Delete arrangement · Review team in the palette. Deleting an arrangement doesn’t change what you already stamped.

Arrangements on your other computers

Your arrangements are files in Cuewire’s state folder, in arrangements. With settings sync on, they follow you to your other computers. See Settings sync.

Your team’s arrangements

In an organisation, admins can share arrangements with every member. A shared arrangement is marked team on its card, for example 3 nodes · team.

• Members can stamp it, but not rename or delete it.
• Admins see Share on their own cards and Stop sharing on the team’s. Members get a change within a minute.
• A shared arrangement brings only safe settings. Agents start with default options and no agent account. Portals keep only web addresses.

Warning

The Cuewire service can read shared arrangements. Keep keys and secrets out of them, including out of their notes.

See Teams and organisations.

What’s next

• Settings sync: keep arrangements the same on all your computers.
• Roles, models and options: give the agents in an arrangement their roles.
• Teams and organisations: share arrangements with your team.

Settings sync

Settings sync keeps your Cuewire setup the same on all your computers. This page shows how to turn it on, what it carries, and how it keeps your settings private.

Figure: Each computer encrypts your settings with the sync code before they leave it. The service stores copies it can’t read.

What syncs

• Your agent accounts, without their keys and tokens.
• Your agent roles.
• Your concurrency caps (how many agents of each kind may run at once).
• Your saved arrangements.

API keys and tokens never sync. Each computer keeps its own in its system keychain. The theme and window layout also stay with each computer.

Before you start

• Settings sync is part of Cuewire Pro.
• Sign in on each computer, with the same email. See Sign in.

Turn on sync on your first computer

1. Press Ctrl+K (Cmd+K on a Mac) and choose Sync settings…. The Sync settings sheet opens.
2. Click Turn on sync.
3. Cuewire shows your sync code. Click Copy, and keep the code somewhere safe, such as your password manager.

Figure: Your sync code. Your other computers need it.

Warning

Anyone with your sync code and your account could read your synced settings. Paste it only on your own computers.

Add another computer

1. Sign in with the same email on the other computer.
2. Press Ctrl+K and choose Sync settings….
3. Click Use a code from another computer.
4. Paste the sync code and click Turn on with this code.

Cuewire says Sync is on: this computer takes your synced settings now. If the code is wrong, it says That is not a sync code.

Figure: Turn on sync on another computer with the code from the first one.

To see the code again on a computer where sync is on, click Show sync code.

How it works

• Cuewire syncs a minute after it starts, then every minute.
• The sheet shows how it went: Sync is on. Last synced 2 min ago. If a round failed, it says Sync is on, but the last round failed: with the reason.
• Each item syncs on its own. If two computers change the same item, the later change wins.
• When you delete an arrangement, your other computers delete it too.
• An account with a pool of API keys arrives without its keys. Add the keys again on that computer, in Agent accounts….

Your settings stay private

Your settings are encrypted on your computer with a key made from the sync code, before they leave it. The Cuewire service stores only the encrypted copies. It can’t read them.

This also means nobody can recover your synced settings without the code.

Warning

If you lose all your computers and the sync code, your synced settings are gone. Keep the code safe.

Turn off sync

Open Sync settings… and click Turn off on this computer. Cuewire says Sync is off on this computer; your settings stay here. Your other computers keep syncing.

What’s next

• Arrangements: save teams of agents to stamp on any canvas.
• Roles, models and options: roles sync too.
• Privacy and security: what Cuewire sends and keeps.

Sign in

You don’t need an account to use Cuewire. You sign in for the paid plans and for what comes with them, such as the phone companion and settings sync. This page shows how to sign in with an emailed code, and how to sign out.

Figure: There is no password. Cuewire emails you a code each time you sign in.

Sign in with an emailed code

1. Click Sign in at the bottom of the sidebar. The Account sheet opens.
2. Type your email address and click Email me a code, or press Enter.
3. Open the email from Cuewire, with the subject Your Cuewire sign-in code. The code has eight digits, shown in two groups, for example 9914 0758.
4. Back in Cuewire, type the code and click Sign in, or press Enter.

Figure: Type the code from the email. Spaces and dashes are fine.

You are signed in. The button at the bottom of the sidebar now shows your plan, for example Pro trial. A new account starts with a 14-day free trial of Pro. See Plans, the free trial and pricing.

About the code:

• Type it with or without the space. 99140758, 9914 0758 and 9914-0758 all work.
• It expires after 15 minutes, and it works once.
• After five wrong tries, it stops working. Ask for a new one.

Tip

No email after a minute or two? Check your spam or junk folder. Then click Use another email, check the address, and click Email me a code again.

If someone else asks for a code for your address, they can’t use yours. A code works only in the Cuewire app that asked for it. If you get a code you didn’t ask for, ignore the email. Nobody can sign in without the code.

Sign in through your organisation

Your organisation may sign in its members through its own identity provider, such as Okta or Entra ID. Then, after you type your email, Cuewire opens your browser instead of emailing a code.

1. Type your work email and click Email me a code.
2. Your browser opens on a Cuewire page that names your organisation’s provider and your address. Continue there and sign in as usual.
3. When you finish, the browser hands the sign-in back to Cuewire. The Account sheet picks it up by itself.

While it waits, the sheet says Continue in your browser: your organisation signs … in. If you closed the browser tab, click Open the browser again. If it takes more than 10 minutes, Cuewire says Signing in took too long; start again.

See Teams and organisations for how admins set this up.

Your account panel

Click your plan’s name at the bottom of the sidebar to open the Account sheet again. It shows:

• your plan: Free plan, Pro trial, Pro plan, Team plan or Enterprise plan;
• a line about your licence, such as how long it works offline;
• Upgrade to Pro, while you are on Free or on the trial;
• Team…, to start or join an organisation;
• Sign out and Close.

Figure: The Account sheet while signed in, here during the free trial.

Your computers

You can be signed in on up to 5 computers with one account. To sign in on another computer, sign out on one you no longer use.

Cuewire keeps your sign-in in your system’s keychain (Credential Manager, Keychain or the Secret Service), never in a file. It checks your licence when it starts and every six hours.

Sign out

1. Click your plan’s name at the bottom of the sidebar.
2. Click Sign out.

Signing out removes this computer from your account and removes its licence. Cuewire goes back to the Free plan on this computer. Your canvases, notes and settings stay. If you were in an organisation, its shared roles and arrangements go from this computer.

What’s next

• Plans, the free trial and pricing: what each plan includes and how to buy Pro.
• Teams and organisations: work in an organisation.
• Settings sync: use the same settings on all your computers.

Plans, the free trial and pricing

Cuewire has a free plan and paid plans. This page shows what each plan includes, how the free trial works, and how to buy Pro.

Note

Paid plans are being tested before launch. Prices and what each plan includes may still change.

You already pay for your agents. Cuewire never resells model access and never touches your agents’ logins. Its plans pay only for the canvas around them.

The plans

On Free, a fourth agent waits until one of the three running agents stops. Its terminal says Waiting: the Free plan runs 3 agents at once. Plain terminals without an agent don’t count. Free also works with one remote computer: the first one your projects use. A project on a second computer won’t open until you upgrade or remove the first computer’s projects.

The free trial

A new account gets 14 days of Pro, free. You don’t need to enter any payment details.

Figure: The trial. Buy Pro during the trial to keep it. Otherwise Cuewire goes back to Free.

While the trial runs:

• The button at the bottom of the sidebar says Pro trial.
• The Account sheet says Your free trial ends on 2026-11-05. Upgrade to keep Pro after that., with the real date.
• Upgrade to Pro is there. Buy during the trial and you keep Pro when the trial ends.

Figure: The Account sheet during the trial.

If the trial ends without a purchase, Cuewire goes back to Free. Nothing you made is lost.

Buy Pro

1. Click your plan’s name at the bottom of the sidebar. The Account sheet opens.
2. Click Upgrade to Pro. The checkout opens in your browser.
3. Choose monthly or yearly, and pay.
4. Go back to Cuewire. Within seconds, the sidebar says Pro plan.

Paddle, our payment provider, takes the payment. Cuewire never sees your card details.

Note

Cuewire looks for your new plan for 15 minutes after you click Upgrade to Pro. If you pay later than that, Pro arrives at the next licence check. That happens when Cuewire starts, and every six hours.

To buy seats for a team instead, see Teams and organisations.

Working offline

Cuewire checks your paid licence while you are online. A licence then works for 14 days without a connection. The Account sheet says how long, for example Works offline for 12 more days; it renews by itself while online.

The Free plan works offline for good.

Two promises

• Keep what you paid for. After 12 months of your own paid subscription, you keep the paid features for good. That holds even if you stop paying, and offline. It covers every version released up to the end of your paid time.
  • The months need not be in a row.
  • Refunded payments don’t count. Nor does time after a cancellation, the free trial, or a seat your organisation pays for.
  • Once you have it, the Account sheet says, for example, Yours to keep after 12 paid months, in versions released before 2027-11-22.
• Updates are never held back. Security fixes reach every plan, Free included.

What’s next

• Sign in: make an account and start the trial.
• Teams and organisations: buy seats for your team.
• Your phone as a companion: one of the things Pro adds.

Teams and organisations

An organisation puts your team on one Team plan. It shares seats, a policy every member’s app follows, and roles and arrangements. This page shows how to start one, invite people, and run it.

Figure: An organisation. Seats come from the Team subscription. The policy and the shared roles and arrangements reach every member.

Open the Team sheet

Sign in first (see Sign in). Then use either:

• Press Ctrl+K (Cmd+K on a Mac) and choose Team….
• Click your plan’s name at the bottom of the sidebar, then Team….

The Team sheet opens. What it shows depends on whether you are in an organisation, and on your role in it.

Start an organisation

1. Open the Team sheet.
2. Under Start an organisation, type its name.
3. Click Start. Cuewire says Your organisation is ready. Buy seats to invite people.

You are its owner. An account can be in one organisation at a time.

Buy seats

Each member with a seat gets the Team plan. You need seats before you can invite anyone.

1. In the Team sheet, click Buy seats…. The checkout opens in your browser.
2. The number of seats is already set: one for each person in the organisation or invited. You can change it there.
3. Pay. The seats show in the sheet within seconds.

The sheet then says, for example, 3 of 5 seats in use (1 waiting for an answer). To add seats later, click Buy more seats….

Members hold seats in the order they joined. If you reduce the seats, the people who joined last lose theirs. They fall back to their own plan until you add seats again. Nobody is removed.

Invite people

1. Type the person’s email address in Email to invite.
2. The owner can click As member to switch it to As admin, and back.
3. Click Invite.

Figure: The Team sheet of an owner. Each member shows their role. An invitation waits for an answer.

Cuewire emails the person. The email says who invited them and how to accept. An invitation lasts 14 days and holds a seat while it waits. To take it back, click Withdraw next to it.

Join an organisation

When someone invites you:

1. Sign in to Cuewire with the address the invitation went to.
2. Open the Team sheet. It says, for example, Acme invited you as member.
3. Click Join. Or click Decline.

Figure: An invitation, as the invited person sees it.

After you join, Cuewire says You joined. The Team plan and policy apply now.

To leave later, click Leave the organisation at the bottom of the sheet. The Team plan and the policy stop applying to you.

Roles

The owner uses Make admin, Make member and Make owner next to each person. Make owner hands ownership on, and you become an admin.

Note

The owner can leave only after handing ownership to someone else.

The policy

The policy limits what Cuewire may do on every member’s computer. It applies to every member, with or without a seat.

Admins click Change policy in the Policy section. They can:

• Skip permission prompts only in a sandbox;
• Forbid typing into another agent’s terminal, so agents hand over tasks instead;
• choose the Agents allowed (none ticked: any);
• list the Models allowed and Remote hosts allowed, separated by commas (empty: any).

Then they click Save policy. Cuewire says Policy saved. Each member’s app applies it at its next licence refresh. That is within a day. Joining or leaving applies at once.

When the policy blocks something, Cuewire says why where it is refused. For the full policy, including a policy per computer, see For administrators.

Shared roles and arrangements

Admins share a role from the roles sheet, and an arrangement from the arrangement library, with Share. Stop sharing takes it back. Members get the change within a minute.

• Shared roles and arrangements are read-only for members. They are marked as the team’s.
• If a member has a role of their own with the same name, theirs comes first on their computer.

Warning

The Cuewire service can read shared roles and arrangements. That is how new members get them without a code. Keep keys and secrets out of them. Each person’s own settings sync stays end-to-end encrypted.

Single sign-on and directory sync

For larger teams, the owner can connect the organisation to your company’s identity provider, such as Okta or Entra ID.

• Single sign-on (OIDC): people with an address at your company’s verified domain sign in through your identity provider, not with emailed codes. Its sign-in rules and MFA apply.
• Directory sync (SCIM): the people your directory lists are invited, and those it turns off leave.

Admins see both sections in the Team sheet. Only the owner turns them on. Directory sync needs Team seats first. For the steps, see For administrators.

What’s next

• For administrators: policies, SSO, SCIM and deploying Cuewire.
• Plans, the free trial and pricing: what Team includes.
• Arrangements: share an arrangement with your team.

Keyboard shortcuts

This page lists every shortcut in Cuewire. You can reach everything on the canvas without a mouse.

On a Mac, use Cmd where this page says Ctrl, and Option where it says Alt. Inside a terminal, the Mac keys are listed on their own.

Anywhere in the window

On the canvas

Tools

After you choose a tool, click the canvas or drag to size the node. Esc stops the tool.

View

Mouse

Inside a terminal

Every key goes to the program in the terminal, except these:

Ctrl+K stays with the program, because shells use it.

In the find box:

In a note or a file you are editing

Clicking somewhere else also stops editing and saves.

In the prompt box

In the command palette

In text fields

These work in every one-line field: the palette, renaming, sheets and forms.

On a Mac, the word keys use Option instead of Ctrl: Option+Left, Option+Backspace and so on. This is true in the prompt box too.

In dialogs and sheets

Screen readers

Cuewire works with screen readers on Windows, such as Narrator and NVDA, through Windows UI Automation.

• Every button, menu item and field has a name.
• Each node on the canvas is listed in reading order. Its name says its kind and its title. For a terminal, it also says what the agent is doing, for example “Terminal Builder, needs you”.
• The canvas says what is selected as you press Tab.
• Messages on the canvas, such as “View 3 saved”, are read out as status messages. Errors are read out at once.

What’s next

• Commands
• Move around the canvas
• A tour of the window

Commands

This page lists every command in the command palette, grouped by what it is for.

Figure: Type a few letters to filter. Here, lay finds the layer commands.

Use the palette

1. Press Ctrl+K (Cmd+K on a Mac). Inside a terminal, press Ctrl+Shift+P.
2. Type a few letters of the command. They must come in order, but they don’t need to touch: nn finds New note.
3. Press Up or Down to choose, then Enter to run it. Or click it.

The palette shows up to 12 commands at a time. Type more letters to find others. A command’s shortcut, if it has one, is on the right. Some commands only show when they can do something. For example, Rename selection shows only when one node is selected.

Add to the canvas

New nodes appear in the middle of the view.

Move around

To save a view, press Ctrl+Alt+1 to Ctrl+Alt+9. See Move around the canvas.

Edit the canvas

Agents

See Add an agent, Roles, models and options, Usage and limits and Sandboxes and safety.

Layers

The last four show only in a layer other than Base. See Projects and layers and Review your agents’ work.

Arrangements

See Arrangements.

Sound

The palette offers the two volumes you are not using. Choosing a volume also turns the sounds on.

Your devices, account and data

Commands in right-click menus

Some actions are in right-click menus only, such as Lock, Bring to front, Restart and the agent’s options. See A tour of the window.

What’s next

• Keyboard shortcuts
• Troubleshooting
• Glossary

cuewire CLI reference

cuewire is the command that agents use to work together on a canvas. It talks to Cuewire’s bridge: the part of Cuewire’s background service that passes tasks, results and notes between wired agents.

You rarely type it yourself. Agents run it in their terminals, and Cuewire’s cuewire skill teaches them how. Ask an agent in plain words, for example “Ask Reviewer to check this change”, and it picks the command.

• It works only in a terminal on a Cuewire canvas.
• It reaches only the agents, notes and portals wired to that terminal.

To learn how wires, tasks and notes fit together, see Agents working together. The full list of commands follows.

cuewire lets an agent in a Cuewire terminal work with the agents, notes and portals wired to it on the canvas.

Output goes to stdout; errors go to stderr as cuewire: <message> with exit code 2. Run this command inside a Cuewire terminal: it needs CUEWIRE_BRIDGE_SOCKET, CUEWIRE_PEER_ID and CUEWIRE_PEER_TOKEN.

Agents

When you are given a task

Notes

Portals

A target is @e<n> (a ref from snapshot), x,y (a point) or a CSS selector.

ORCHESTRATOR only (the app must have the canvas open)

Agent integrations

Privacy and security

This page lists what Cuewire keeps on your computer, what it may send, and how it protects keys, passwords and messages.

Figure: Your work stays on your computer. Only the items on the right may leave it, and only as described here.

What stays on your computer

Cuewire works without an account. It never sends your code, prompts, file names, notes or messages anywhere. Your canvases, notes and settings are files in Cuewire’s folder on your computer. For remote projects, the canvas is also kept on the host.

The agents talk to their own providers with your own logins. Cuewire never sees, proxies or stores those logins.

What Cuewire sends

Press Ctrl+K (Cmd+K on a Mac) and choose Privacy settings…. The Privacy sheet opens. There you choose what Cuewire may send, and see exactly what is waiting to go.

Figure: The Privacy sheet. Everything waiting to be sent is listed in words.

• Send a crash heartbeat (on unless you turn it off): for each session, whether it ended cleanly, with the version and the operating system. It tells us when a release crashes more than the last one, so that release can be stopped.
• Share usage events (off unless you turn them on): which features are used, as counts and set values such as “an agent started”. Times are rounded to the hour. Never names, paths or text.

Neither carries an account, a device id or anything else that says who sent it. The service keeps only totals.

• Waiting to be sent lists every item not sent yet. Delete what is waiting deletes them.
• Turning a switch off deletes what of it was waiting.
• Cuewire sends a minute after it starts, then every six hours.
• If your organisation turned something off, the sheet says Your organisation turned this off.

What Cuewire reads

• The agents’ local usage logs: Claude Code’s, Codex’s, Gemini CLI’s and Copilot CLI’s logs on your computer, to show token use and limits. Nothing from them leaves your computer. Set CUEWIRE_NO_USAGE=1 to turn this off.
• Your login shell’s environment, on remote hosts: so the agents installed there are found.

Agents reach only what you connect

An agent can see and change only what is wired to it on the canvas: other agents, notes and portals. A task’s text is typed only into terminals that run an agent, never into a plain shell. A reviewer agent runs read-only.

Agents tell Cuewire when they need you through their own hooks. Claude Code posts these events to Cuewire’s background service on your own computer (127.0.0.1). Each post carries its terminal’s own token. Posts without one are refused.

Your account

You need an account only for the paid plans. When you sign in, the Cuewire service keeps:

• your email address, to send you sign-in codes and invitations;
• the names of the computers you signed in on (up to 5);
• your plan, and your organisation if you are in one.

Sign-in codes and sessions are stored on the service only in a scrambled form (as hashes). Your session on your computer is in the system keychain. Paddle, our payment provider, takes payments. Cuewire never sees your card details.

Keys and tokens

API keys and endpoint tokens you give agent accounts are kept in your system’s keychain, never in a file. That is Credential Manager, Keychain or the Secret Service. The same goes for your sign-in, your sync code and each companion pairing’s key.

Synced settings

Settings sync encrypts your settings on your computer with your sync code. The service stores only the encrypted copies and can’t read them. Keys and tokens never sync.

Roles and arrangements your organisation shares are different. The service can read those. See Teams and organisations.

The companion

What your phone and desktop say to each other is end-to-end encrypted. The relay in between sees only an anonymous channel id and when messages pass. It can’t read them, and it keeps nothing. Notifications are encrypted for your phone’s browser, so its push service can’t read them either. See Your phone as a companion.

Remote hosts

• Server uploads: Cuewire uploads only the server files this build signed. Each file’s checksum is checked on the host before it is used.
• Passwords and passphrases: these go straight to SSH. They pass through a connection on your own computer (127.0.0.1) that only the SSH session Cuewire started can use. They are never stored or logged.
• Folders: the host lists only folders inside the folders it allows (your home folder unless configured otherwise), and never follows symbolic links.

Support files

Press Ctrl+K and choose Report a problem…. Cuewire builds a support file and shows it to you in full before it goes anywhere. It holds:

• the version and platform;
• the last crash, if any;
• the end of Cuewire’s logs, which never contain terminal output, prompts or notes.

Your home folder, your name, email addresses and anything that looks like a key are taken out.

Figure: Report a problem. Read the file, then save or copy it.

Nothing is sent from the app. Click Save to a file, Copy or Show in folder, then attach the file yourself.

The audit log

Cuewire keeps a record of security-relevant actions on your computer, such as agents started and companions paired. It never holds prompts. See For administrators.

Reporting a security problem

To report a security problem, contact the maintainers privately before you publish anything.

What’s next

• For administrators: policies, the audit log and deploying Cuewire.
• Your phone as a companion: how pairing works.
• Settings sync: how synced settings stay private.

For administrators

This page is for people who deploy Cuewire and set its rules for a team. It covers the organisation’s policy, single sign-on, directory sync, deployment, a policy per computer and the audit log.

Figure: Two policies can apply on one computer. Whatever either one forbids stays forbidden.

Your organisation

You run your organisation from the Team sheet: press Ctrl+K (Cmd+K on a Mac) and choose Team…. Starting an organisation, buying seats, inviting people and roles are explained in Teams and organisations. In short:

• Seats come from the Team subscription. Admins buy them with Buy seats…, later Buy more seats…. Members hold seats in the order they joined.
• Invitations go to an email address. They last 14 days and hold a seat while they wait.
• Admins invite and remove members, set the policy, and share roles and arrangements. Only the owner makes admins, removes them, hands ownership on, and sets up directory sync and single sign-on.

The organisation’s policy

Admins set the policy in the Policy section of the Team sheet, with Change policy:

• Skip permission prompts only in a sandbox;
• Forbid typing into another agent’s terminal (raw keystrokes from cuewire ask --raw);
• the Agents allowed;
• the Models allowed and the Remote hosts allowed.

Figure: Changing the organisation’s policy.

The policy applies to every member, with or without a seat. Each member’s app applies it at its next licence refresh, within a day. Joining or leaving applies at once. The policy travels in each member’s signed licence, so members can’t change it.

Single sign-on (OIDC)

Members at your company’s email domain can sign in through your identity provider instead of with emailed codes. Okta, Entra ID and any OpenID Connect provider work. Then the provider’s MFA and access rules apply.

1. Verify your domain. In the Single sign-on section, the owner types the domain (for example example.com) and clicks Claim. Cuewire shows a DNS TXT record: _cuewire-verify.example.com with a value cuewire-verify=…. Add it in your DNS. Click Copy value to copy the value. Then click Check. A domain can belong to one organisation only.
2. Register Cuewire with your provider as a web application that uses the authorization code flow. Use the redirect URI https://api.cuewire.dev/v1/sso/callback. Note the issuer URL, the client ID and the client secret.
3. Turn it on. The owner types the Issuer URL, Client ID and Client secret in the sheet and clicks Turn on single sign-on. Cuewire reads your provider’s discovery document to find its endpoints.

Figure: A claimed domain waits for its TXT record. Click Check once it is published. (This picture was taken with a test service; your redirect URI starts with https://api.cuewire.dev.)

From then on, anyone who signs in to Cuewire with an address at a verified domain goes to your provider in their browser:

• A first page names your provider and the address. When they finish at the provider, the browser hands the sign-in back to the Cuewire app on their own computer.
• Sign-in for those addresses works from the app only, not from a link someone else sent.
• The provider must sign in the same address that was typed.
• The owner keeps signing in with codes. So a provider outage can’t lock the organisation out.

Turn off single sign-on, or removing the domain, brings codes back for those addresses.

Warning

Keep the TXT record published. Cuewire looks for it again every day. A domain whose record is missing three days in a row stops counting as verified.

Directory sync (SCIM)

Connect Okta, Entra ID or any SCIM 2.0 provider. The people it lists are invited, and those it turns off leave.

1. In the Directory sync section, the owner clicks Turn on directory sync. Your organisation needs Team seats first. Only the owner can do this, since the directory can remove admins.
2. Cuewire shows the base URL and a token, once. Click Copy token.
3. In your identity provider, add a SCIM 2.0 app. Use the base URL https://api.cuewire.dev/scim/v2 and the token as a bearer token (Okta: “HTTP Header”; Entra: “Secret Token”). Turn on creating, updating and deactivating users. Group push isn’t used: assign people to the app.
4. Assigned people see an invitation from your directory when they sign in to Cuewire with their work address. It reads, for example, Acme’s directory lists you: join as a member. It doesn’t expire, and holds no seat until they join.

The section then shows, for example, On: 12 listed, 10 active, 2 not joined yet.

When the provider deactivates or deletes someone, they leave the organisation. Its plan and policy stop applying to them at their app’s next licence refresh. The owner is never removed this way: hand ownership on first. People you invited by hand are left alone until the directory lists them.

• New directory token gives a new token, and the old one stops working.
• Turn off directory sync stops the token and withdraws the directory’s waiting invitations. Members stay.

Deploy Cuewire

On Windows, Cuewire installs per user, without administrator rights. To deploy it with your device management (for example as an Intune Win32 app installed in the user’s context), run:

CuewireSetup-<version>-x86_64.exe --silent

It installs into the user’s %LOCALAPPDATA%\Programs\Cuewire. It registers a quiet uninstall command (uninstall.exe --uninstall --silent) under the entry com.cuewire.desktop. Use that entry to detect the install. Installed this way, Cuewire updates itself.

A policy for this computer

You can also set a policy per computer. Put a managed-policy.json in the machine-wide folder, for example with your device management:

Cuewire reads it when it starts. Every field is optional. Leave a field out to allow anything:

{
  "allowed_presets": ["claude_code", "codex"],
  "allowed_models": ["sonnet", "opus"],
  "sandbox_required_for_skip": true,
  "remote_hosts": ["*.corp.example", "wsl:Ubuntu"],
  "update_channel": "stable",
  "max_telemetry": "heartbeat",
  "forbid_raw_input": true
}

With a Team plan, your organisation’s policy arrives with each person’s licence. The two are combined: whatever either forbids stays forbidden.

Warning

A file that is there but can’t be read blocks agents, remote projects and telemetry until it is fixed. Cuewire says why where something is refused.

The agents’ own managed settings

Cuewire honours the settings you deploy for the agents themselves. It never asks an agent for what they forbid.

Settings an agent gets from its own service or from device management (registry, configuration profiles) are applied by the agent as usual. Cuewire reads only the files. A file Cuewire can’t parse restricts nothing on Cuewire’s side, because the agent itself still enforces it. Agents on a remote host follow that host’s settings.

The audit log

Cuewire keeps a record of security-relevant actions in audit/audit.jsonl in its state folder:

• agents started, with whether they skipped permission prompts or were held read-only;
• launches and remote hosts a policy refused;
• sign-in and sign-out, settings sync, telemetry choices and role rules;
• companions paired and unpaired, and what a companion approved or prompted (never the prompt’s text);
• what orchestrator agents changed on the canvas: agents recruited (with their agent and role), dismissed or wired together, notes added, portals opened (with their address).

Beside it, audit/host.jsonl is written by the background service that runs the agents. It holds every task one agent handed another (who to whom, never the prompt), and every raw keystroke input one agent typed into another’s terminal.

A remote Linux host keeps its own log, in ~/.local/share/cuewire/audit/host.jsonl there. The computer that drives it keeps a copy in audit/remote/. It fetches the copy when it connects and every ten minutes after, and exports and sends it with its own logs.

Each record holds the hash of the one before it. So a changed, removed or reordered record shows.

Export the audit log

Press Ctrl+K and choose Export audit log…. Cuewire checks each log’s chain and saves copies, as JSON lines, to your Downloads folder, for your SIEM. It then says, for each log, how many records it saved and whether the chain is intact.

Send it to a collector

To have every computer send its log to your OpenTelemetry collector (or any service that takes OTLP/HTTP JSON logs), add audit_export to managed-policy.json:

{
  "audit_export": {
    "otlp_logs_url": "https://otel.corp.example:4318/v1/logs",
    "headers": { "x-api-key": "…" }
  }
}

• Each record becomes one log record. Its action is the body, and its fields are attributes named cuewire.<field>. cuewire.audit.log says which log it came from (app or host). cuewire.audit.seq, cuewire.audit.prev and cuewire.audit.hash come with it, so you can check each chain on your side. Refusals are WARN; everything else is INFO.
• The resource names the app (service.name = cuewire, service.version), the install (service.instance.id) and the computer (host.name).
• New records go within seconds. If the collector is down, Cuewire keeps them and tries again, waiting up to 15 minutes between tries. So none is skipped. A new URL gets the whole log.
• The URL must be https://. Plain http:// works only to the computer itself.

Note

Cuewire reads audit_export only from the computer’s own file, never from a Team licence, because its headers may hold a key.

What’s next

• Teams and organisations: seats, invitations and roles.
• Privacy and security: what Cuewire sends and keeps.
• Sandboxes and safety: sandbox profiles for agents.

Troubleshooting

This page lists common problems and how to fix them. If yours is not here, ask for help and attach a support file. See Report a problem.

Figure: When an agent can’t start, its terminal says why.

An agent does not start

Look at the terminal first. When an agent can’t start, the terminal says why, in a line such as Codex can’t start: codex is not installed (it is not on PATH).

The agent is not installed

Cuewire runs each agent’s own command-line tool. It looks for the tool on your PATH:

On the Start here card, an agent Cuewire can’t find shows (not installed).

1. Install the agent’s tool, as its maker describes.
2. Open a new terminal outside Cuewire and run the tool, for example codex --version. If this fails, the tool is not on your PATH yet.
3. Quit Cuewire with Ctrl+Q and open it again. Cuewire looks for agents when it starts.
4. Right-click the terminal and choose Restart.

The terminal says “… is only installed as a script …”

On Windows, Cuewire found only a script for the agent, such as a .bat, .ps1 or .cmd file. Cuewire does not run these scripts. Windows runs them through cmd.exe, which could read parts of a prompt as commands.

Most tools installed with npm are different. Their .cmd script only starts Node.js on the tool’s JavaScript file. Cuewire starts Node.js on that file itself, without the script. For example, npm install -g @google/gemini-cli works for Gemini CLI.

To fix it, install the agent’s native build (its .exe). Then quit Cuewire, open it again, and restart the terminal.

The terminal says “… installed with npm …, but Node.js was not found”

The agent was installed with npm, so Cuewire starts it with Node.js. Cuewire looked for node.exe next to the agent’s script and on your PATH, and found neither.

1. Install Node.js from nodejs.org.
2. Open a new terminal outside Cuewire and run node --version. If this fails, Node.js is not on your PATH yet.
3. Quit Cuewire with Ctrl+Q and open it again.
4. Right-click the terminal and choose Restart.

The terminal says “Waiting: … (the cap; change it under Usage)”

You set a limit on how many agents of one kind may run at once. The new agent waits until one of the others stops. To raise the limit:

1. Click the usage chip at the bottom left.
2. Under At once (concurrency caps), click + next to the agent.

The waiting agent starts as soon as there is room.

The terminal says “Waiting: the Free plan runs 3 agents at once …”

The Free plan runs up to 3 agents at the same time. The new agent waits, and starts by itself as soon as one of the others stops. Stop an agent you don’t need, or upgrade to Pro for no limit. See Plans, the free trial and pricing.

“… can’t be opened: the Free plan works with 1 remote computer”

Your projects already use another remote computer, and the Free plan works with one. Upgrade to Pro, or remove that computer’s projects from the sidebar.

The terminal says “Process exited” or “Process failed”

The program in the terminal ended. Scroll up to read its last output. Then right-click the terminal and choose Restart.

The terminal says “can’t start” for another reason

Read the rest of the line. It names what stopped the agent, for example:

• … can’t start in its sandbox: Docker is needed …: the project runs agents in a sandbox, and Docker is not installed. See Sandboxes and safety.
• … your organisation does not allow …: your organisation’s policy forbids this agent or this option. Ask your administrator. See For administrators.

The terminal says “Draft in this layer”

The terminal came with a new layer and has not started yet. Right-click it and choose Start in this layer. See Projects and layers.

Terminals stay on “Starting the terminal service…”

Cuewire can’t reach its background service, which runs every terminal.

1. Wait a few seconds. The service may still be starting.
2. If an error shows instead, read it.
3. Quit Cuewire with Ctrl+Q and open it again.
4. If it still fails, report a problem. The support file holds the end of the service’s log.

A prompt is not sent

• Select one or more agents to prompt: the selection has no agent. A terminal that runs a plain shell takes no prompts. Select an agent’s terminal and try again.
• None of them is running; start them first: the agents have not started yet, or have stopped. Wait for them, or right-click and choose Restart.

Codex shows “Hooks need review”

Codex asks you to trust the hooks that Cuewire gives it. Press 2 to choose Trust all and continue, then press Enter. See Trust Cuewire’s hooks in Codex.

Codex’s reason is always “Would you like to run the following command?”

Codex’s hooks don’t run, so Cuewire reads its screen. Check these:

• Codex is 0.162 or newer. Open a terminal outside Cuewire and run codex --version.
• You trusted the hooks. If not, quit Cuewire, open it again and start Codex. Codex asks once more.
• Codex runs on this computer. Agents on a remote computer or in a sandbox always use the screen.

After you update Codex, quit Cuewire and open it again. Cuewire checks the version when it starts.

Two nodes don’t connect

Cuewire says these nodes cannot be connected; a terminal connects to a terminal, a note, or a portal. Wires always have a terminal at one end. Two notes, for example, can’t be wired.

The sign-in code does not arrive

When you sign in, Cuewire emails you a code.

1. Look in your spam or junk folder. Mark the email as not spam, so the next one arrives.
2. Check the address in Enter the code sent to …. If it is wrong, click Use another email and type it again.
3. Wait a minute, then ask for a new code with Email me a code.

A code works for 15 minutes. See Sign in.

The phone shows only the heading

The companion page did not load fully on your phone.

1. On the phone, close that browser tab.
2. On the desktop, open the command palette and choose Pair a phone or browser….
3. Choose Pair a device and scan the new code with the phone.

See Your phone as a companion.

Windows says “Windows protected your PC”

This build of Cuewire is not signed. Click More info, then Run anyway, if the file came from the Cuewire team. See Install Cuewire.

“Workspace was not saved”

A red message at the top left says Workspace was not saved: and the reason. Cuewire could not write your canvas to disk.

• Check that your disk has free space.
• Check that you can write to %LOCALAPPDATA%\Cuewire.

Cuewire tries again with your next change. The message goes away once a save works.

“This canvas was saved by a newer Cuewire”

The canvas was saved by a newer version of Cuewire, maybe on another computer. You can look at it, but Cuewire does not save changes to it. Install the newer version. See Update Cuewire.

No notifications or sounds

• Windows notifications come only when Cuewire is in the background, or the agent is off screen. Check that Windows allows notifications from Cuewire.
• For sounds, open the command palette. If it offers Turn sound cues on, the sounds are off. Choose it to turn them on. Sound volume: … sets how loud they are.

Where the logs are

Cuewire writes a log every day:

The logs hold no terminal output, prompts or note text.

Which version do I have?

Click Cuewire at the top of the sidebar. Or open the command palette (Ctrl+K) and choose About Cuewire. The About Cuewire window shows:

• Version: the release, for example 0.1.0;
• Commit and its date: the exact code this build was made from;
• Built: when this build was made;
• Background service: the version and commit of the service that keeps your agents running;
• System: your operating system.

Click Copy to put all of it on the clipboard, for example to paste into a message.

Figure: About Cuewire. Your version and commit will be different.

Note

After an update, the background service keeps running its old build until it restarts, so your agents keep running. Then About says The background service runs another build. Click Update ready in the sidebar when you are ready, or quit Cuewire while no agent runs.

Report a problem

When you ask for help, attach a support file. You read all of it before it leaves your computer.

1. Open the command palette (Ctrl+K) and choose Report a problem….
2. Read the support file. It holds the Cuewire version and commit, your platform, the last crash, and the end of the app’s and the service’s logs. Cuewire takes out your home folder, your name, email addresses and anything that looks like a key.
3. Click Save to a file. The file goes to your Downloads folder, named cuewire-support-<number>.txt. Or click Copy.
4. Click Show in folder to find the file.
5. Attach the file where you ask for help.

Cuewire sends nothing by itself from this sheet.

Figure: Report a problem… shows the whole support file before you save it.

What’s next

• Keyboard shortcuts
• Glossary
• Install Cuewire

Glossary

This page explains the words this manual uses, in alphabetical order.

Agent

An AI coding tool that runs in a terminal on the canvas, such as Claude Code or Codex. You choose a terminal’s agent under Runs in its right-click menu. See Add an agent.

Agent account

The account an agent signs in with. An agent uses this computer’s own sign-in unless you give it another account in Agent accounts…. See Roles, models and options.

Arrangement

A saved set of nodes and wires that you can add to any canvas again. Agents in it start fresh, and notes keep their text. See Arrangements.

Attention

What Cuewire knows about what each agent is doing: working, waiting for input, waiting for approval, done or failed. Cuewire learns it from the agent’s own reports or from its screen. See Know when an agent needs you.

Background service

The program that runs your terminals, cuewired. It keeps running when you close Cuewire, so your agents keep working. See Workspaces and canvases.

Base

The layer that is your project folder itself. Every canvas starts in Base. See Projects and layers.

Canvas

The large surface where your nodes are. You pan and zoom it. A workspace can hold several canvases. See Move around the canvas.

Command palette

The list of every command in Cuewire. Press Ctrl+K to open it, then type to filter it. See Commands.

Companion

A phone or a browser that you paired with Cuewire. It shows which agents need you, and you can answer them from it. See Your phone as a companion.

Concurrency cap

The most agents of one kind that may run at the same time. You set it in the usage panel, under At once (concurrency caps). See Usage and limits.

Connection

Another word for a wire.

cuewire command

The command agents use inside their terminals to hand each other tasks, read notes and use portals. Cuewire teaches each agent how to use it. See cuewire CLI reference.

Draft

A terminal that has not started yet. In a new layer, every terminal starts as a draft. Right-click it and choose Start in this layer to run it.

File, file tree

A file tree is a node that lists your project’s files and their git status. A file node shows one file: its text or its changes. See Files and the editor.

Group

Nodes kept together. Select two or more nodes and press Ctrl+G. Drag the group’s tab to move them all. See Terminals, notes and shapes.

Label

A node with a short title in large text. Use it to name an area of the canvas.

Layer

A separate copy of your project for one task. A layer is a git worktree with its own copy of the canvas, so agents in it can’t touch your main checkout. See Projects and layers.

Layer chip

The button at the top left of the canvas. It shows the layer you are in, and its menu lists the others.

Lock

A locked node can’t be moved, resized, renamed or deleted. Right-click a node and choose Lock or Unlock.

Needs you

An agent needs you when it waits for your answer or your approval. The Needs you list at the top right shows every such agent, most urgent first. See Know when an agent needs you.

Node

Anything on the canvas: a terminal, a note, a browser portal, a file tree, a file, a label, a rectangle or a text block. See Terminals, notes and shapes.

Note

A node with text that you and your agents share. Agents wired to a note can read it and change it.

Orchestrator

An agent that may change the canvas: add and remove agents, add notes and portals, and wire them. Turn it on in the agent’s right-click menu. See Roles, models and options.

Plan

The Cuewire plan of your account, for example Free plan or Pro plan. The account button in the sidebar shows it. See Plans, the free trial and pricing.

Portal

Short for browser portal: a node that shows a web page. Agents wired to it can use the page. See Browser portals.

Preset

The program a terminal runs: a plain shell, or one of the agents Cuewire knows. You choose it under Runs in the terminal’s right-click menu.

Project

A folder with your code. Each project you add becomes a workspace in the sidebar.

Prompt box

The box where you write a prompt for one or more agents. Select the agents and press Ctrl+Enter. It is named after them, for example Prompt · Builder.

Rectangle

A coloured box on the canvas. Use it to mark an area.

Relay

The Cuewire server that passes messages between your computer and your companion. The messages are end-to-end encrypted, so the relay can’t read them.

Remote project

A project on another machine, reached over SSH or in WSL. Its agents run on that machine. See Remote projects.

Review

A check of the work in a layer. Review changes adds a reviewer agent, which may only read, and a review note for its findings. See Review your agents’ work.

Role

Instructions given to an agent when it starts. A role can also hold the agent to rules, such as read-only. Cuewire has two built-in roles, Builder and Reviewer. See Roles, models and options.

Sandbox

A container that an agent runs in. It sees only its layer’s files. A project sets it up in .cuewire/layers.toml, and it needs Docker. See Sandboxes and safety.

Saved view

A place and a zoom level on a canvas, kept in a slot from 1 to 9. Ctrl+Alt+3 saves one, and Alt+3 goes back to it.

Session

An agent’s conversation. Cuewire remembers each agent’s session, so the agent can pick it up again after a restart, if the agent supports that.

Settings sync

Keeps your agent accounts, roles, concurrency caps and arrangements the same on all your computers. Keys stay on each computer. See Settings sync.

Shell

A plain command line with no agent in it. Choose Terminal on the Start here card, or Shell under Runs.

Skill

A short guide an agent reads to learn a tool. Cuewire installs one named cuewire into your agents’ settings, so they know how to use the cuewire command. See Agents working together.

Skip permission prompts

An agent option. The agent acts without asking you first. Your organisation can allow it only inside a sandbox.

Start here

The card on an empty canvas. It helps you open a project, add an agent and connect agents.

Support file

A text file that Report a problem… makes. It helps someone find out what went wrong. You read all of it before you save it. See Troubleshooting.

Task

Work that one agent hands to another over a wire, with the cuewire command. The other agent does the work and reports back. See Agents working together.

Terminal

A node that runs a real terminal, with a shell or an agent in it.

Text

A node with a block of smaller text.

Tidy up

A command that arranges your agents by who hands tasks to whom, with their notes and portals under them.

Toolbar

The row of tools at the bottom of the canvas: Select, Terminal, Note, Rectangle, Label and Text.

Usage chip

The button at the bottom left of the canvas. It shows how many tokens your agents used in the last 24 hours. Click it for more. See Usage and limits.

While you were away

A card that sums up what each agent did while you were gone. It shows when you come back after five minutes or more.

Wire

A line between two nodes that lets them work together. Two wired agents can hand each other tasks. An agent wired to a note can read and change it. An agent wired to a portal can use its page. See Agents working together.

Workspace

One project in the sidebar. It holds one or more canvases, which all work in the project’s folder. See Workspaces and canvases.

Worktree

A git feature: a second checkout of the same repository, in its own folder. Each layer is a worktree. See Projects and layers.

What’s next

• Keyboard shortcuts
• Commands
• Welcome to Cuewire