Initial commit: Claude Session Manager with complete CLI toolset
- 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
This commit is contained in:
William Valentin
310
README.md
Normal file
310
README.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user