# Claude Session Manager A powerful tool to manage and optimize your Claude Code programming sessions, implementing all the best practices from [PLAN.md](./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 ```bash # Clone the repository git clone 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 ```bash csm project create --name "My Project" --path "/path/to/project" ``` ### 2. Start a Session ```bash csm session start --project --model sonnet ``` ### 3. Track Usage ```bash csm session track ``` ### 4. End Session ```bash csm session end --summary "Implemented user authentication" ``` ### 5. View Statistics ```bash csm stats today ``` ## Command Reference ### Project Management ```bash # Create new project csm project create [-n ] [-p ] # List all projects csm project list # Show project details csm project info # Generate CLAUDE.md csm project claude-md # View session summaries csm project notes [-l ] # Export session history csm project export [-f ] [-o ] ``` ### Session Management ```bash # Start new session csm session start [-p ] [-m ] # End session csm session end [-i ] [-s ] # Track token usage csm session track # Add note to session csm session note [-t ] [-i ] # List recent sessions csm session list [-l ] [-p ] # Check session status csm session status # Schedule overlap hack csm session overlap [-d ] ``` ### Statistics & Analytics ```bash # Show usage statistics csm stats usage [-d ] # Today's usage and recommendations csm stats today # Workflow efficiency analysis csm stats optimize [-p ] # Detect anomalies and trends csm stats anomalies # Token usage breakdown csm stats tokens [-p ] ``` ### Optimization Tools ```bash # Get suggestions for specific task csm optimize suggest [-c ] # Generate optimal schedule csm optimize schedule # Analyze overall workflow csm optimize workflow [-p ] # Show optimization tips csm optimize tips ``` ## Usage Examples ### Example 1: Daily Workflow ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # 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 ```bash # Auto-generate comprehensive project context csm project claude-md # Includes tech stack, coding style, architecture, and common commands # Export session history for documentation csm project export --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 ```bash # 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.