---
audience: power_user
summary: Get an AI to commit to a multi-step plan, then supervise it as it executes.
title: Use the planner
path: tutorials/power-user/use-the-planner
status: published
---

# Use the planner

The planner is what turns "do this thing for me" from a guessing
game into a contract.

## 1. Ask in a way that invites a plan

The AI decides on its own whether to plan. It's biased toward
planning when:

- The task has multiple distinct steps.
- Each step likely needs its own tool call.
- The work would take more than ~30 seconds of back-and-forth.

Phrasings that tend to trigger a plan:

- *"Research three vector databases for our use case and compare
  them on pricing, latency, and hybrid search support."*
- *"Audit the `auth` module: list every route, what scopes it
  requires, and any inconsistencies."*
- *"Migrate the `2026-03 reports` notes to the new naming
  convention. There are about 40 of them."*

Phrasings that don't:

- *"What's the capital of France?"* — one tool call max, no plan.
- *"Summarise this conversation."* — single turn, no plan.

## 2. The plan card

The first thing the AI does is call `plan(action="write", goal, steps)`.
A **plan card** mounts above the chat showing:

- The goal it's about to pursue.
- A checklist of steps with status glyphs (○ ▶ ✓ ✗ —).
- The current step (underlined).
- An auto-budget indicator (⚡N) — how many more steps the AI can do
  before pausing for your check-in.
- Buttons: **Pause**, **Resume**, **Cancel**.

Read it. If the plan is wrong, say so — *"That's not what I want.
Cancel and try again with X."* The AI will revise.

## 3. Let it work

With `advance=auto` (the default), the AI works through steps in the
same turn — no extra prompts needed. As each step completes, the
glyph flips to ✓ and the next one starts.

For long plans, the auto-step budget (default 8) is the throttle.
After 8 consecutive auto-advances without your input, the harness
pauses the plan and waits for you to send anything. (Sending
anything resets the budget.)

## 4. Step results

Each completed step has a one-line **result** the AI fills in. Click
the **+** next to a step in the plan card to expand it and see the
result inline. Useful when reviewing what happened or backing out a
plan.

## 5. When something goes wrong

A failing tool call doesn't kill the plan. The AI sees the error
plus a harness nudge:

> Plan harness: this is step 3/5, attempt 1/3. If the error suggests
> fallbacks, try the one that fits the user's intent.

It'll typically try a different approach. After 3 attempts on the
same step, the plan force-pauses and waits for you.

You can also force the AI's hand:

- *"Skip that step."* → AI calls `step_failed(next="skip")`.
- *"Stop, the plan is wrong, let me think."* → AI calls
  `step_failed(next="revise")` or you click **Pause**.

## 6. Supervisor controls

Any room member can:

- **Pause** — the AI stops at the current step. Plan stays in
  `paused`.
- **Resume** — back to `running`. Auto-budget resets.
- **Cancel** — terminate. If `venue=sidekick`, the sidekick task is
  killed too and your concurrency budget frees up.

These are REST-backed:

- `POST /v1/rooms/{room_id}/plan/pause`
- `POST /v1/rooms/{room_id}/plan/resume`
- `POST /v1/rooms/{room_id}/plan/cancel`

## 7. Sequential vs. parallel mode

The default is **sequential** — one step at a time, each builds on
the previous. Use **parallel** mode when steps are independent and
you want speed:

*"Research these three competitors in parallel."*

In parallel mode, every step gets spawned as a sidekick at run
time. When sidekicks complete, the AI calls `step_done` for each
with the sidekick's result summary. Same plan card; just N steps
running at once.

## 8. Venue: main vs. sidekick

By default the plan runs in the room you triggered it from. Pass
`venue=sidekick` (or ask: *"Do this in a sidekick"*) to spawn a
sidekick room and run the plan there. Your main chat stays clean;
you can follow the plan in the sidekick window.

## Caps you'll bump into

| Cap | Default | Meaning |
|---|---|---|
| Max steps per plan | 20 | Force the AI to split if it's bigger. |
| Max attempts per step | 3 | After this, force-pause. |
| Max consecutive auto-steps | 8 | Force-pause for user check-in. |
| Plans per room | 1 active at a time | New plan needs the old to finish or be cancelled. |

## Where to go next

- [Spawn and monitor sidekicks](/docs/scaiwave/tutorials/power-user/spawn-and-monitor-sidekicks).
- [Concepts: Planner](/docs/scaiwave/concepts/planner) for the state machine.
- API: [Plans](/docs/scaiwave/reference/api/sidekicks-and-plans).