---
audience: everyone
summary: Delegated AIs that run a single task in the background and report back when
  done.
title: Sidekicks
path: concepts/sidekicks
status: published
---

# Sidekicks

A **sidekick** is an AI assistant spawned into a dedicated room to work
on a single task in parallel with the main conversation. The motivating
case: you ask an AI in your chat to do something that would take three
minutes of back-and-forth tool calls; instead of stalling the chat with
*"this might take a while"*, the AI spawns a sidekick and keeps the
conversation flowing.

## The shape of a sidekick

When a sidekick is spawned, three things happen:

1. A new **sidekick room** is created in the same workspace. It has
   one human member (the spawner), one AI member (the sidekick), and
   `room_type=sidekick`.
2. An `AgentTask` row records the task: spawner id, task description,
   step counter, status, time / token budgets.
3. The parent room gets a `swp.sidekick.spawned` event with the
   sidekick's **codename** (a friendly name like `brave-penguin`).

The sidekick then chews through its task autonomously: thinking,
calling tools, possibly spawning sub-sidekicks. When done, it calls
the `sidekick_complete` tool, which:

- Updates `AgentTask.status = completed` and records a `result_summary`.
- Posts a `swp.sidekick.result` event back to the parent room with
  the summary.
- Closes the sidekick room (read-only, kept for audit).

## Caps

To keep a stuck sidekick from running forever, three caps apply:

- **Max steps** per sidekick (default 25). After this many turns the
  sidekick is force-completed with whatever it has.
- **Token budget** for the whole task (configurable per-tenant; the
  AI gets a warning when it's burning through it).
- **Wall-clock timeout** (default 5 minutes). Enforced by an ARQ
  scheduled job that terminates the sidekick if it goes over.

There's also a per-user concurrency cap (default 3 simultaneous
sidekicks). Hitting it returns a clear error from the spawn tool.

## Spawning

Two ways:

- **From chat**, by the user: type `/sidekick <task description>`.
  The currently-engaged AI handles the spawn.
- **From the AI**, by tool call: the AI judges the request will be
  long and calls `spawn_sidekick(task, context_mode)`.

The `context_mode` parameter chooses what the sidekick sees:

- `task_only` (default, cheap) — the sidekick sees only its task
  description. No conversation history.
- `full` — the sidekick gets the parent room's recent history. Use
  when the task references "this", "the user", "the message above",
  etc.

## Codenames

Sidekicks have human-readable two-word codenames (`brave-penguin`,
`gentle-wren`) generated by a deterministic word-pair function. Each
codename is unique per parent room over the room's lifetime.

Use codenames in slash commands:

- `/sidekick:status brave-penguin` — what's it doing now.
- `/sidekick:cancel brave-penguin` — stop it.
- `/sidekick:result brave-penguin` — re-show its final summary.

## Monitoring

The right-side **Sidekicks** panel shows every sidekick in the room
with its codename, status (`spawning`, `running`, `completed`,
`failed`, `terminated`), step counter, and an open-the-room button.
Click into a sidekick room to watch it think live; navigate back with
the **← Parent room** link in the sidekick room's header.

## Cancelling

Anyone with `power_level >= 50` in the parent room (or the spawner)
can cancel via `/sidekick:cancel <codename>`, the panel button, or
`POST /v1/rooms/{room_id}/sidekicks/{task_id}/cancel`. The sidekick's
in-flight ScaiGrid stream is interrupted; the task is marked
`terminated`; the parent room gets a `swp.sidekick.cancel` event.

## When *not* to use a sidekick

- The task is < 30 seconds of work. Just ask in the main room.
- You'd lose context. Sidekicks are async — the user has moved on by
  the time it finishes.
- The task requires the user's input partway through. Sidekicks don't
  have a turn-by-turn conversation with the user; they're "fire and
  return a result".

If you want a structured multi-step process *with* user oversight,
that's a [plan](/docs/scaiwave/concepts/planner), not a sidekick.

## Where to go next

- [Planner](/docs/scaiwave/concepts/planner) — sequential plans with
  human supervisor controls.
- Tutorial: [Spawn and monitor sidekicks](/docs/scaiwave/tutorials/power-user/spawn-and-monitor-sidekicks).
- API: [Sidekicks](/docs/scaiwave/reference/api/sidekicks-and-plans).