Sessions, Checkpoints, and Handoffs

Illustrative · sessions are disposable, the handoff is forever

A session is one conversation with your AI assistant. This article covers the habit that makes HQ feel reliable instead of forgetful: end sessions on purpose, and start fresh ones often.

Why fresh sessions beat one long session#

Every session has a limited working memory (a "context window"). As a conversation grows, that window fills with everything said and every file read. Two things then happen:

1. Quality degrades. A crowded memory means the assistant starts overlooking earlier decisions and making sloppier choices.
2. Eventually the session dies. Past the hard limit, the session simply can't continue ("Prompt is too long").

HQ's answer is not "try to keep sessions alive", it's the opposite. Sessions are disposable; the files HQ writes between sessions are what persist. A fresh session that reads a good handoff is sharper than an old session limping along, because it has all the conclusions and none of the clutter. (This is the heart of the HQ mental model.)

The arc: /startwork → work → /handoff#

1. Start with /startwork. At the top of a session, this command orients you: if a previous handoff exists, it offers to resume it (showing a one-line summary of where you left off); otherwise it asks what you want to work on, a company, a project, a repo, or a free-form task, and loads just the context that choice needs.

2. Work. Do the actual thing.

3. End with /handoff. This writes a "thread", a structured record with a summary of what happened, the next steps, the files touched, the git state, and any learnings, then commits everything so nothing is lost. It finishes by printing a thread ID and telling you exactly how to continue:

• In your next session, run /resumework {thread-id} to continue that exact piece of work, or
• Run /startwork and pick "Resume last session".

When you resume, HQ also lists next steps left open by your recent handoffs, so nothing falls through the cracks between sessions. Steps are marked done as you finish them.

That's the whole daily loop.

/checkpoint, the mid-session save#

/checkpoint is the lighter sibling of /handoff: a quick save of your progress (summary, files touched, next steps, git state) without ending the session. Think of it like hitting Save in a document.

Use it during long sessions, especially before starting anything risky or large, so that even if the session dies later, your progress up to the checkpoint is recorded. If the session feels long enough that you're checkpointing repeatedly, that's your cue to /handoff instead.

/recover-session, when a session dies without a handoff#

Sometimes a session hits the context limit and dies before you ran /handoff. Your work on disk is fine, you just lost the tidy summary. In a new session, run:

/recover-session

HQ scans the last 7 days for sessions that died at the context limit, shows you a list, and reconstructs a thread for the one you pick, what the session set out to do, which files it edited, and what it was doing when it died. From there you continue as if a handoff had been written. It never touches your git state, so nothing is committed without you.

Signs it's time to hand off#

• The session has been running for hours or has covered several unrelated tasks.
• Responses are getting slower, or the assistant repeats itself or forgets earlier decisions.
• You're about to switch task types (e.g., from coding to writing marketing copy).
• You've finished a milestone, a natural chapter break.
• You see any warning about context or compaction.

When in doubt, hand off. It costs a minute; a degraded session costs much more.

Where handoff files live#

Everything lands under workspace/threads/ inside your HQ folder:

• workspace/threads/T-{date}-{time}-{slug}.json, each thread (handoff, checkpoint, or recovered session).
• workspace/threads/handoff.json, a pointer to the most recent handoff; this is what /startwork peeks at.
• workspace/threads/recent.md, a human-readable table of your recent threads.
• Threads older than 60 days are archived into workspace/threads/archive/.

You never need to edit these by hand, the commands manage them, but it's useful to know they're plain files: searchable with /search, and synced between your machines when you use HQ Cloud.

Common questions#

If you get stuck#

If a session died and /recover-session doesn't find it, it may have been too recent or too small to detect, check workspace/threads/recent.md for the last saved state, or just describe to a fresh session what you were doing. For anything else, see the I'm stuck guide or file /hq-bug.