claude-session-manager 1.0.0
Session management for Claude CLI - preserve context across projects
Requires Python: >=3.7
Keywords: claude, cli, session, management, context, ai, conversation

# Claude Session Manager

[![Python Version](https://img.shields.io/badge/python-3.7%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
pip install claude-session-manager
```

### From source

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

## Quick Start

### Basic Commands

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
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

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

### Manual Context Addition

```bash
# 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

```bash
# 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](LICENSE) file for details.

## Support

For issues and feature requests, please use the [GitHub issue tracker](https://github.com/ahmetkumass/claude-session-manager/issues).

---

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