Coding sessions

An agent works on a task in a session. Each role of a task, such as the Spec agent or the Builder, has its own session.

The session pageCopy Anchor Link

123456

1. 1

   Sidebar

   Your sessions, in Needs you, Running, and Recent. A session that waits for you shows in Needs you.

2. 2

   Workflow rail

   The roles of the task, in order. A check marks a finished role. Select a role to open its session.

3. 3

   Next step

   The button that starts the next step of the task, for example Start Spec.

4. 4

   Transcript

   The agent works here. You see its messages, its commands, its file edits, and its questions.

5. 5

   Composer

   Type a message to the agent. Type @ for files, / for commands, and $ for skills.

6. 6

   Right panel

   The artifacts, diffs, files, and CI checks of the task. Select + to open a terminal or a web page.

Follow the agentCopy Anchor Link

When the agent moves the task, a card with the event as its title shows in the transcript, for example Build Completed. Select the title to read the note of the agent. When the agent saves the pull request of the task, a Set Pull Request card shows it.

Start a sessionCopy Anchor Link

1. On a task card, or in the top bar of the session page, select the button of a role, for example Start Spec.
2. In the dialog, check the model, then select Start session. The session page opens and the agent starts.

Send messagesCopy Anchor Link

To add a reference to a message, type its key in the composer, then select an item in the menu.

A reusable prompt must be at the start of the message. A message with a reusable prompt cannot also have files, skills, subagents, or attachments.

Queue a messageCopy Anchor Link

While the agent works, Enter queues your message. The queued messages show above the composer. When the agent ends its turn, it gets the oldest queued message. Each next message waits for the end of the next turn.

To send a queued message to the agent at once, while it works, point to the message and select Steer now, the lightning icon.

To send a new message to the agent at once, press Cmd+Enter on macOS or Ctrl+Enter on Windows and Linux. To swap the keys, see Steer messages by default.

If you stop the agent or a reply fails while messages wait in the queue, Queue paused shows above the composer. To send the queued messages, select Resume queue.

Fork from a replyCopy Anchor Link

To try another way, select Fork from this reply on a reply of the agent. A new session of the same role starts with the conversation up to that reply, and it opens. The first session does not change.

Work toward a goalCopy Anchor Link

export function useSearchShortcut(openSearch: () => void): void;

In Goal mode, the Builder gets a goal instead of a first message. Its harness then starts each next turn by itself, until the goal is met.

Start in Goal modeCopy Anchor Link

1. Select Start Builder, Address QA Feedbacks, or Request Changes. Only these steps show Goal mode.
2. Turn on Goal mode. The Goal field shows a default goal: the outcome, and the conditions that must be true at the end.
3. Edit the goal, or select Generate goal. A model writes a goal from the task, its documents, and the default goal.
4. Select Start session.

• The agent gets only the goal. Customize first message hides while Goal mode is on. A goal can have 4000 characters.
• Generate goal uses the Default model of the repository, and the Goal Writer prompt. Without a default model, the button is off.
• Your harness must support goals. If it does not, the switch is off and tells you why. See Goal mode support.
• Autopilot never starts a session in Goal mode.

Follow the goalCopy Anchor Link

The goal row shows above the composer: Goal, the status, and the objective. Select the row to read the whole goal.

The row has Pause goal, Resume goal, and Clear goal. Some harnesses can only clear a goal.

A goal does not end when the task moves to another lane. The Builder can keep working after it reports the build as completed, until the goal is met. Before OpenDucktor removes a task worktree, it stops the sessions that work on a goal.

Set a goal with /goalCopy Anchor Link

In the composer of a session, type /goal, then the objective, and send the message. The message shows a Goal chip. To change a running goal, send /goal pause, /goal resume, or /goal clear.

• A /goal message holds only text, with no files or attachments.
• While the agent works in a normal turn, a /goal message waits in the queue. You cannot steer it.
• While a goal drives the work, your other queued messages wait until the goal stops. A /goal message applies at once.

Answer the agentCopy Anchor Link

When an agent asks a question, needs a permission, or reports that the task is blocked, its session moves to Needs you. The agent waits until you answer. You can also answer from your phone. See Answer the agent.

Answer a questionCopy Anchor Link

1. In the sidebar, select the session in Needs you.
2. Select an option, and the next question opens. To write your own answer, select Other answer, then Next.
3. After the last question, select Confirm Answers. The agent continues, and the session moves to Running.

To answer without opening the session, point to its row in Needs you. A preview opens with the question. Answer it there, or select Open session.

123

1. 1

   Needs you row

   The session that waits for you. Point to it to open the preview.

2. 2

   Preview

   The question of the agent. Select an option, then Confirm Answers.

3. 3

   Open session

   Opens the full session page.

Reply to a permission requestCopy Anchor Link

An agent asks for a permission before it does some actions, for example before it runs a command. Select a reply on the Approval required card.

Some harnesses also show these replies:

To get fewer requests, set the permissions of each harness.

Review the workCopy Anchor Link

Open the Diffs tab. Branch changes compares the task branch with its target branch.

To comment on a line, point to it and select + in the gutter. The agent gets your comments with your next message.

1234

1. 1

   Views

   Uncommitted changes, Branch changes, and History.

2. 2

   Changed files

   Search the files. Select a file to open its diff.

3. 3

   Diff

   The removed lines in red and the added lines in green.

4. 4

   Comment

   Your comment on line 11. The agent gets it with your next message.

NextCopy Anchor Link