Docs/The Director/Starting and steering agents
Director

Starting and steering agents

5 min read

This page covers the two verbs of the Director: starting an agent session and steering it while it runs - answering questions, queueing the next task, and stopping it when it goes down the wrong path.

Start a new session

  1. Open the New Session dialog

    Click New Session in the toolbar (or press Ctrl+N). The dialog also has tabs for Named Sessions and Resume Session - more on those below.

  2. Pick the agent

    The agents you have configured appear as a row of choices, with the first one preselected. Claude Code and Pi ship with verified drivers and are always available; you manage the list under Settings - Agents. Choosing Custom CLI lets you point the session at any command-line tool by giving its command and arguments.

  3. Pick the repository

    Choose the folder the agent will work in - the dialog lists the repositories you have used, sortable by name, path, or last used, and a Browse button picks any folder. The agent edits real files in that folder, so for a first run start somewhere low-stakes.

  4. Decide about permission prompts

    Bypass permission prompts is checked by default: the agent works without stopping to ask before each tool action. Uncheck it if you want to approve actions as they happen - the session's card will flip to Permission each time the agent wants a decision.

  5. Start

    A new card appears in the Director and the agent launches in its terminal. Give it the first task from the prompt bar - or set the task up front with a named session.

Named sessions and resuming

Named Sessions are saved presets - a repository plus an agent under a name you choose, launched with one click. Save any running session as a named session from its card menu. Resume Session lists your past Claude Code conversations with a summary, message count, and how long ago they ran.

The prompt bar

The prompt bar below the terminal: the message box with the Expand button in its corner, and Send, Speak and Queue stacked down its right-hand side, the Queue button red and reading Queue (3)
The prompt bar under the terminal with the Send, Speak, Queue, and Expand buttons
  • Send (Ctrl+Enter) - type a message and send it into the terminal.
  • Queue (Ctrl+Shift+Enter) - add the message to the session's queue instead of interrupting; it waits there until you send it.
  • Speak (Ctrl+H) - dictate instead of typing. See voice.
  • Expand - open a large editor for long prompts, with image preview for screenshots you attach.
Tip
Queueing is the habit that makes multiple agents work. While an agent is busy, line up its next two or three tasks with Ctrl+Shift+Enter - the Queue panel on the right shows the line, and you can reorder, edit, or delete items before you send them. Nothing leaves the queue on its own, so when you come back to an agent that has stopped, the next instruction is already written and waiting.

Stop, interrupt, compact, and clear

The action bar - the row of buttons at the top of the prompt bar, under the terminal - gives you graduated brakes:

  • Stop - the agent's own soft cancel (Esc). Ends the current turn; the conversation continues.
  • Interrupt - a hard interrupt (Ctrl+C), stronger than Stop, for when the agent will not let go.
  • Compact - summarize the conversation so far, freeing room in the context window. The session keeps what it has learned. Asks for confirmation first, and can take a minute or two.
  • Clear context - reset the conversation in place while the process keeps running - a fresh start without a new session. Asks for confirmation first; it cannot be undone.
  • History - open the agent's in-terminal history picker to jump back to an earlier point.

The buttons are drawn from what each session's agent can actually do, so the bar differs by agent: a verb the agent's CLI does not support is simply absent. Claude Code shows all five; pi has Stop but no Interrupt, because Ctrl+C means something else entirely in pi; Cursor and Copilot have only Interrupt; History is Claude Code's alone.

For agents that can report their context usage - Claude Code, Codex and pi - the action bar also shows a context-window gauge - how full the agent's working memory is - which is your cue to compact, clear context, or wrap up the task.

Answering an agent

When a card turns red, click it, read the question in the terminal, and answer in the prompt bar. If the card shows Permission, the agent is asking to run a specific action - approve or deny it right in the terminal. Then get out of the way; the card goes blue and you go back to whatever you were doing.

Note
You do not have to be at the desktop to answer. The same sessions can be driven from the Cockpit in a browser and from your phone - including by voice.

The card menu

The "..." menu on each card: Rename; Snooze (or Unsnooze), with a Snooze for submenu offering other lengths once this desktop has learned them; Open in Explorer and Open in VS Code; Copy Handover Info, Save as named session, and Relink Session; and Close Session.

Warning
Closing a session ends the agent process. Your files keep every change the agent made, but anything the agent was mid-way through stops where it stands.