Save current chat session state and prepare instructions for next session.
Saves your chat session state and creates instructions for the next session. Use this before hitting token limits or ending a work session to preserve context and define next steps.
/plugin marketplace add unclecode/claude-code-tools/plugin install unclecode-cc-toolkit@unclecode-toolsSave current chat session state and prepare instructions for next session.
$ARGUMENTS
Optional query to add extra guidance for the next session. This query will be incorporated into the "What To Do Next" section of NEXT.md.
Examples:
/pp-checkpoint focus on fixing the auth bug first/pp-checkpoint user will provide new API docs tomorrow/pp-checkpoint skip T260, move directly to T262Called at the end of a chat session (or before hitting token limits) to:
# Get current working directory
pwd
# Convert to Claude projects path
# Example: /Users/unclecode/devs/project
# Becomes: ~/.claude/projects/-Users-unclecode-devs-project/
# Find most recent .jsonl file (exclude agent-* files)
ls -lt ~/.claude/projects/-Users-unclecode-devs-{converted-path}/*.jsonl | grep -v "agent-" | head -1
# Extract UUID from filename
# Example: 530170ff-52f5-4ad6-a333-22a09bd64773.jsonl
# UUID: 530170ff-52f5-4ad6-a333-22a09bd64773
Read .context/project/INDEX.md to identify active subproject.
ALWAYS ask the user:
Before saving checkpoint, do you want me to create a compressed dump of this chat session?
This will use AI to compress the full conversation into a readable summary (~5-10% of original size) that captures all important details, decisions, and code changes.
Options:
1. **Yes** - Create compressed dump (takes ~30-60 seconds)
2. **No** - Skip dump, just save checkpoint files
Note: The raw .jsonl transcript is always available for grep/search regardless.
If user says Yes:
/compress-chat command on the current session.context/project/{active}/history/{uuid}-{YYYY-MM-DD}-dump.mdIf user says No:
If user provided query in $ARGUMENTS:
If NO query provided:
TODO.md - what's pendingCHANGELOG.md entries - what was just doneSTATUS.md - current focusLocation: .context/project/{active}/history/{uuid}-{YYYY-MM-DD}.md
Content (compact, ~200-400 tokens):
# Chat Session {uuid}
**Date**: {YYYY-MM-DD HH:MM}
**Tokens Used**: ~{approximate} / 200k
## Key Achievements
- [T###] Task completed
- Major milestone reached
- Decision made
## Technical Decisions
- Technology choice with rationale
- Architecture decision
- Library/framework selected
## Files Created/Modified
- path/to/file.ext
- another/file.js
## What's Next
{Brief 1-2 line summary}
---
## Full Chat Transcript
**⚠️ IMPORTANT**: Full conversation available at:
`{full-path-to-jsonl-file}`
**WARNING**: This file is LARGE (~2-3MB, ~140k+ tokens). NEVER load it entirely.
**How to use it**:
- Use `grep` to search for specific topics
- Use `tail -n 100` for recent messages
- Use `head -n 100` for session start
- Use `sed -n 'START,ENDp'` for specific line ranges
- Parse JSON with `jq` for structured queries
**Example commands**:
```bash
# Search for specific topic
grep -i "your topic" {path-to-file}
# Get last 50 messages
tail -n 50 {path-to-file}
# Count total lines
wc -l {path-to-file}
### Step 6: Create/Update NEXT.md (Comprehensive)
**Location**: `.context/project/{active}/NEXT.md`
**Purpose**: NEXT.md is the PRIMARY file a new AI session reads. It must contain enough actionable information for the new session to work effectively WITHOUT needing to read the history file.
**Content** (comprehensive, actionable):
```markdown
# Next Chat Session
## Previous Session Context
**Session**: {uuid} ({YYYY-MM-DD})
**History**: [history/{uuid}-{YYYY-MM-DD}.md](history/{uuid}-{YYYY-MM-DD}.md)
{If dump exists: **Dump**: [history/{uuid}-{YYYY-MM-DD}-dump.md](history/{uuid}-{YYYY-MM-DD}-dump.md)}
**Active Phase**: {from STATUS.md}
**Pending Tasks**: {from TODO.md}
**Last Modified**: {files changed this session}
---
## What To Do Next
{If user provided query: Use their query as PRIMARY guidance, enhanced with context}
{If no query: AI-generated guidance based on TODO.md, STATUS.md, CHANGELOG.md}
### Immediate Tasks
1. Task with context
2. Another task
### Quick Start Commands
```bash
{Common commands the new session will need}
{Include any important data/tables the new session needs - benchmarks, configs, etc.}
| File | Purpose |
|---|---|
| path/to/file | What it does |
**Important**: NEXT.md should be COMPREHENSIVE. The new AI session should be able to start working immediately after reading it.
### Step 7: Output Confirmation
Tell user:
✅ Checkpoint saved!
Files created/updated:
When starting next session:
/pp-resume to load context + next stepsSession ID: {uuid}
## Notes
- Always create history/ directory if it doesn't exist
- NEXT.md is overwritten each time (always shows latest)
- History files are never overwritten (one per session)
- NEXT.md should be COMPREHENSIVE - new AI session's primary reference
- History file is COMPACT - backup/deep-dive reference only
- User query from $ARGUMENTS takes priority for "What To Do Next"
- Always ask about dump before proceeding
## Error Handling
If unable to find session UUID:
- Inform user
- Still create NEXT.md with guidance
- Skip history file creation (not critical)
If active subproject unclear:
- Ask user which subproject
- Or use root .context/project/ as fallback