Supervisor Customization

This page covers the mechanics behind Supervisors: the session that runs, the prompt it receives, and the two free-text rules you can use to change its behaviour.

The supervisor session

Starting a supervisor runs, inside a tmux session named sq-supervisor-<supervisor-id> with ~/.sidequest as the working directory:

claude [--model <model>] [--chrome] --resume <supervisor-id> --dangerously-skip-permissions \
  --system-prompt "$(cat ~/.sidequest/skills/sidequest-supervisor.md)" '<prompt>' \
|| claude ... --session-id <supervisor-id> ... '<prompt>'

• --resume <supervisor-id> continues the supervisor’s own conversation. On the first run there is none, so the command falls through to --session-id <supervisor-id>, which creates it. The prompt is sent either way, so edited rules reach a resumed session.
• --model is the supervisor’s Model rule; Auto omits the flag.
• --chrome is added when Chrome Browser Tools is enabled in Settings.
• --dangerously-skip-permissions is always set: the supervisor must run sqlite3 and tmux commands without approval.

Stopping sends /exit to the session, waits half a second, then kills the tmux session.

How the prompt is built

graph TD
A[System prompt
~/.sidequest/skills/sidequest-supervisor.md] --> E[Session]
B[Capabilities line
auto_answer, pull_backlog, ceiling, close_quest] --> E
C[Close Quest Conditions] -->|if enabled and non-empty| E
D[Extended Instructions] -->|if enabled and non-empty| E

The first message sent to Claude is:

You are supervising the quest group '{name}' (supervisor_id: {id}).
Enabled capabilities: auto_answer: true, pull_backlog: true, ceiling: 3, close_quest: true.

## Close Quest Conditions

You are authorized to close (archive) quests when they meet the user's
completion criteria. The user defines "done" as:

{close quest prompt}

When a quest meets these conditions, archive it using the instructions in
your system prompt.

## Extended Instructions

{extended prompt}

Begin your supervision loop.

The two optional sections appear only when their switch is on and the text is non-empty. Because the prompt is assembled at start, these rules are locked while the supervisor runs — stop it, edit, start again. Reports to, Auto-start and the name can change at any time.

What the system prompt teaches

The bundled system prompt (about 300 lines) tells the supervisor:

• Its scope. It supervises one quest group, identified by supervisor_id, and must never touch quests outside it. Child supervisors’ quests may be counted but not read, answered or closed.
• Its tools. The sqlite3 CLI against Sidequest’s database for reading quests and updating needs_attention or status, and tmux capture-pane / tmux send-keys -l against sq-<quest-id> sessions for reading and answering.
• The auto-answer workflow. Read each active quest’s pane; when the agent is waiting, pick the recommended option, confirm routine actions, make small design decisions, then wait ~10 seconds and handle any follow-up prompt before moving on.
• Escalation rules. Leave needs_attention set and log the reason for destructive git operations, merges to the main branch, worktree deletion, anything involving secrets, external side effects, or notable cost.
• The main loop. Sleep 30 seconds between passes and print a status table (| Quest | Summary | Last Action |) each time.
• Close quest capability and extended instructions, which come from your rules.

The file is rewritten from the bundled copy on every launch, so edit the Extended prompt instead of the file.

Close quest conditions

With Close completed quests on, the supervisor archives quests that meet your criteria. Write the criteria the way you would tell a colleague when a task is done.

PR-based workflow:

When a pull request has been created for the quest's branch and all CI
checks have passed. The PR should have a description that summarizes
the changes.

Commit-based workflow:

When all requested changes have been committed to the branch and the
git status is clean (no uncommitted changes). The commit messages
should be descriptive.

Current Branch quests:

When the research question has been answered with a summary written
to a markdown file in the project's docs/ directory.

Archiving through the supervisor behaves like Complete Quest: the worktree stays for the retention window and the Chronicler writes a journal entry.

Extended prompt

The extended prompt is appended as an Extended Instructions section. Use it to add behaviour the built-in options do not cover, or to tune how the supervisor answers.

Code style enforcement:

When a quest has committed code, check that new TypeScript files include
explicit return types on exported functions. If not, send a follow-up
message to the quest session asking it to add them before considering
the quest complete.

Answering policy:

When an agent asks which of several approaches to take and one is marked
(Recommended), pick it. When none is recommended, prefer the smallest
change. Never approve a request to force-push.

Reporting:

After activating a backlog quest, log the quest title and description.
When a quest has been active for more than 30 minutes without new
commits, flag it as needing attention.

The notes file

A supervisor’s context is not durable: the session restarts, and a long run compacts. The system prompt therefore tells it to keep ~/.sidequest/supervisor-state/<supervisor-id>/notes.md, read it at the start of every loop and update it at the end:

• ## Handled — one line per thing it already acted on (- PR #553: reviewed, approved 2026-10-13). Everything here is treated as done, which is what makes “only look at new things” hold across a restart.
• ## Learnings — short facts about the group that changed how it acts (- the foreman's quests merge via /smash-merge; do not nudge them to open PRs).

It appends rather than rewrites, keeps the file under 100 lines by dropping handled entries whose quest is closed, and trusts the notes over its own memory when it sees the brief a second time. You can read the file to see what a supervisor thinks it has done, or edit it to correct it; delete it to start the supervisor with a blank memory.

Queue and ceiling

Pulling from the backlog is done by Sidequest, not by the agent. While the supervisor is running and Pull backlog to active is on, Sidequest checks every 30 seconds whether fewer than ceiling of its quests are active and, if so, promotes the top of Up next and launches its session in the background. The order is the position you set by dragging; quests that were never explicitly ordered (for example ones spawned by a recurring quest) come after the ordered ones.

The ceiling is enforced at the point of promotion. If you manually activate more quests, the supervisor does not demote them; it only stops promoting.

Model choice

A supervisor reads terminals and makes small judgement calls, so Sonnet is usually enough and keeps it cheap. Pick Opus for a supervisor whose close criteria require real judgement (reading a PR and its CI, say). The smart router never routes supervisors; Auto means your Claude Code default.

Reporting lines

With Reports to set, the parent supervisor’s prompt lists its children. Each loop it re-queries them, so changing the link applies live. The parent captures the child’s pane and answers prompts the child’s own session raises, counts the child’s quests in its status table, and reports a child that is down with work waiting — but it never reads or closes the child’s quests and never starts or stops the child.

Linux note

The bundled system prompt refers to the macOS database path (~/Library/Application Support/com.sidequest.app/sidequest.db). On Linux, add the correct path to the extended prompt so sqlite3 commands work:

The Sidequest database is at ~/.config/com.sidequest.app/sidequest.db.