0xDarkMatter
7099761305
feat: Major expansion of agents, skills, and review command
|
4 months ago | |
|---|---|---|
| .. | ||
| LICENSE | 4 months ago | |
| README.md | 4 months ago | |
| load.md | 4 months ago | |
| save.md | 4 months ago | |
| status.md | 4 months ago | |
README.md
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.