Handoffs

A handoff extracts the conversation history from one quest, summarizes it into a structured document, and delivers that summary to another quest — even across different projects and workspaces. It solves the continuity problem: when a quest finishes (or hits a dead end), its context doesn’t have to die with it.

How it works

graph LR
A[Source Quest] -->|Read conversation log| B[Last 200k characters]
B -->|Summarize via Claude| C[Handoff Summary .md]
C -->|typed into the session
or stored on the quest| D[Target Quest]

1. Sidequest reads the source quest’s Claude Code conversation. Long conversations are trimmed from the start, keeping the most recent 200,000 characters, with a marker noting how many earlier messages were dropped — so the summary reflects where things stand now, not how they began.
2. It sends the conversation to Claude with a prompt that produces a structured summary. The model comes from the handoff entry in the router rules (Sonnet by default).
3. The summary is saved as a markdown file in ~/.sidequest/handoffs/.
4. If the target quest has a live session, Sidequest types a note into that session’s terminal pointing at the summary file (followed by the new quest’s prompt, for new quests), so the agent reads it immediately.
5. If the target quest isn’t running yet, the summary reference is prepended to the quest’s description so it is included when the session is first launched.

What gets transferred

The handoff summary follows a fixed structure:

• Abstract — 2-3 sentences on what the quest was about and where it stands.
• Initial Goals — What the quest originally set out to accomplish.
• Steps Taken — Chronological walkthrough of key actions, decisions, and code changes with file paths and function names.
• Findings & Insights — Solutions found, patterns identified, gotchas encountered.
• Where things stand right now — What was being worked on at the end, specific next steps with file paths and error messages, unresolved questions.
• Key Context — Environment setup, constraints, relevant paths, API endpoints, configuration values — anything painful to rediscover.

If the source quest was mid-task, the handoff captures exact file paths, line numbers, error messages, and pending decisions so the receiving quest can pick up without re-reading the original conversation.

Creating a handoff

1. Right-click a quest in the quest log and select Handoff Quest. The Courier’s dialog opens.
2. Choose the target:
   • Existing Quest — search and select any active or backlog quest across all projects and workspaces.
   • New Quest — pick a project and whether the new quest starts as Active or Backlog, then click Configure Quest…. The full Create Quest dialog opens, titled New Quest for Handoff, so you can set the type, base branch, prompt, GitHub issues, context projects, attachments, token budget, agent, account, supervisor, model and effort. Issues linked to the source quest start selected when the target is in the same project.
3. Optionally check Complete this quest after handoff to archive the source quest once the handoff is delivered.
4. Click Send Handoff.

The Courier reports its progress (“Reading through the quest log”, “Summarizing key moments”…) while Claude generates the summary. Once complete you’ll see The handoff scroll has been delivered! and the dialog closes.

Adding a prompt

When handing off to a new quest, the prompt you write becomes the new quest’s initial instruction. The handoff summary is delivered as context, so the agent in the new quest sees both the prior work and your new direction.

When to use handoffs

Continuing interrupted work. A quest hit its context limit or you need to restart a session. Hand off to a new quest so the next session starts with full context instead of from scratch.

Splitting work. A quest discovered that the task is bigger than expected. Hand off the remaining work to a new quest while keeping the original quest’s findings intact.

Switching agents or models. Hand off to a new quest on a different agent, account or model — the configure step lets you pick all of them.

Cross-project knowledge sharing. One quest learned something (API behavior, a workaround, an architectural constraint) that a quest in a different project or workspace needs. Handoffs are not limited to quests within the same project.

Shift handoffs. You’re done for the day and want to leave a clean summary of where things stand. Create a handoff to a backlog quest that you or a teammate can pick up later.

For durable, searchable notes rather than a one-off transfer, see Journals.

Handoff file management

Handoff summaries are stored as markdown files in ~/.sidequest/handoffs/. Filenames are slugified from the summary title (e.g., api-auth-migration-handoff.md). If a file with the same name already exists, a numeric suffix is appended.

Each file includes frontmatter with the date and source quest title:

---
date: 2026-07-15
source_quest: Fix authentication flow
---

# API Auth Migration Handoff

## Abstract
...

Old handoff files are pruned automatically based on Handoff Retention in Settings > Storage (7, 30 or 90 days, or never; default 30 days). Cleanup runs on startup and periodically while the app is open.