Claude Session Manager

Advanced session management system for Claude CLI that preserves conversation context across sessions.

Features

• Automatic Context Preservation: Conversations are automatically captured and saved every 2 seconds
• Session Management: Create, resume, and delete sessions for different projects
• Auto-start Sessions: New sessions start automatically after creation
• CLAUDE.md Integration: Context is loaded via CLAUDE.md without disrupting existing content
• Working Directory Memory: Each session remembers and returns to its working directory
• Export Functionality: Export conversations to Markdown or JSON format
• Real-time Capture: Conversations are saved even if terminal is forcefully closed

Installation

From PyPI

pip install claude-session-manager

From source

git clone https://github.com/ahmetkumass/claude-session-manager
cd claude-session-manager
pip install -e .

Quick Start

Basic Commands

# Quick start - creates and starts a session immediately
cs quick

# Create named session - automatically starts
cs create --name "api_project"

# Create without starting
cs create --name "api_project" --no-start

# List all sessions
cs list

# Resume existing session
cs resume <session_id>

# Delete session
cs delete <session_id>

# Delete all sessions
cs delete --all

# Export session
cs export <session_id>

Usage Guide

Starting a New Project

# Navigate to project directory
cd ~/projects/my-api

# Create and start session
cs create --name "my_api"

# Work with Claude - context is automatically saved
> Create a FastAPI application structure
> Add user authentication endpoints

# Exit anytime - context is preserved
# Use Ctrl+C, /exit, or close terminal

Resuming Work

# List available sessions
cs list

# Output:
# ID         Name           Created              Context    Description
# --------------------------------------------------------------------------------
# abc123     my_api         2024-01-15 10:30     25         
# def456     frontend       2024-01-14 15:45     42         React dashboard

# Resume session - previous context is automatically loaded
cs resume abc123

# Claude remembers your previous conversation
> Continue with the authentication endpoints we discussed

Project Switching

# Working on API
cs resume api_session_id
> Implement rate limiting

# Switch to frontend project
cs resume frontend_session_id
> Debug the login component

# Each session maintains its own context

Command Reference

Command	Description	Alias
create --name <name>	Create and start new session	new
create --name <name> --no-start	Create without starting
quick	Create quick session with timestamp name	q
list	List all sessions	ls
resume <id>	Resume session with context
resume <id> --full	Resume with full history
delete <id>	Delete specific session	rm
delete --all	Delete all sessions
export <id>	Export to Markdown
export <id> --format json	Export to JSON
save <id> <message>	Manually save message
current	Show current session

Short Aliases

The cs command is the primary alias. Additional shortcuts:

cs q              # Quick start
cs ls             # List sessions
cs rm <id>        # Delete session

How It Works

Context Loading

When resuming a session, the system:

1. Reads existing CLAUDE.md if present
2. Appends session context to CLAUDE.md
3. Claude automatically reads the context
4. On exit, restores original CLAUDE.md content

Automatic Capture

Conversations are captured through:

1. Background monitoring every 2 seconds
2. Signal handlers for clean exits
3. Parsing Claude's JSONL log files
4. Automatic save even on terminal force-close

File Structure

~/.claude-sessions/
├── current_session.json       # Active session tracker
├── <session_id>.json          # Session data and context
└── context_<session_id>.md    # Formatted context file

Advanced Usage

Full History Loading

# Load complete conversation history
cs resume <session_id> --full

Manual Context Addition

# Add custom context to session
cs save <session_id> "Important: API key is in .env file" --role user
cs save <session_id> "Understood, I'll read from .env" --role assistant

Session Information

# View current active session
cs current

# List sessions with context count
cs list

Best Practices

1. One session per project - Keep contexts separate and organized
2. Descriptive names - Use meaningful session names for easy identification
3. Regular exports - Export important sessions for backup
4. Clean up regularly - Delete old sessions with cs delete --all

Technical Details

Context Preservation

• Monitors ~/.claude/projects/ for JSONL changes
• Parses conversation data from Claude's native format
• Updates session context in real-time
• Preserves working directory per session

CLAUDE.md Integration

• Preserves existing CLAUDE.md content
• Adds session context under ## Session Context section
• Restores original content on exit
• No permanent modifications to project files

Contributing

Contributions are welcome. Please submit pull requests with:

• Clear commit messages
• Updated documentation
• Test coverage for new features

License

MIT License - see LICENSE file for details.

Support

For issues and feature requests, please use the GitHub issue tracker.

---

This is an independent project and is not affiliated with Anthropic or Claude.