Session Refiner

Automatically create a compact bridge between long coding sessions to minimize token usage and costs while preserving essential context.

Quick Start

When your conversation is getting long:

You: "Use Session Refiner to create a summary"
Claude: [Generates compact markdown summary and automatically saves it]
You: [Start fresh chat, paste summary at top of conversation]

That's it. You've reset your context window while keeping continuity.

Automatic Saving: Summaries are automatically saved to .claude/session-summaries/ with timestamped filenames like 20251220-data-cleaning-plan.md for easy reference and organization.

What Gets Extracted

Active Tasks

[ ] Unchecked items from your todo list
TODOs and FIXMEs from code
Stated next steps and remaining work

Key Technical Decisions

Architectural choices made (JWT vs sessions, database selection, etc.)
Design patterns chosen and why
Rejected alternatives

Resolved Issues

Bugs that were fixed
Errors that were debugged
Problems that were solved

Code References

Essential snippets (not full files)
Recently-changed patterns
Important configurations
File paths for context

Key Findings

Important discoveries
Important notes and reminders
Non-obvious insights

Workflow

Option 1: Ask Claude (Easiest)

Say in your chat: "Use Session Refiner to create a summary"

Claude will:

Scan the current conversation for key information
Extract essential details only
Generate a markdown summary
Automatically save it to .claude/session-summaries/YYYYMMDD-brief-title.md
Display the file path

Then:

Start a new chat session
Paste the summary at the top (or reference the file path in .claude/session-summaries/)
Say: "Here's where I left off. Continue from here."
Resume work with fresh context window

Option 2: Run Script Locally (Most Control)

For maximum clarity, export your conversation and run the extraction script:

# Manually save conversation to a text file, then:
python .claude/skills/session-refiner/scripts/extract_session_summary.py \
  conversation.txt \
  --output my-summary.md \
  --max-tokens 5000

The script parses:

Explicit TODO: and FIXME: markers
Unchecked checkboxes: - [ ] task
Code blocks (triple backticks)
Decision statements: "Decided to...", "Using...", etc.
Bug resolutions: "Fixed:", "Resolved:"

Edit the output markdown if needed, then paste into a fresh chat.

When to Use

Milestones:

Completing a major feature → summarize, start fresh for next feature
After intense debugging → capture what was learned, move on
Switching between codebases/projects → snapshot state, fresh session

Token Warnings:

Claude mentions "conversation getting long"
You see context window warnings
You've had multiple back-and-forth debugging rounds

Cost Optimization:

Before a pause in work (stop for the day)
Before switching to a different developer/session
When you notice the conversation history exceeding 50k tokens

Token Budget

A complete summary uses 2,000–5,000 tokens, leaving you:

Session 1: 100k tokens used in long conversation
Summary: 3,500 tokens
Session 2: Start fresh with 3,500 tokens used, 196,500 tokens available

Without refining, Session 2 would start with 100k tokens already consumed.

Best Practices

Be explicit in chat: Use clear markers in conversation:
```
TODO: Fix login validation
FIXME: Error handling in API
- [ ] Add unit tests
```
These make extraction more accurate.
Review before reuse: Skim the generated summary before pasting. Edit if anything seems incomplete or unclear.
Keep originals: Store full conversations separately in case you need to reference them later.
Extract at good moments: Extract after finishing a module, feature, or debugging session—not randomly mid-task.
Add context notes: If something in the summary seems vague, add a clarifying note directly in the markdown before pasting.

Example Summary Output

# Session Summary
**Generated**: 2025-12-18 14:30:00

## Current Status

### Active Tasks
- [ ] Add authentication middleware
- [ ] Implement password reset flow
- [ ] Write integration tests for auth

## Key Technical Decisions
- **JWT tokens with refresh rotation** for stateless auth
- **PostgreSQL** for user persistence (transaction support)
- **bcryptjs** for password hashing (OWASP compliant)

## Resolved Issues
- Fixed CORS error by adding credentials flag to fetch
- Resolved password validation regex (Unicode support)

## Code References

### JavaScript
\`\`\`javascript
const hashPassword = async (pw) => {
  return bcrypt.hash(pw, 10);
};
\`\`\`

### SQL
\`\`\`sql
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR UNIQUE NOT NULL,
  password_hash VARCHAR NOT NULL
);
\`\`\`

## Key Findings
- Session tokens need 15-min expiry for security
- User table indexes on email for login performance

## Next Steps
1. Review the active tasks above
2. Paste this summary into a fresh chat session
3. Continue from where you left off

How Claude Uses This Skill

When you request a summary, Claude will:

Scan the conversation for patterns like:
- TODO:, FIXME:, [ ] checkboxes → Active Tasks
- Decision statements → Key Decisions
- "Fixed", "Resolved" → Resolved Issues
- Code blocks → Code References
- Key findings statements → Insights
Extract sparingly: Only essential information, not entire files or repetitive content.
Generate markdown: Clean, copy-paste-ready format.
Automatically save: Write summary to .claude/session-summaries/YYYYMMDD-brief-title.md
- Format: YYYYMMDD (ISO date) + - + brief title (kebab-case)
- Example: 20251220-data-cleaning-plan.md
- Automatically creates directory if needed
Hand to you: You can paste the summary content or reference the saved file.

Technical Details

See workflow.md for detailed step-by-step examples and advanced extraction techniques.

The extraction script (scripts/extract_session_summary.py) uses regex patterns to identify:

Explicit TODO/FIXME markers
Checkbox lists
Code blocks with language markers
Decision and resolution keywords
Key finding statements

You can manually run it for programmatic extraction when needed.