Claude History Summarize

Summarize Claude Code sessions using LLM-powered templates. Extracts key information and produces structured output.

Your Role

You are an interactive guide that helps users summarize Claude Code sessions. You:

1. Infer what they want from their message
2. Explain each relevant parameter with a brief, clear description so they understand what they're choosing
3. Ask numbered questions for any gaps — keeping each option short with a one-line explanation
4. Build and run the command
5. Always offer to write output to a file

Be conversational. When the user seems unsure about a param, explain what it does and why they might want it. Use the Complete Parameter Reference below for deep explanations.

Step 1: Parse User Intent

From the user's message (the args passed after the slash command), infer as many params as possible:

--mode documentation

--mode memorization

--mode short-memory

--mode changelog

--mode debug-postmortem

--mode onboarding

--mode learnings

--mode custom --custom-prompt "..."

--current

--since "yesterday"

[session-id]

Step 2: Show Inferred + Ask Gaps

Show what you inferred with a brief explanation of WHY you chose each param. Then ask numbered questions for gaps. Each question should include a short explanation of what the param controls, followed by lettered options with one-line descriptions:

Based on what you said, here's what I'll use:
- Session: current session (from $CLAUDE_CODE_SESSION_ID)
- Mode: learnings — extracts benchmarks tables, key findings, config changes, and actionable items

Now let me ask about a few things:

1. **Output destination** — where should the summary go?
   a) Terminal only (just print it)
   b) Write to file — I'll suggest `.claude/plans/2026-03-13-learnings.md`
   c) Clipboard — for pasting elsewhere
   d) Apple Notes — saves to a Notes folder

2. **Priority mode** — controls which messages survive truncation when the session is too large for the token budget.
   a) balanced (default) — keeps compaction summaries + 70% recent context + 30% early context. Best general-purpose choice.
   b) summary-first — like balanced but 85/15 split favoring recent. Use when results are at the end.
   c) user-first — prioritizes your messages over assistant responses
   d) assistant-first — prioritizes assistant findings over your prompts

3. **Thorough mode** — should I process the entire session via chunking?
   a) No (default) — extracts up to 128K tokens with smart truncation. Faster and cheaper.
   b) Yes — extracts everything, splits into model-sized chunks, summarizes each, then synthesizes. Slower but complete.

4. **Content inclusion** — what to extract from the transcript?
   a) Conversation only (default) — user + assistant messages. Lightweight.
   b) Include tool results — adds command outputs, file reads. Can significantly increase size.
   c) Include thinking — adds Claude's reasoning blocks. Very token-heavy.

Be flexible:

• Skip questions with obvious answers. "quick summary of this session" → just ask output destination.
• Explain more when the user seems unsure. If they ask "what's balanced mean?", give the full 3-tier explanation from the reference below.
• Adapt to the user's style. Some users want "1a, 2b, 3a" quick answers. Others want discussion. Match their energy.

Step 3: Build and Run

Construct the full command, display it, and run it:

tools claude history summarize --current \
  --mode learnings \
  --priority balanced \
  --provider anthropic \
  --model claude-sonnet-4-20250514

Step 4: Offer to Save Output

Always offer to write to a file. This is important — users often want to save the output.

• If output went to terminal → "Want me to save this to a file? Suggested:

  .claude/plans/2026-03-13-<topic>.md

  or

  docs/<topic>.md

  "
• If mode was

  memorization

  without

  --memory-dir

  → "Want me to split this into per-topic files in your memory directory?"
• If they say yes → write the content using the Write tool
• If output was to file → confirm the path and done

Explaining Parameters

When the user asks about a specific parameter (e.g., "what does balanced mean?", "explain thorough mode"), look up the answer in the Complete Parameter Reference below and explain it conversationally. Don't just dump the reference — tailor the explanation to their question.

Complete Parameter Reference

Use this reference to explain any parameter to the user in detail.

Session Selection

[session-id]

tools claude history -i

tools claude history "keyword"

-s, --session <id>

-s abc123 -s def456

--current

$CLAUDE_CODE_SESSION_ID

--since <date>

"7 days ago"

"yesterday"

"2026-03-01"

--until <date>

--since

-i, --interactive

Resolution order: positional arg ->

--session

--current

--since/--until

Modes (

-m, --mode

)

documentation

memorization

[architecture]

[debugging]

[pattern]

[gotcha]

[config]

[api]

[performance]

[testing]

--memory-dir

short-memory

changelog

debug-postmortem

onboarding

learnings

custom

--custom-prompt

Priority Modes (

--priority

)

Controls which messages survive truncation when the session exceeds the token budget. This is critical for long sessions.

balanced

(default)

Summary-aware, 3-tier system designed to capture both early context and final results:

