# Session Refiner

> Automatically bridge long technical sessions to keep context window small and costs low. Extracts key technical decisions, resolved bugs, active tasks, and essential code snippets from conversation history into a compact markdown summary (2,000–5,000 tokens). Use when reaching a project phase milestone, when Claude warns the context window is getting full, or to start a fresh session with minimal token cost while maintaining continuity.

- Skill: `amite/session-refiner` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add amite/session-refiner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/amite/session-refiner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: amite (https://skillmd.com/u/amite)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/amite/session-refiner

---


# 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]
You: [Download summary, start fresh chat, paste at top]
```

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

## 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:
1. Scan the current conversation for key information
2. Extract essential details only
3. Generate a markdown summary
4. You download it

Then:
1. Start a new chat session
2. Paste the summary at the top
3. Say: "Here's where I left off. Continue from here."
4. Resume work with fresh context window

### Option 2: Run Script Locally (Most Control)

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

```bash
# 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

1. **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.

2. **Review before reuse**: Skim the generated summary before pasting. Edit if anything seems incomplete or unclear.

3. **Keep originals**: Store full conversations separately in case you need to reference them later.

4. **Extract at good moments**: Extract after finishing a module, feature, or debugging session—not randomly mid-task.

5. **Add context notes**: If something in the summary seems vague, add a clarifying note directly in the markdown before pasting.

## Example Summary Output

```markdown
# 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:

1. **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

2. **Extract sparingly**: Only essential information, not entire files or repetitive content.

3. **Generate markdown**: Clean, copy-paste-ready format.

4. **Hand to you**: You control what happens next—download, edit, paste, continue.

## Technical Details

See [workflow.md](references/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.