@papercraneai/summarize-chat

CLI tool that creates and maintains an evolving summary of learnings from your Claude Code conversations.

Features

• Discovers conversations from ~/.claude/history.jsonl
• Incrementally processes only new messages since last run
• Maintains a single evolving summary document (not per-session)
• Uses Claude (Haiku) to intelligently merge new learnings
• Keeps summary under a configurable size for context loading
• Tracks token usage and cost

Installation

npm install -g @papercraneai/summarize-chat

Prerequisites: Requires Claude Code to be installed and authenticated.

Usage

# Basic usage - summarize recent conversations
summarize-chat run --since 24

# Specify a custom summary file
summarize-chat run --sync-summary ~/my-learnings.md --since 24

# Check status
summarize-chat status

Options

summarize-chat run [options]

Options:
  --in-summary <path>    Read existing summary from this file
  --out-summary <path>   Write summary to this file
  --sync-summary <path>  Read and write to the same file
  --staleness <hours>    Hours before a session is considered stale (default: 2)
  --since <hours>        Only process sessions from the last X hours
  --max-size <kb>        Maximum summary size in KB (default: 50)
  --full                 Re-summarize all sessions (ignore state)

Default Paths

• Summary: ~/.claude/learning-summary/summary.md
• State: ~/.claude/learning-summary/state.json

How It Works

1. Discovery: Reads ~/.claude/history.jsonl to find conversation sessions
2. Filter: Skips sessions still active (within staleness window) and already processed
3. Parse: Extracts user/assistant messages from session JSONL files
4. Summarize: Sends existing summary + new messages to Claude with instructions to merge learnings while keeping under the size limit
5. Update: Saves the updated summary and records processed sessions in state

Output

--- Results ---
Sessions processed: 2
Total messages summarized: 121
Summary size: 10.5KB

--- Token Usage ---
Model: claude-haiku-4-20250514
Input tokens: 15,297 (3 uncached, 0 cache read, 15,294 cache write)
Output tokens: 2,912
Cost: $0.0337

License

MIT