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#

Where to go next#

• Spawn and monitor sidekicks.
• Concepts: Planner for the state machine.
• API: Plans.