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
| Backend | Use it for | Credentials |
|---|---|---|
openai (default) | Any OpenAI-compatible endpoint: local Ollama, OpenAI, OpenRouter, vLLM, LiteLLM | none for local; SPOOLING_SUMMARY_API_KEY for hosted |
anthropic | The Anthropic API | ANTHROPIC_API_KEY |
bedrock | AWS Bedrock (Converse API) | AWS_BEARER_TOKEN_BEDROCK (Bedrock API key) or any normal AWS credentials, plus AWS_REGION |
claude-code | Reuse your Claude Code login (runs claude -p), here or on another machine with --ssh | whatever Claude Code is signed in with |
opencode | Reuse opencode's providers (runs opencode run), here or over --ssh | whatever 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
| Flag | Description |
|---|---|
--backend | openai, anthropic, bedrock, claude-code or opencode. Env: SPOOLING_SUMMARY_BACKEND. Default: openai. |
--model | Model name or id. Env: SPOOLING_SUMMARY_MODEL. Defaults: qwen2.5:7b (openai), claude-haiku-4-5 (anthropic). Required for bedrock. |
--base-url | Endpoint for the openai backend. Env: SPOOLING_SUMMARY_BASE_URL. Default: http://localhost:11434/v1. |
--region | AWS region for bedrock. Default: AWS_REGION. |
--ssh | Run 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-cmd | Command to run if it isn't on PATH, such as ~/.local/bin/claude. With --ssh, the path on the remote machine. |
-p, --project | Only sessions in this project. |
--provider | Only sessions from this provider id. |
-d, --days | Only sessions started in the last N days. |
-n, --limit | Max sessions to summarize. Default: 20. |
--min-messages | Skip sessions shorter than this. Default: 4. Ignored when you name sessions. |
--force | Regenerate even if a summary exists, including provider-written ones. |
--dry-run | List what would be summarized and call no model. |
-y, --yes | Don'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-miniThen read them back:
spooling session list --summaries
spooling session show ses_e6310bd1Summarize 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
--forceto replace it, including a summary the provider wrote. - Naming a session skips the
--min-messagesfilter, so short sessions work too. You can name several:spooling summarize ID1 ID2 --backend claude-code. --dry-runshows what would run without calling a model, and-yskips 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
--modeloff to use the agent's default model. For opencode, passprovider/modelexplicitly if your configured default is an old model id. - With
--ssh, the agent runs from/tmpon 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-cmdto the full path. claude -precords each run as a session in that machine's Claude Code history. They start with aspooling-summary:prefix andspooling summarizeskips 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.