/gaia handoff and /gaia pickup

Command	What it does
/gaia handoff	Writes a self-contained handoff document so you can clear context.
/gaia pickup	Reads the most recent handoff and reconstitutes context.

When to use them

Run /gaia handoff when your context starts getting “heavy”. A good rule of thumb is:

• Opus 1M - 20-25%
• Sonnet/Haiku - 40-60%

Then /clear (or exit Claude and restart).

Then call /gaia pickup in the fresh session to continue.

/gaia handoff

/gaia handoff [optional inline notes]

Pulls from three sources:

• The conversation transcript (accomplishments, decisions, gaps, open questions).
• Git state (git rev-parse --abbrev-ref HEAD, git log -1 --oneline, git status --short).
• You can optionally include notes inline after handoff to help “focus” on specific parts or the next step(s).

The handoff document is written to:

.gaia/local/handoff/HANDOFF-{YYYY-MM-DD}-{slug}.md

The slug is derived from the session’s main thread (e.g. auth-refactor, route-cleanup).

What the document contains

Sections present only when there is real content. Empty sections are dropped, not stubbed.

• Accomplishments: what shipped, with commit hashes when committed.
• Decisions: table of decision, rationale, impact.
• Gaps and open questions: each gap names a status (FIXED / PARTIAL / UNKNOWN / DEFERRED / INTENTIONAL), notes, a concrete next check, and a reference (@path/to/file:line).
• Environment state: branch, background processes, devices or simulators, test fixtures.
• Reference files: @path cross-references so the next session can jump straight in.
• Next actions: table of concrete, testable steps with rough effort estimates.

/gaia pickup

/gaia pickup

No arguments. Pickup runs through four steps:

1. Locate. Find the most recent handoff: ls -t .gaia/local/handoff/HANDOFF-*.md | head -1. If no handoff exists, fall back to wiki/hot.md and report No handoff found — resuming from hot cache.
2. Read. Load the handoff in full. Run git rev-parse --abbrev-ref HEAD, git status --short, and git log -1 --oneline in parallel.
3. Report. Surface a tight status block: current branch (with drift from the handoff if any), handoff filename and date, one-line context, 1 to 3 bullets on what’s done or in-flight, 1 to 3 bullets on gaps, and a suggested next action.
4. Archive. After you confirm a direction (pick an action, start editing, or say “go”), the consumed handoff moves to .gaia/local/handoff/archive/.

Note

The handoff archive only happens after you act on it. Premature archive would lose context if the pickup itself hits a context break.

Drift detection

If the handoff says branch feat/auth at commit abc1234, and current state is main at def5678 with a dirty tree, pickup flags the divergence before suggesting next actions. The handoff may be stale; pickup says so explicitly rather than reconstructing context against a different reality.

Example flow

End of session:

> /gaia handoff coach voice prompts still need fixture audit

Fresh session:

> /gaia pickup

Pickup reports:

Branch: feat/coach-voice (clean, matches handoff)
Last handoff: HANDOFF-2026-05-08-coach-voice.md (2026-05-08)
Context: Wired coach voice prompts to /api/coach; fixtures pending.

State:
- Coach prompt template extracted to lib/prompts/coach.ts
- Endpoint contract aligned with spec

Open:
- Fixtures audit: voice cues for happy/sad/neutral are stubs
- Test for empty transcript edge case

Suggested next: Audit fixture coverage at @lib/prompts/coach.fixtures.ts:1

Storage

Handoffs are project-local: .gaia/local/ is gitignored. They never enter version control, so private notes, dirty-tree details, and device IDs stay on the machine that wrote them. Archived handoffs are not pruned automatically. You should clean .gaia/local/handoff/archive/ when it grows.