User Configuration Plans

Manage Claude Code plan files stored in ~/.claude/plans/. Plans are markdown files created during plan mode sessions.

Arguments

Argument	Description
plan-name	View a specific plan (partial name match)
--list	List all plans with metadata
--archive	Move old plans to archive subdirectory
--cleanup N	Delete plans older than N days
(no args)	List recent plans

Plan File Format

Plans are stored as markdown files with generated names:

~/.claude/plans/
├── reflective-sauteeing-riddle.md
├── curious-dancing-penguin.md
└── archive/                      # Created by --archive
    └── old-completed-plan.md

Plan files contain:

• Plan content written during plan mode
• No formal structure required (user/Claude generated content)
• Filename is randomly generated adjective-verb-noun pattern

Workflow

Mode: List Plans (--list or no args)

List all plans with metadata:

from pathlib import Path
from datetime import datetime, timezone

plans_dir = Path.home() / ".claude" / "plans"

if not plans_dir.exists():
    print("No plans directory found (~/.claude/plans/)")
    exit(0)

plans = list(plans_dir.glob("*.md"))
plans.sort(key=lambda p: p.stat().st_mtime, reverse=True)

print(f"Found {len(plans)} plan(s):\n")

for plan in plans[:20]:  # Show 20 most recent
    stat = plan.stat()
    mtime = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc)
    size_kb = stat.st_size / 1024

    # Read first line as title hint
    with open(plan) as f:
        first_line = f.readline().strip()
        title = first_line[:50] if first_line else "(empty)"

    print(f"  {plan.stem}")
    print(f"    Modified: {mtime.strftime('%Y-%m-%d %H:%M')}")
    print(f"    Size: {size_kb:.1f} KB")
    print(f"    Preview: {title}")
    print()

Mode: View Plan

View a specific plan by name (supports partial match):

from pathlib import Path

plans_dir = Path.home() / ".claude" / "plans"
search = "reflective"  # From argument

# Find matching plans
matches = [p for p in plans_dir.glob("*.md") if search.lower() in p.stem.lower()]

if not matches:
    print(f"No plan found matching: {search}")
    print("Use --list to see all plans")
elif len(matches) > 1:
    print(f"Multiple matches for '{search}':")
    for m in matches:
        print(f"  {m.stem}")
    print("Please be more specific")
else:
    plan = matches[0]
    print(f"# Plan: {plan.stem}\n")
    print(plan.read_text())

Mode: Archive (--archive)

Move plans older than 30 days to archive:

from pathlib import Path
from datetime import datetime, timezone, timedelta
import shutil

plans_dir = Path.home() / ".claude" / "plans"
archive_dir = plans_dir / "archive"
archive_dir.mkdir(exist_ok=True)

cutoff = datetime.now(timezone.utc) - timedelta(days=30)
archived = []

for plan in plans_dir.glob("*.md"):
    mtime = datetime.fromtimestamp(plan.stat().st_mtime, tz=timezone.utc)
    if mtime < cutoff:
        dest = archive_dir / plan.name
        shutil.move(str(plan), str(dest))
        archived.append(plan.name)

if archived:
    print(f"✅ Archived {len(archived)} plan(s) to ~/.claude/plans/archive/")
    for name in archived:
        print(f"  • {name}")
else:
    print("No plans older than 30 days to archive")

Mode: Cleanup (--cleanup N)

Delete plans older than N days (with confirmation):

from pathlib import Path
from datetime import datetime, timezone, timedelta

plans_dir = Path.home() / ".claude" / "plans"
days = 90  # From argument
cutoff = datetime.now(timezone.utc) - timedelta(days=days)

to_delete = []
for plan in plans_dir.glob("*.md"):
    mtime = datetime.fromtimestamp(plan.stat().st_mtime, tz=timezone.utc)
    if mtime < cutoff:
        to_delete.append(plan)

if not to_delete:
    print(f"No plans older than {days} days")
else:
    print(f"Found {len(to_delete)} plan(s) older than {days} days:")
    for plan in to_delete:
        print(f"  • {plan.stem}")

    # Use AskUserQuestion for confirmation
    # If confirmed:
    for plan in to_delete:
        plan.unlink()
    print(f"✅ Deleted {len(to_delete)} plan(s)")

Output Format

List View

# Claude Code Plans

Found 5 plan(s) in ~/.claude/plans/

| Plan Name | Modified | Size | Preview |
|-----------|----------|------|---------|
| reflective-sauteeing-riddle | 2025-12-30 15:30 | 12.3 KB | # Plan: User Config Management |
| curious-dancing-penguin | 2025-12-29 10:00 | 5.1 KB | # Migration Strategy |
| brave-singing-dolphin | 2025-12-28 14:00 | 2.8 KB | # Feature Implementation |

## Quick Actions

- View plan: `/user-config:plans reflective`
- Archive old: `/user-config:plans --archive`
- Cleanup: `/user-config:plans --cleanup 90`

Plan View

# Plan: reflective-sauteeing-riddle

**Location:** ~/.claude/plans/reflective-sauteeing-riddle.md
**Modified:** 2025-12-30 15:30 UTC
**Size:** 12.3 KB

---

[Full plan content displayed here]

Use Cases

1. Review past planning sessions - Find plans from previous work
2. Resume abandoned plans - Copy content back to continue work
3. Learn from past approaches - Review how problems were solved
4. Clean up old plans - Remove stale planning artifacts

Notes

• Plans are created by Claude Code during plan mode
• Plan names are auto-generated (adjective-verb-noun pattern)
• Plans persist indefinitely unless manually cleaned
• Archive is just a subdirectory - no special behavior

Related Commands

• /user-config:status - Overview including plan count
• /user-config:storage - Storage breakdown including plans
• /user-config:prune - Comprehensive cleanup (includes plans)

Related Skill

This command uses the user-config-management skill for:

• Plans directory structure
• Known file patterns