ccsm — Claude Code Session Manager

A CLI tool that helps developers discover, organize, and resume Claude Code sessions from previous days.

Problem

After several days of using Claude Code, it becomes difficult to remember:

• What you were working on yesterday
• Which session contained a specific task
• How to quickly resume a previous development thread

Install

Clone and build from source:

git clone git@gitlab.cee.redhat.com:kewang/ccsm.git
cd ccsm
go install ./cmd/ccsm

Usage

List sessions

ccsm list          # Yesterday's sessions (default)
ccsm list -d0      # Today's sessions
ccsm list -d1      # Yesterday's sessions
ccsm list -d2      # 2 days ago
ccsm list -w       # Last 7 days
ccsm list -a       # All sessions

Example output:

📅 Yesterday (Mar 1)
──────────────────────────────────
  a0effe  04:35  Fix OAuth API error handling
          project: ai-helpers  branch: fix-oauth  msgs: 117
  1b2ada  03:19  Kubernetes API server rebase
          project: myproject  branch: main  msgs: 3

With AI-generated summaries:

When sessions have been summarized using the session-summary Claude Code skill, you'll see enhanced 20-30 word titles and topics:

📅 Today (Mar 3)
──────────────────────────────────
  abc123  02:15  Created session-summary skill for Claude Code enabling automated conversation...
          topics: claude-code, skill-development, session-management
          project: my-claude-skills  branch: main  msgs: 45

Search sessions

ccsm search oauth
ccsm search "kubernetes rebase"
ccsm search "20-30 word"

Searches across:

• AI-generated titles (if available)
• AI-generated topics (if available)
• First user messages (fallback titles)
• Project names

Show full session summary

Display complete AI-generated summary for a session:

ccsm show abc123      # Short ID works
ccsm show abc123-full-uuid   # Full ID also works

Example output:

📊 Session Summary

💾 Created session-summary skill for Claude Code enabling automated conversation...
   (27 words)

📋 Overview:
Developed and deployed comprehensive session-summary skill for Claude Code
enabling automated conversation analysis and intelligent 20-30 word session
naming...

🎯 Key Topics:
  • Claude Code session management
  • Skill development workflow
  • 20-30 word naming convention

✅ Accomplishments:
  1. Created feature branch feature/session-summary-rename-skill
  2. Developed comprehensive SKILL.md with detailed implementation guide
  ...

📝 Files Changed:
  Created:
    • skills/session-summary/SKILL.md (689 lines)
    • skills/session-summary/README.md (93 lines)

🔧 Tools & Skills Used:
  • Git - Branch creation and version control
  • Write - Created comprehensive skill documentation

💡 Key Decisions:
  • Use 20-30 word descriptive names (not brief titles)
  • Include technologies, approach, and outcomes in names

📈 Metrics:
  • Messages: 45
  • Commands: 12+

Resume a session

ccsm open a0effe           # Resume in current terminal (default)
ccsm open a0effe12-full-id # Full ID also works
ccsm open a0effe --tab     # Open in new terminal tab
ccsm open a0effe --tmux    # Open in new tmux window

Default behavior: Changes to the session's original project directory and runs claude --resume <id> in the current terminal.

New tab (--tab or -t): Opens the session in a new tab of your current terminal emulator:

• macOS: iTerm2, Terminal.app
• Linux: Terminator, GNOME Terminal, Konsole, xterm

New tmux window (--tmux): Opens the session in a new tmux window (requires running inside tmux):

# Must be inside tmux first
tmux new-session
ccsm open a0effe --tmux

Configuration

Custom Claude command

If you use a wrapper script instead of claude directly, set CCSM_CLAUDE_CMD:

export CCSM_CLAUDE_CMD=/path/to/your/claude-wrapper

Add this to your ~/.bashrc or ~/.zshrc.

How it works

ccsm scans ~/.claude/projects/*/ for .jsonl session files on each invocation. No index or database — always reads fresh data. For each session it extracts:

• Session ID and timestamps
• Project directory and git branch
• AI-generated summary metadata (if available)
• First user message (fallback title)
• Message count

Sessions are grouped by day with the most recent first.

Integration with session-summary skill

ccsm integrates seamlessly with the session-summary Claude Code skill:

Hybrid Data Storage:

1. Quick metadata - Read from .jsonl files for fast listing

   • 20-30 word AI-generated titles
   • Topic tags
   • Word count validation

2. Full summaries - Read from ~/.claude/summaries/ for detailed view

   • Complete session overview
   • Accomplishments and outcomes
   • Files changed
   • Tools used
   • Key decisions
   • Remaining work
   • Metrics

Workflow:

1. Use Claude Code with session-summary skill: /session-summary
2. Skill writes both inline metadata and full summary
3. ccsm list shows AI-generated titles automatically
4. ccsm show <id> displays complete structured summary

Benefits:

• ✅ Better session discovery with descriptive 20-30 word titles
• ✅ Search across AI-generated topics
• ✅ View full context without opening Claude Code
• ✅ Backward compatible (works with old sessions too)

Project structure

cmd/ccsm/main.go           — Cobra CLI with list, search, open commands
internal/session/session.go — Session model
internal/session/parser.go  — JSONL parser
internal/title/title.go     — Heuristic title from first user message
internal/scanner/scanner.go — Discovers sessions across projects
internal/formatter/         — Grouped-by-day output rendering