code-plan/README.md

Claude Session Manager

A powerful tool to manage and optimize your Claude Code programming sessions, implementing all the best practices from PLAN.md.

Features

🎯 Session Management

• 5-Hour Window Tracking: Automatically manages Claude's 5-hour session windows
• Overlap Hack: Schedule overlap sessions for extended work periods
• Smart Scheduling: Optimize session timing based on usage patterns
• Active Session Monitoring: Real-time tracking of current sessions

📊 Token Optimization

• Usage Analytics: Detailed token consumption tracking
• Optimization Recommendations: AI-powered suggestions to reduce token usage
• Efficiency Scoring: Quantitative measurement of session efficiency
• Cost Analysis: Track token usage by model and project

🗂️ Project Context Management

• CLAUDE.md Generation: Auto-generate project context files
• Tech Stack Detection: Automatically identify project technologies
• Coding Style Analysis: Detect and document coding conventions
• Common Commands: Track frequently used project commands

📝 Smart Note-Taking

• Session Summaries: Automatic generation of session summaries
• Quick Notes: Categorized note-taking during sessions
• Searchable History: Find information across all sessions
• Export Capabilities: Export session history in various formats

🚀 Workflow Optimization

• Task Scheduling: Optimal scheduling for upcoming tasks
• Model Recommendations: AI-powered model selection suggestions
• Batching Suggestions: Recommendations for grouping similar tasks
• Anomaly Detection: Identify workflow inefficiencies

Installation

# Clone the repository
git clone <repository-url>
cd claude-session-manager

# Install dependencies
npm install

# Build the project
npm run build

# Install globally (optional)
npm install -g .

Quick Start

1. Create a Project

csm project create --name "My Project" --path "/path/to/project"

2. Start a Session

csm session start --project <project-id> --model sonnet

3. Track Usage

csm session track <session-id> <tokens> <messages>

4. End Session

csm session end --summary "Implemented user authentication"

5. View Statistics

csm stats today

Command Reference

Project Management

# Create new project
csm project create [-n <name>] [-p <path>]

# List all projects
csm project list

# Show project details
csm project info <project-id>

# Generate CLAUDE.md
csm project claude-md <project-id>

# View session summaries
csm project notes <project-id> [-l <limit>]

# Export session history
csm project export <project-id> [-f <format>] [-o <output>]

Session Management

# Start new session
csm session start [-p <project-id>] [-m <model>]

# End session
csm session end [-i <session-id>] [-s <summary>]

# Track token usage
csm session track <session-id> <tokens> <messages>

# Add note to session
csm session note <note> [-t <type>] [-i <session-id>]

# List recent sessions
csm session list [-l <limit>] [-p <project-id>]

# Check session status
csm session status

# Schedule overlap hack
csm session overlap [-d <hours>]

Statistics & Analytics

# Show usage statistics
csm stats usage [-d <days>]

# Today's usage and recommendations
csm stats today

# Workflow efficiency analysis
csm stats optimize [-p <project-id>]

# Detect anomalies and trends
csm stats anomalies

# Token usage breakdown
csm stats tokens [-p <project-id>]

Optimization Tools

# Get suggestions for specific task
csm optimize suggest <task> [-c <complexity>]

# Generate optimal schedule
csm optimize schedule

# Analyze overall workflow
csm optimize workflow [-p <project-id>]

# Show optimization tips
csm optimize tips

Usage Examples

Example 1: Daily Workflow

# Start your day by checking status
csm session status

# Start a new session for feature development
csm session start --project my-web-app --model sonnet

# During development, add quick notes
csm session note "Fixed login bug" --type bug
csm session note "Add password validation" --type feature

# Track usage periodically
csm session track abc123 25000 15

# End session with summary
csm session end --summary "Implemented user authentication with password validation"

# Check today's optimization recommendations
csm stats today

Example 2: Complex Architecture Task

# Get optimization suggestions first
csm optimize suggest "Design microservices architecture" --complexity complex

# Start with Opus for complex task
csm session start --project my-system --model opus

# Schedule overlap hack for extended work
csm session overlap --delay 2

# End with detailed summary
csm session end --summary "Designed comprehensive microservices architecture with service mesh"

Example 3: Project Setup

# Create new project
csm project create --name "E-commerce Platform" --path ./ecommerce

# Generate CLAUDE.md for context
csm project claude-md "E-commerce Platform"

# View project info
csm project info "E-commerce Platform"

Best Practices (from PLAN.md)

Context Management

• Use /clear frequently - Most crucial command for token savings
• Use /compact for long but necessary conversations
• Leverage CLAUDE.md for long-term project memory
• Target specific files with @ symbol or full paths

Workflow Optimization

• Batch similar requests into single detailed prompts
• Use Sonnet for implementation, Opus for complex tasks
• Adopt "Plan First" approach - plan, review, execute
• Use "think hard" for complex planning tasks

5-Hour Window Strategy

• Use overlap hack 2-3 hours before intensive work
• Cycle to non-AI tasks when session runs out
• Schedule complex tasks for fresh sessions
• Track window timing to maximize productivity

Configuration

The tool stores all data in a local SQLite database (./data/claude-sessions.db). Configuration options:

• Database location: Can be overridden with environment variable CSM_DB_PATH
• Default model: Sonnet (recommended for most tasks)
• Token limits: Configurable in service classes

Advanced Features

Workflow Automation

# Generate optimal schedule for multiple tasks
csm optimize schedule
# Enter your tasks interactively
# Get optimized schedule with model recommendations

# Analyze workflow efficiency
csm optimize workflow
# Get comprehensive analysis with actionable recommendations

Token Optimization

# Get personalized recommendations
csm stats today
# See high-priority optimization suggestions

# Track token efficiency trends
csm stats usage --days 30
# Monitor your optimization progress over time

Project Intelligence

# Auto-generate comprehensive project context
csm project claude-md <project-id>
# Includes tech stack, coding style, architecture, and common commands

# Export session history for documentation
csm project export <project-id> --format markdown --output docs/session-history.md

Troubleshooting

Common Issues

1. Database errors: Ensure write permissions to ./data/ directory
2. Project not found: Use csm project list to see available projects
3. Session tracking: Always track tokens before ending session for accurate statistics

Getting Help

# Show all commands
csm --help

# Show command-specific help
csm session --help
csm project --help
csm stats --help
csm optimize --help

# Show optimization tips
csm optimize tips

Contributing

This tool implements the best practices from PLAN.md. Contributions welcome for:

• Additional optimization algorithms
• New workflow automation features
• Enhanced analytics and reporting
• Integration with other development tools

License

MIT License - see LICENSE file for details.