spool

Spool is the publishing platform for agent Sessions. Share sends the selected records to the Hub and creates a Link-only URL that other people can read; Public visibility is always a separate author choice. Claude Code and Codex CLI shares can also be resumed from another machine. A Share can carry a Markdown Summary: the interactive CLI can generate one with a detected Claude Code or Codex CLI, while an agent shell should provide its own Summary with --summary. Local preparation and sharing cover Claude Code, Codex CLI, Gemini CLI, OpenCode, and Pi, so any agent with a shell can recall another agent's Sessions.

Routing

Decide from $ARGS and the conversation:

• share/publish this (or a specific) session → Share flow
• withdraw/unpublish a shared session → spool withdraw <sid-or-url>
• a resumable Claude/Codex spool session URL or sid the user wants to continue → spool resume <sid-or-url> (materializes it locally and forks the provider's native session)
• anything else (a topic, a question, "that session where…") → Recall flow

Preflight

which spool

If missing, tell the user: install with npm install -g @spool-lab/cli, then spool sync to index sessions. Stop here.

Share flow

claude, codex, gemini, opencode, and pi sessions can be shared. Sharing sends native Claude/Codex records or the other sources' provider-neutral indexed conversation to the Hub and prints a Link-only URL.

1. Run spool sync so the session and its newest turns are indexed.
2. Pick the target:
   • Inside Claude Code, use $CLAUDE_CODE_SESSION_ID.
   • In another agent (or if that variable is unset), omit the session argument to select the latest indexed session whose cwd exactly matches the current directory.
   • For any other session, pass a UUID or unique UUID prefix from spool list. <uuid>@<n> shares only the first n records.

3. Write a share-ready Markdown Summary from the shared portion of the conversation. It should read like a concise, polished GitHub README for this one session—not a turn-by-turn chat recap.

   Determine the language from the session's natural-language conversation, giving substantive user messages more weight than assistant replies. Ignore code, logs, commands, paths, identifiers, metadata, and pasted material when deciding. For a mixed-language session, use the dominant language of the user's discussion; if none is clear, use the first substantive user request. Use that language for all prose and headings while preserving technical names in their original form.

   Use this README-style structure, localizing every heading:

   • # <specific title> derived from the actual goal, followed by a 1–2 sentence overview.
   • ## Goal — the original request, constraints, and meaningful scope changes.
   • ## What happened — the important stages in chronological order, grouped into concise paragraphs or bullets; include relevant pivots, failures, implementation details, and validation.
   • ## Key decisions and findings only when material decisions or discoveries shaped the work.
   • ## Validation only when the session contains concrete checks, tests, builds, or measurements.
   • ## Outcome — state whether the goal was achieved, partially achieved, changed, or remains unresolved, and explain why.
   • ## Next steps only when the session supports specific remaining work.

   Omit optional sections without meaningful content. Use direct, neutral language, preserve useful technical details, distinguish completed work from proposals and unresolved items, do not expose secrets, and never invent outcomes.

4. Pass that Summary directly. Agent tool shells are non-interactive, so do not rely on the CLI's post-upload Agent prompt:

summary="$(cat <<'SPOOL_SUMMARY'
<share-ready Markdown Summary>
SPOOL_SUMMARY
)"

# Inside Claude Code:
spool share "$CLAUDE_CODE_SESSION_ID" --summary "$summary" < /dev/null

Outside Claude Code, omit the target: spool share --summary "$summary" < /dev/null. For a selected session, put its UUID before --summary. Add --spool-file <path> only when the user wants to attach a .spool document.

The < /dev/null is deliberate: if the secret gate needs confirmation, a non-interactive invocation must abort instead of hanging. Do not add --yes until the user explicitly accepts the reported risk.

5. Handle outcomes:
   • Session shared as Link-only — the records and provided Summary are live; give the user the URL. For Claude/Codex shares, teammates can run spool resume <sid-or-url> to fork it locally.
   • Not logged in — ask the user to run spool login (browser approval), then retry.
   • Secret findings / Cannot confirm ... without a TTY — show the findings summary and ask. Only after an explicit yes, re-run the same command with --yes.
   • <source> sessions can be shared and read, but native Resume is not supported yet — explain that the share is readable, while native Resume currently requires Claude or Codex.
   • The session is already shared at <url>. Its previous Summary is unchanged. — preserve and report the live URL, and explain that only the Summary generation/upload failed.

Recall flow

The goal is cited recall: your reply answers the question and names the session each claim came from.

1. Search

spool search "<query>" --json -n 5

• -s claude|codex|gemini|opencode|pi filters by agent, --since 7d by time.
• When the user names a project, scope to it instead: spool projects <name> lists its sessions (exact name > repo slug > substring).
• Zero hits → run spool sync once (indexing is manual; the newest sessions are often missing) and retry with broader terms.

Done when you hold at least one relevant UUID — or you have synced, retried, and can report there is no match.

2. Zoom

Pick the cheapest view that answers the question; the full transcript is the most expensive and rarely the right first move:

For local Gemini, OpenCode, and Pi sessions, use the full transcript: record-level --log, --diff, and @r<n> views currently require Claude or Codex raw records. Local UUID prefixes are accepted when unique.

3. Use it

Fold what you found into your reply as ordinary context, citing the source per claim — [codex · 7/15 · parallel-world]. When the user wants to continue a local session rather than read it, use the native command shown by human-formatted search output: claude -r <uuid>, codex resume <uuid>, or pi --session <uuid>. JSON search output does not add that command, and the CLI currently prints no resume hint for Gemini or OpenCode.

Command reference