0625d457be
- Add TypeScript project structure with Bun runtime - Implement CLI commands for session, project, stats, and optimization - Add SQLite database integration with prepared statements - Include AGENTS.md for development guidelines - Add Makefile for common development tasks - Configure ESLint and TypeScript with strict mode
310 lines
7.8 KiB
Markdown
310 lines
7.8 KiB
Markdown
# 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 <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
|
|
```bash
|
|
csm project create --name "My Project" --path "/path/to/project"
|
|
```
|
|
|
|
### 2. Start a Session
|
|
```bash
|
|
csm session start --project <project-id> --model sonnet
|
|
```
|
|
|
|
### 3. Track Usage
|
|
```bash
|
|
csm session track <session-id> <tokens> <messages>
|
|
```
|
|
|
|
### 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 <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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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
|
|
```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 <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
|
|
|
|
```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. |