docs/reference/claude-code-history-management.md
Research Date: 2025-10-09 Purpose: Understand .jsonl file structure, performance impact, and establish rotation policy
Location: ~/.claude/projects/{project-directory}/
Data Structure (from analysis of actual files):
{
"type": "summary|file-history-snapshot|user|assistant|system|tool_use|tool_result|message",
"timestamp": "ISO-8601 timestamp",
"cwd": "/absolute/path/to/working/directory",
"sessionId": "uuid",
"gitBranch": "branch-name",
"content": "message content or command",
"messageId": "uuid for message tracking"
}
Key Message Types (from 2.6MB conversation analysis):
message (228): Container for conversation messagesassistant (228): Claude's responsesuser (182): User inputstool_use (137): Tool invocationstool_result (137): Tool execution resultstext (74): Text content blocksfile-history-snapshot (39): File state trackingthinking (31): Claude's reasoning processsystem (12): System-level messages{
"type": "file-history-snapshot",
"messageId": "uuid",
"snapshot": {
"messageId": "uuid",
"trackedFileBackups": {},
"timestamp": "ISO-8601"
},
"isSnapshotUpdate": false
}
Purpose (inferred from structure):
Official Best Practices (source):
Resume Commands:
--continue: Automatically continue most recent conversation/resume: Show list of recent sessions and choose oneStatus: Open (Major Issue) URL: https://github.com/anthropics/claude-code/issues/5024
Reported Problems:
Current Workaround:
.claude.json (risky - can break configurations)claude history clear (removes ALL history across ALL projects)Status: Critical URL: https://github.com/anthropics/claude-code/issues/7985
Reported Problems:
Status: Regression (after undo/redo feature) URL: https://github.com/anthropics/claude-code/issues/8839
Impact:
Status: Bug URL: https://github.com/anthropics/claude-code/issues/8755
Impact:
/clear command stopped functioning for some usersCurrent State (as of 2025-10-09):
Age Distribution:
Comparison to Other Projects:
33M agiletec (57 files) - Most active
14M SSD-2TB project
6.3M tokium
2.6M bunseki
Source: Anthropic Privacy Center
Source: Custom Data Retention Controls
Finding: No official documentation found regarding:
Current Tools:
claude history clear: Removes ALL history (all projects, destructive)Source: Claude Code Best Practices
Key Guidelines:
/clear frequently: "Reset context window between tasks"Quote: "During long sessions, Claude's context window can fill with irrelevant conversation, file contents, and commands which can reduce performance, so use the /clear command frequently between tasks to reset the context window."
~/.claude/CLAUDE.md) → Workspace → ProjectSource: Community Best Practices
Use /clear when:
Restart session when:
Pattern: "Scope a chat to one project or feature"
/clear when goal completePattern: "Avoid extensive, unrefined context"
Pattern: "Ghost icon for temporary conversations"
# Backup first
mkdir -p ~/.claude/projects-archive/$(date +%Y-%m)
# Find and archive
find ~/.claude/projects/ -name "*.jsonl" -mtime +30 -type f \
-exec mv {} ~/.claude/projects-archive/$(date +%Y-%m)/ \;
Rationale:
# Per-project archive
mkdir -p ~/.claude/projects-archive/agiletec/$(date +%Y-%m)
find ~/.claude/projects/-Users-kazuki-github-agiletec -name "*.jsonl" -mtime +14 -type f \
-exec mv {} ~/.claude/projects-archive/agiletec/$(date +%Y-%m)/ \;
Rationale:
# Find files >1MB
find ~/.claude/projects/ -name "*.jsonl" -type f -size +1M -exec ls -lh {} \;
# Review and archive if not actively used
Criteria for Archival:
# Monthly archive
mkdir -p ~/.claude/projects-archive/$(date +%Y-%m)
find ~/.claude/projects/ -name "*.jsonl" -mtime +7 -type f \
-exec mv {} ~/.claude/projects-archive/$(date +%Y-%m)/ \;
When to Use:
# BACKUP EVERYTHING FIRST
tar -czf ~/claude-history-backup-$(date +%Y%m%d).tar.gz ~/.claude/projects/
# Keep only last 7 days
find ~/.claude/projects/ -name "*.jsonl" -mtime +7 -type f -delete
When to Use:
claude-history-rotate.sh#!/usr/bin/env bash
# Claude Code Conversation History Rotation
# Usage: ./claude-history-rotate.sh [--dry-run] [--days N]
set -euo pipefail
DAYS=${DAYS:-30}
DRY_RUN=false
ARCHIVE_BASE=~/.claude/projects-archive
# Parse arguments
while [[ $# -gt 0 ]]; do
case $1 in
--dry-run) DRY_RUN=true; shift ;;
--days) DAYS="$2"; shift 2 ;;
*) echo "Unknown option: $1"; exit 1 ;;
esac
done
# Create archive directory
ARCHIVE_DIR="$ARCHIVE_BASE/$(date +%Y-%m)"
mkdir -p "$ARCHIVE_DIR"
# Find old conversations
OLD_FILES=$(find ~/.claude/projects/ -name "*.jsonl" -mtime "+$DAYS" -type f)
if [[ -z "$OLD_FILES" ]]; then
echo "No files older than $DAYS days found."
exit 0
fi
# Count and size
FILE_COUNT=$(echo "$OLD_FILES" | wc -l | tr -d ' ')
TOTAL_SIZE=$(echo "$OLD_FILES" | xargs du -ch | tail -1 | awk '{print $1}')
echo "Found $FILE_COUNT files older than $DAYS days ($TOTAL_SIZE total)"
if [[ "$DRY_RUN" == "true" ]]; then
echo "DRY RUN - Would archive:"
echo "$OLD_FILES"
exit 0
fi
# Archive files
echo "$OLD_FILES" | while read -r file; do
mv "$file" "$ARCHIVE_DIR/"
echo "Archived: $(basename "$file")"
done
echo "✓ Archived $FILE_COUNT files to $ARCHIVE_DIR"
# Add to crontab (monthly cleanup)
# 0 3 1 * * /Users/kazuki/.local/bin/claude-history-rotate.sh --days 30
# Or use launchd on macOS
cat > ~/Library/LaunchAgents/com.user.claude-history-rotate.plist <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.user.claude-history-rotate</string>
<key>ProgramArguments</key>
<array>
<string>/Users/kazuki/.local/bin/claude-history-rotate.sh</string>
<string>--days</string>
<string>30</string>
</array>
<key>StartCalendarInterval</key>
<dict>
<key>Day</key>
<integer>1</integer>
<key>Hour</key>
<integer>3</integer>
</dict>
</dict>
</plist>
EOF
launchctl load ~/Library/LaunchAgents/com.user.claude-history-rotate.plist
#!/usr/bin/env bash
# claude-history-check.sh
THRESHOLD_MB=100
PROJECTS_DIR=~/.claude/projects
TOTAL_SIZE_MB=$(du -sm "$PROJECTS_DIR" | awk '{print $1}')
echo "Claude Code conversation history: ${TOTAL_SIZE_MB}MB"
if [[ $TOTAL_SIZE_MB -gt $THRESHOLD_MB ]]; then
echo "⚠️ WARNING: History size exceeds ${THRESHOLD_MB}MB threshold"
echo "Consider running: claude-history-rotate.sh --days 30"
# Find largest projects
echo ""
echo "Largest projects:"
du -sm "$PROJECTS_DIR"/*/ | sort -rn | head -5
fi
/clear✅ Safe to Delete:
⚠️ Caution Required:
❌ Known Issues:
/clear command bugs (Issue #8755)Daily Practice:
/clear between major tasksWeekly Review (Sunday):
# Check current state
du -sh ~/.claude/projects/*/
# Archive old conversations (>14 days)
claude-history-rotate.sh --days 14 --dry-run # Preview
claude-history-rotate.sh --days 14 # Execute
Monthly Cleanup (1st of month):
# Aggressive cleanup (>30 days)
claude-history-rotate.sh --days 30
# Review large files
find ~/.claude/projects/ -name "*.jsonl" -size +1M -mtime +7
Performance Threshold Actions:
Watch for Official Solutions:
claude history prune command (requested in #5024)Community Tools:
Generated: 2025-10-09 04:24 JST
33M -Users-kazuki-github-agiletec (57 files)
14M -Volumes-SSD-2TB (project count: N/A)
6.3M -Users-kazuki-github-tokium
2.6M -Users-kazuki-github-bunseki
1.9M -Users-kazuki
1.9M -Users-kazuki-github-superclaude
---
Total: ~62MB across all projects
Status: ✅ Healthy (no immediate action required)
Reasoning:
Next Review: 2025-10-16 (weekly check)