ccsm

CCSM — Claude Code Session Manager

TUI + MCP plugin for browsing, searching, and resuming Claude Code sessions.

⬡ CCSM — Claude Code Session Manager
 WORKTREES          │ SESSIONS · GUI/panel        │ DETAIL
─────────────────── │────────────────────────────── │──────────────────────────
▶ PROJECTS          │[ 🟢 ACTIVE 3 ] 🔵 BACK 0 ...│── 📋 SESSION ──────────
  ▼ GUI (432)       │                              │  Title   整理GPT5.2数据
    main (329)      │ ● 整理GPT5.2数据并对比分析   │  Status  ● ACTIVE  Duration 2h
    panel (4)       │   📝 "整理GPT5.2在subset..." │  Branch  memory   Last     5h ago
    memory (73)     │ ● CCSM架构设计        23h ago│── 🧭 MILESTONES ────────
    streamIT (3)    │   📝 "重构数据库..."   💬 42  │  ✓ Data Cleanup & Analysis
  ▼ VLM-Router (0)  │                              │  ✓ Multi-Model Comparison
                    │                              │  ▶ Eval Mode Analysis
 ↑↓ Navigate  Tab Panel  1-4 Status  / Search  r Resume  s AI  D Archive  q Quit

Features

• Three-panel TUI — Worktree tree / Session list / Detail view
• Status Tab filtering — ACTIVE | BACK | IDEA | DONE, switch with 1/2/3/4
• Milestone timeline — Rule-based (free, instant) or LLM-powered (haiku, ~12s) phase extraction
• Breakpoint — "Where was I?" highlighted in orange, the single most useful info for context restoration
• AI Title & Intent — Haiku generates short titles (≤8 Chinese chars) and one-line summaries, cached to sidecar
• Full-text Search — Press / for fuzzy search across title, intent, content, branch, tags (powered by in-memory SessionIndex, no count limits)
• Lineage Detection — Automatic fork/compact/duplicate relationship detection across sessions
• Session Graph — Press g to toggle DAG visualization showing session relationships (fork=◆, compact=◇, duplicate=◉)
• Timestamp Fix — Sessions sort by last actual message time, not file modification time (prevents "peeking" from changing order)
• Duplicate Detection — Identifies sessions from concurrent SSH terminals (same cwd+branch, <5min gap)
• Title Lock — lock_title() stores titles in CCSM sidecar, immune to Claude Code's 64KB tail window crashes
• Resume — Press r to jump back into a session via claude --resume
• Archive — Press D to mark sessions as DONE
• MCP Server — Expose sessions to Claude Code itself for self-aware context management

Quick Start

# From the project root
cd /path/to/GUI
source ml_env/bin/activate

# Run the TUI
PYTHONPATH=projects/ccsm:$PYTHONPATH python3 -m ccsm

# Or install as a package
pip install -e projects/ccsm
ccsm

Architecture

ccsm/
├── core/                   # Backend logic (no UI dependencies)
│   ├── discovery.py        # Scan ~/.claude/projects/ for sessions & worktrees + detect_duplicates()
│   ├── parser.py           # JSONL parser + XML sanitization + parse_session_timestamps()
│   ├── lineage.py          # NEW: Fork/compact/dup detection, DAG construction
│   ├── index.py            # NEW: Persistent full-text fuzzy search index (SessionIndex)
│   ├── status.py           # Auto-classify sessions: ACTIVE/BACK/IDEA/DONE/NOISE
│   ├── milestones.py       # Rule-based milestone extraction (6 signal types)
│   ├── summarizer.py       # Dual-mode summarizer (extract / LLM via haiku)
│   └── meta.py             # Sidecar metadata read/write (~/.ccsm/) + lock_title(), lineage serialization
├── models/
│   └── session.py          # Dataclasses: SessionInfo, SessionMeta, Milestone, Breakpoint + LineageType, SessionLineage
├── tui/
│   ├── app.py              # Textual App entry point
│   ├── screens/main.py     # MainScreen — panel layout, keybindings, async workers
│   ├── widgets/
│   │   ├── worktree_tree.py    # Left panel: project/worktree tree
│   │   ├── session_list.py     # Middle panel: tab bar + session cards
│   │   ├── session_card.py     # 2-line compact card with right-aligned metadata
│   │   ├── session_detail.py   # Right panel: SESSION/MILESTONES/BREAKPOINT/LAST REPLY
│   │   └── session_graph.py    # NEW: DAG visualization widget (lineage graph)
│   └── styles/
│       └── claude_native.tcss  # Stone/Orange theme inspired by Claude's design language
├── mcp/
│   └── server.py           # MCP server with 30s TTL cache
└── cli/
    └── main.py             # Click CLI (placeholder for `ccsm list`, `ccsm resume`)

Keyboard Shortcuts

Key	Action
1 2 3 4	Switch to ACTIVE / BACK / IDEA / DONE tab
/	Full-text fuzzy search (backed by SessionIndex)
g	Toggle session lineage graph view
r	Resume selected session (claude --resume)
s	Trigger AI summary (haiku LLM)
D	Archive selected session (mark as DONE)
h	Toggle NOISE session visibility
Tab / Shift+Tab	Cycle panel focus
q	Quit

Summarization Modes