---
allowed-tools: Read
description: Summarize and compress conversation history to reduce token usage
argument-hint: [optional: focus area or time range]
---

# Compact Session

Analyze the current conversation session and create a concise summary that preserves key context while reducing token usage. Useful for long conversations approaching context limits.

## Task

Review the conversation history, identify key decisions, code changes, and context, then create a structured summary that can be used as context for continuing the conversation.

## Process

### 1. **Analyze Conversation**

Review the current session to identify:
- **Key Decisions**: Important choices made during the conversation
- **Code Changes**: Files created, modified, or deleted
- **Context**: Background information that's essential to keep
- **Action Items**: Tasks completed or pending
- **Problems Solved**: Issues resolved and their solutions
- **Open Questions**: Unresolved items needing attention

### 2. **Extract Essential Information**

Focus on:
- **What Changed**: Concrete modifications to files or configurations
- **Why**: Reasoning behind decisions
- **How**: Key implementation details worth preserving
- **What's Next**: Logical next steps or pending work

Skip:
- Verbose explanations already captured in code
- Redundant back-and-forth dialogue
- Superseded approaches or failed attempts (unless they provide valuable context)
- Tool outputs that are no longer relevant

### 3. **Create Structured Summary**

Generate a compact summary using this format:

```markdown
# Session Summary - [Date/Time]

## Context
[Brief description of the overall task or goal]

## Key Decisions
- [Decision 1]: [Rationale]
- [Decision 2]: [Rationale]

## Changes Made

### Files Created
- `path/to/file.ext`: [Purpose]

### Files Modified
- `path/to/file.ext`: [What changed and why]

### Files Deleted
- `path/to/file.ext`: [Reason]

## Problems Solved
1. **[Problem]**: [Solution approach]
2. **[Problem]**: [Solution approach]

## Configuration Changes
- [Setting/Config]: [New value and reason]

## Important Context
[Essential background information needed for continuing]

## Open Items
- [ ] [Pending task or question]
- [ ] [Follow-up needed]

## Next Steps
1. [Suggested next action]
2. [Alternative direction]

## Technical Details Worth Keeping
- [API endpoints, algorithms, or specific implementation notes]
```

### 4. **Verify Coverage**

Ensure the summary includes:
- ✓ All file modifications with reasons
- ✓ Critical decisions and their context
- ✓ Errors encountered and solutions
- ✓ Current state of work
- ✓ Dependencies or prerequisites
- ✓ Next logical steps

### 5. **Output Format**

Present the summary in a copy-pasteable format that the user can:
- Use to start a fresh conversation with preserved context
- Archive in their vault for future reference
- Share with collaborators

## Arguments

**Optional user input:**
- Time range: "last hour", "since lunch", "today"
- Focus area: "only code changes", "decisions only", "full context"
- Specific topic: "authentication work", "bug fixes"

## Example Usage

```bash
# Compact entire session
/compact

# Focus on recent changes
/compact last 2 hours

# Only code changes
/compact code changes only

# Specific feature work
/compact authentication implementation
```

## Use Cases

**Approaching Token Limits:**
- Long debugging sessions
- Extended refactoring work
- Multi-day project conversations

**Archival:**
- Document work sessions for future reference
- Create project timeline entries
- Generate changelog content

**Handoffs:**
- Brief another developer
- Return to work after a break
- Share context with team members

**Context Management:**
- Reset conversation with preserved essentials
- Remove noise while keeping signal
- Prepare for new phase of work

## Smart Compression Techniques

**Merge Similar Items:**
- Combine related file changes into single entries
- Group similar decisions together
- Consolidate repeated troubleshooting steps

**Reference Not Repeat:**
- Point to files rather than including content
- Reference commit messages rather than repeating changes
- Link to documentation instead of explaining basics

**Prioritize Recency:**
- Recent decisions carry more weight
- Latest code state is most relevant
- Current blockers are most important

**Preserve Dependencies:**
- Keep chains of reasoning intact
- Maintain cause-and-effect relationships
- Note interdependencies between changes

## Quality Checks

Before finalizing:
- ✓ Could someone continue the work from this summary?
- ✓ Are all file paths accurate and complete?
- ✓ Is reasoning clear for non-obvious decisions?
- ✓ Are next steps actionable?
- ✓ Is the summary at least 80% shorter than full conversation?

## Integration Tips

**With Git:**
- Use summary as basis for commit messages
- Generate comprehensive PR descriptions
- Create release notes from multiple sessions

**With Obsidian:**
- Save summary as daily note entry
- Link to relevant project pages
- Archive in project documentation

**With Claude:**
- Start new conversation by pasting summary
- Use as project instructions in CLAUDE.md
- Reference when asking follow-up questions

## Tips

- **Run proactively**: Don't wait for context limits
- **Iterate**: Can run multiple times to refine compression
- **Customize**: Add focus areas based on your needs
- **Archive**: Keep summaries in project documentation
- **Review**: Quick scan ensures nothing important was lost

## Troubleshooting

**Summary too generic:**
- Provide more specific focus area
- Request technical details be preserved
- Specify which decisions are most important

**Missing important context:**
- Review summary against conversation
- Request specific additions
- Run again with better focus parameters

**Too verbose:**
- Ask for more aggressive compression
- Specify what to omit (e.g., "skip troubleshooting steps")
- Focus on outcomes rather than process

---

**Pro tip**: Run this command periodically during long sessions to maintain a living summary, making it easier to track progress and reset context when needed!