Session Manager

Unified session management for Claude Code. Persist state, track progress, resume seamlessly.

The Problem

Claude Code doesn't persist everything across sessions:

┌─────────────────────────────────────────────────────────────┐
│                What Persists?                                │
├──────────────────────────┬──────────────────────────────────┤
│ ✓ Conversation history   │ Use: claude --resume             │
│ ✓ CLAUDE.md context      │ File: ./CLAUDE.md                │
├──────────────────────────┼──────────────────────────────────┤
│ ✗ TodoWrite tasks        │ Deleted on session end           │
│ ✗ Plan Mode thinking     │ In-memory only                   │
│ ✗ "Where was I?"         │ Lost context                     │
└──────────────────────────┴──────────────────────────────────┘

The Solution

Three commands that work together:

┌─────────────────────────────────────────────────────────────┐
│                  Session Lifecycle                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│     START              WORK                END              │
│       │                  │                  │               │
│       ▼                  ▼                  ▼               │
│   ┌──────┐          ┌────────┐         ┌──────┐            │
│   │/load │ ───────▶ │/status │ ──────▶ │/save │            │
│   └──────┘          └────────┘         └──────┘            │
│       │                  │                  │               │
│   Restore            Dashboard          Persist             │
│   context             view              state               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Commands

/status - Dashboard View

See everything at a glance:

📊 Project Status

┌─ Plan ─────────────────────────────────────────┐
│ Goal: Add user authentication with OAuth2      │
│                                                │
│ ✓ Step 1: Research OAuth providers [S]         │
│ ✓ Step 2: Set up Google OAuth app [S]          │
│ ◐ Step 3: Implement OAuth flow [M]  ← CURRENT  │
│ ○ Step 4: Add token refresh [S]                │
│ ○ Step 5: Write integration tests [M]          │
│                                                │
│ Progress: ██████░░░░ 40% (2/5)                 │
└────────────────────────────────────────────────┘

┌─ Active Tasks ─────────────────────────────────┐
│ ◐ Fix callback URL handling                    │
│ ○ Add token refresh logic                      │
└────────────────────────────────────────────────┘

┌─ Git ──────────────────────────────────────────┐
│ Branch: feature/auth                           │
│ Uncommitted: 3 files (+45/-12)                 │
└────────────────────────────────────────────────┘

/save - Persist State

Save before ending your session:

/save "Stopped at callback URL issue"

✓ Session saved

┌─ Saved State ──────────────────────────────────┐
│ Plan: Step 3/5 (40%) - Implement OAuth flow    │
│ Tasks: 1 completed, 1 in progress, 1 pending   │
│ Git: 3 uncommitted files                       │
└────────────────────────────────────────────────┘

Restore with: /load

/load - Restore Context

Pick up where you left off:

/load

📂 Session Loaded

┌─ Plan Context ─────────────────────────────────┐
│ Goal: Add user authentication with OAuth2      │
│ Current: ◐ Step 3 - Implement OAuth flow       │
│ Progress: ██████░░░░ 40% (2/5)                 │
└────────────────────────────────────────────────┘

┌─ Restored Tasks ───────────────────────────────┐
│ ◐ Fix callback URL handling                    │
│ ○ Add token refresh logic                      │
└────────────────────────────────────────────────┘

┌─ Notes ────────────────────────────────────────┐
│ "Stopped at callback URL issue"                │
└────────────────────────────────────────────────┘

Suggested: Continue with "Fix callback URL handling"

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Commands                                │
├─────────────┬─────────────┬─────────────────────────────────┤
│   /status   │   /save     │   /load                         │
│   (read)    │   (write)   │   (read + restore)              │
└──────┬──────┴──────┬──────┴──────┬──────────────────────────┘
       │             │             │
       │             ▼             │
       │    ┌────────────────┐     │
       │    │ .claude/       │     │
       │    │ claude-state   │◄────┤
       │    │ .json          │     │
       │    ├────────────────┤     │
       │    │ {              │     │
       │    │   todos: {},   │     │
       │    │   plan: {},    │     │
       │    │   git: {},     │     │
       │    │   notes: ""    │     │
       │    │ }              │     │
       │    └────────────────┘     │
       │             │             │
       │             │             │
       ▼             ▼             ▼