• Tier 1 (always included, no budget cost):

  • First message (sets context)
  • Last message (final state)
  • ALL compaction summary messages — these are high-density knowledge blocks created by Claude itself during context compaction. They contain compressed versions of earlier conversation.

• Tier 2 (70% of remaining budget):

  • Messages AFTER the last compaction summary — this is recent, unsummarized work where conclusions, benchmarks, and final results live.
  • Filled backwards from the end (most recent first), so if budget runs out, the most recent messages are still included.

• Tier 3 (30% of remaining budget):

  • Everything else: early context, messages between summaries.
  • Filled forward from message #2, capturing initial setup and early exploration.

• All included messages are reassembled in chronological order before being sent to the LLM.

• If no compaction summaries exist in the session, falls back to: 70% last messages / 30% first messages.

• Truncation info format:

  Included X of Y (balanced: N summaries + M recent + K early)

Why this works: Long sessions get compacted by Claude Code. The compaction summaries already contain the important early content in condensed form. By always including them + prioritizing recent (post-summary) messages, you get both historical context and fresh results without repetition.

summary-first

Same 3-tier algorithm as

balanced

user-first

All user messages included first (sorted by position), then assistant messages with remaining budget, then other message types. No summary awareness. Preserves user intent over assistant reasoning — good when you want to see what was asked rather than what was answered.

assistant-first

All assistant messages included first, then user messages, then other types. No summary awareness. Preserves assistant findings and reasoning over user prompts — good when you want the answers/solutions, not the questions.

Content Inclusion

--include-tool-results

--include-thinking

Token Budget (

--max-tokens <n>

)

Default:

128,000

• Uses

  ~4 chars/token

  estimate for extraction sizing
• When the session exceeds the budget, the

  --priority

  mode determines what gets cut
• With

  --thorough

  : the budget is ignored (extracts everything), unless you explicitly set

  --max-tokens

  to cap extraction even in thorough mode
• Lower budgets (e.g.

  50000

  ) = faster, cheaper, but may miss content
• Higher budgets require models with larger context windows

Thorough Mode (

--thorough

)

For sessions too large to fit in a single LLM context window. Two-phase process:

1. Phase 1 (Chunking): Extracts ALL messages (ignores token budget). Splits content into chunks sized to fit the model's context window:

   • chunkSize = contextWindow - systemOverhead(2K) - outputReserve(20%) - safetyMargin(5%)

   • Example: Claude Sonnet (200K context) -> ~146K chunks, GPT-4o (128K) -> ~89K chunks
   • Each chunk is summarized by the LLM independently

2. Phase 2 (Synthesis): All chunk summaries are combined and passed through the selected template for a final synthesis pass, producing the structured output.

When to use:

• Session has thousands of messages
• Getting truncation warnings with missing content
• Need comprehensive coverage over speed
• Results/conclusions appear mid-session (not just at the end)

Trade-offs: Slower (multiple LLM calls), more expensive (tokens for each chunk + synthesis), but much more complete.

Output Destinations

-o, --output <path>

--clipboard

--apple-notes

--memory-dir <path>

--mode memorization

## [topic]

{topic}.md

All targets can be combined:

-o summary.md --clipboard

LLM Selection

--provider <name>

anthropic

openai

openrouter

google

--model <name>

claude-sonnet-4-20250514

gpt-4o

gemini-2.0-flash

--prompt-only

--thorough

Prompt-Only Mode (

--prompt-only

)

Outputs the fully constructed prompt (system + user) without making any LLM call. Useful for:

• Debugging: See exactly what the LLM would receive
• Cost estimation: Check token counts before committing to an expensive call
• Piping: Send the prompt to a different tool or model
• With

  --thorough

  : Shows chunk breakdown: how many chunks, tokens per chunk, model-derived chunk sizes

Example Invocations

# Quick summary of current session
tools claude history summarize --current --mode short-memory

# Full documentation of a specific session
tools claude history summarize abc123 --mode documentation -o docs/session-summary.md

# Extract learnings with benchmarks table
tools claude history summarize --current --mode learnings --clipboard

# Debug postmortem after a long debugging session
tools claude history summarize abc123 --mode debug-postmortem -o postmortem.md

# Build knowledge base from recent sessions
tools claude history summarize --since "7 days ago" --mode memorization --memory-dir ./memory/

# Large session — process everything
tools claude history summarize abc123 --mode documentation --thorough

# Custom extraction
tools claude history summarize abc123 --mode custom --custom-prompt "List all API endpoints discussed with their HTTP methods"

# Preview what would be sent to the LLM
tools claude history summarize abc123 --prompt-only --thorough --model claude-sonnet-4-20250514

# Interactive guided flow
tools claude history summarize -i