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