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, not a sidekick.

Where to go next#

• Planner — sequential plans with human supervisor controls.
• Tutorial: Spawn and monitor sidekicks.
• API: Sidekicks.