┌─────────────────────────────────────────────────────────────┐
│                    docs/PLAN.md                              │
│  (Strategic plan - managed by /plan command)                │
└─────────────────────────────────────────────────────────────┘

State File Format

.claude/session-cache.json:

{
  "version": "2.0",
  "timestamp": "2025-11-27T10:30:00Z",

  "todos": {
    "completed": ["Set up OAuth credentials"],
    "in_progress": ["Fix callback URL handling"],
    "pending": ["Add token refresh"]
  },

  "plan": {
    "file": "docs/PLAN.md",
    "goal": "Add user authentication with OAuth2",
    "current_step": "Step 3: Implement OAuth flow",
    "progress_percent": 40
  },

  "git": {
    "branch": "feature/auth",
    "last_commit": "abc123f",
    "uncommitted_count": 3
  },

  "notes": "Stopped at callback URL issue"
}

Workflow Examples

Daily Workflow

Morning:
  $ claude
  > /load                    # See where you left off
  > /status                  # Check current state

Work:
  > (make changes)
  > /status                  # Quick check anytime

End of day:
  > /save "Finished auth, starting tests tomorrow"

Context Switch

Working on Feature A:
  > /save "Pausing for urgent bug"

Switch to Bug Fix:
  > git checkout hotfix/bug
  > (fix bug)
  > git checkout feature-a

Resume Feature A:
  > /load                    # Restore Feature A context

Team Handoff

Developer 1:
  > /save "Implemented OAuth, needs review" --commit
  > git push

Developer 2:
  > git pull
  > /load                    # See exactly where they stopped

Integration with /plan

These commands integrate with the /plan command:

┌─────────────────────────────────────────────────────────────┐
│                 Unified State Model                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Strategic (Big Picture)          Tactical (Right Now)    │
│   ────────────────────────         ───────────────────────  │
│                                                             │
│   docs/PLAN.md                     .claude/session-cache.json│
│   ├─ Project goal                  ├─ TodoWrite tasks       │
│   ├─ Implementation steps          ├─ Current plan step ref │
│   ├─ Progress markers              ├─ Git context           │
│   └─ Decision log                  └─ Session notes         │
│                                                             │
│         ▲                                   ▲               │
│         │                                   │               │
│         │         ┌───────────┐             │               │
│         └─────────│  /status  │─────────────┘               │
│                   │ (unified  │                             │
│                   │   view)   │                             │
│                   └───────────┘                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Why Not Just Use --resume?

Feature	claude --resume	Session Manager
Conversation history	✓	-
TodoWrite tasks	✗	✓
Plan context	✗	✓
Git state	✗	✓
Human-readable	✗	✓
Git-trackable	✗	✓
Works across machines	✗	✓
Team sharing	✗	✓

Use both together: claude --resume for conversation, /load for task state.

Installation

This is a submodule of claude-mods.

# Via claude-mods (recommended)
git clone --recursive https://github.com/0xDarkMatter/claude-mods.git
cd claude-mods
./install.sh  # or .\install.ps1 on Windows

# Standalone
git clone https://github.com/0xDarkMatter/session-manager.git
# Copy *.md files to ~/.claude/commands/

Command Reference

Command	Purpose	Modifies Files
/status	Dashboard view	No (read-only)
/save [notes]	Persist state	Yes (.claude/)
/load	Restore state	Yes (TodoWrite)

Flag	Command	Effect
--brief	/status	Single-line output
--commit	/save	Git commit state files
--no-restore	/load	Preview without restoring
--clear	/load	Clear state after loading

License

MIT

---

Part of the claude-mods collection.