Spooling
CLI Reference
Back to spooling.ai

spooling summarize

Write short summaries for your local sessions with a local or hosted model, or your Claude Code or opencode login.

spooling summarize [SESSION_ID...] [--backend BACKEND] [--model MODEL] [-n LIMIT] [--dry-run]

Generates a short summary for sessions that don't have one and stores it in the local database. Summaries appear in spooling session show, in spooling session list --summaries, and in the MCP get_session tool.

Summaries are local-only. spooling push does not send them to the cloud.

Some providers already write a summary (Claude Code does). Those are used as-is and never overwritten unless you pass --force. A summary that Spooling generated is refreshed on the next run once the session has grown.

Backends

BackendUse it forCredentials
openai (default)Any OpenAI-compatible endpoint: local Ollama, OpenAI, OpenRouter, vLLM, LiteLLMnone for local; SPOOLING_SUMMARY_API_KEY for hosted
anthropicThe Anthropic APIANTHROPIC_API_KEY
bedrockAWS Bedrock (Converse API)AWS_BEARER_TOKEN_BEDROCK (Bedrock API key) or any normal AWS credentials, plus AWS_REGION
claude-codeReuse your Claude Code login (runs claude -p), here or on another machine with --sshwhatever Claude Code is signed in with
opencodeReuse opencode's providers (runs opencode run), here or over --sshwhatever opencode is configured with

The default is a local Ollama daemon, so nothing leaves your machine. Transcripts are secret-redacted before they are sent anywhere. For any non-local backend, Spooling asks for confirmation first; pass --yes to skip the prompt.

Flags

FlagDescription
--backendopenai, anthropic, bedrock, claude-code or opencode. Env: SPOOLING_SUMMARY_BACKEND. Default: openai.
--modelModel name or id. Env: SPOOLING_SUMMARY_MODEL. Defaults: qwen2.5:7b (openai), claude-haiku-4-5 (anthropic). Required for bedrock.
--base-urlEndpoint for the openai backend. Env: SPOOLING_SUMMARY_BASE_URL. Default: http://localhost:11434/v1.
--regionAWS region for bedrock. Default: AWS_REGION.
--sshRun the claude-code or opencode backend on this SSH host, for example another Mac where Claude Code is signed in. Needs key-based SSH login.
--cli-cmdCommand to run if it isn't on PATH, such as ~/.local/bin/claude. With --ssh, the path on the remote machine.
-p, --projectOnly sessions in this project.
--providerOnly sessions from this provider id.
-d, --daysOnly sessions started in the last N days.
-n, --limitMax sessions to summarize. Default: 20.
--min-messagesSkip sessions shorter than this. Default: 4. Ignored when you name sessions.
--forceRegenerate even if a summary exists, including provider-written ones.
--dry-runList what would be summarized and call no model.
-y, --yesDon't ask before sending text to a non-local endpoint.

Bedrock model ids differ by region and account, so there is no default. Use an inference profile id such as us.anthropic.claude-haiku-4-5-20251001-v1:0.

Examples

# See what would run, without calling a model
spooling summarize --dry-run

# Local Ollama, newest 10 sessions from the last week
ollama pull qwen2.5:7b
spooling summarize -n 10 --days 7

# One session, replacing any existing summary
spooling summarize ses_e6310bd1 --force

# Hosted backends
spooling summarize --backend anthropic
spooling summarize --backend bedrock --region us-east-2 \
  --model us.anthropic.claude-haiku-4-5-20251001-v1:0

# Reuse a coding agent you are already signed in to
spooling summarize --backend claude-code
spooling summarize --backend claude-code --ssh my-other-mac
spooling summarize --backend opencode --model amazon-bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0
spooling summarize --base-url https://api.openai.com/v1 --model gpt-4o-mini

Then read them back:

spooling session list --summaries
spooling session show ses_e6310bd1

Summarize one session

Name the session by its id (or any unique prefix) and pick the backend:

spooling session list --title login            # find the id first
spooling summarize ses_e6310bd1 --backend claude-code
spooling summarize ses_e6310bd1 --backend claude-code --ssh my-other-mac
spooling session show ses_e6310bd1             # read it back
  • If the session already has a summary, nothing runs. Add --force to replace it, including a summary the provider wrote.
  • Naming a session skips the --min-messages filter, so short sessions work too. You can name several: spooling summarize ID1 ID2 --backend claude-code.
  • --dry-run shows what would run without calling a model, and -y skips the confirmation prompt.
  • To avoid typing the backend each time, export SPOOLING_SUMMARY_BACKEND=claude-code. There is no environment variable for --ssh.

Using Claude Code or opencode

These backends run the agent's headless mode and send the prompt on stdin, so there is no API key to set up. They use whatever login the agent already has. Both send the redacted transcript to that agent's provider, so Spooling asks for confirmation first.

  • Leave --model off to use the agent's default model. For opencode, pass provider/model explicitly if your configured default is an old model id.
  • With --ssh, the agent runs from /tmp on the remote machine so it doesn't pick up a project's rules. SSH runs non-interactively and often skips your shell profile, so if you see "not found", set --cli-cmd to the full path.
  • claude -p records each run as a session in that machine's Claude Code history. They start with a spooling-summary: prefix and spooling summarize skips them. The opencode backend deletes its run's session automatically.

The run stops early on errors that would repeat for every session, such as bad credentials, an unreachable server, or an unknown model.

On this page