Claude Pro Session Manager

A Python-based session manager for Claude Pro that automates the creation and tracking of Claude sessions to optimize usage within 5-hour windows. The system provides intelligent session lifecycle management through automated scheduling and comprehensive status tracking.

Features

• 🚀 Automated Session Management: Seamlessly create and track Claude Pro sessions
• ⏰ 5-Hour Window Optimization: Intelligent tracking of session expiration times
• 📊 Real-time Status Monitoring: Check current session status and remaining time
• 🔧 Clean Architecture: Well-structured codebase with clear separation of concerns
• 🛡️ Error Handling: Comprehensive error management and user-friendly messages
• 🎨 Rich Terminal Output: Beautiful formatted output using Rich library
• 🔄 Force Session Override: Option to force new sessions when needed

Architecture

The application follows clean architecture principles with distinct layers:

src/
└── claude_code_session_manager/
    ├── domain/          # Core business models and exceptions
    ├── infrastructure/  # External dependencies (Claude CLI, file storage)
    ├── services/        # Business logic (SessionManager)
    ├── config/          # Application settings and configuration
    └── utils/           # Formatting utilities

Prerequisites

• Python 3.10 or higher
• Claude CLI installed and configured
• macOS (primary platform, with plans for cross-platform support)

Installation

Method 1: pipx (Recommended)

# Install pipx if not already installed
brew install pipx
pipx ensurepath   # apoi deschide un shell nou

# Clone and install
git clone <repository-url>
cd claude-code-sessions-manager
pipx install .

# Verify installation
claude-sessions status

Method 2: Development Setup

1. Clone the repository:

   git clone <repository-url>
   cd claude-code-sessions-manager

2. Install dependencies:

   pip install -r requirements.txt

3. Verify Claude CLI installation:

   claude --help

Usage

Quick Start

With pipx installation (recommended):

# Start a new session immediately
claude-sessions start-now

# Check current session status
claude-sessions status

# Force start a new session (override active session)
claude-sessions start-now -f

With development setup:

# Start a new session immediately
python -m claude_code_session_manager start-now

# Check current session status
python -m claude_code_session_manager status

# Force start a new session (override active session)
python -m claude_code_session_manager start-now -f

Command Reference

Command	Description	Options
start-now	Creates and activates a new Claude session	-f, --force: Override existing active session
status	Displays current session information and status	None

Example Output

$ claude-sessions start-now
✅ Sesiune activată cu succes!

$ claude-sessions status
📊 Sesiune Claude Pro
├── 📅 Creată: 2024-01-15 14:30:25
├── ⏰ Expiră: 2024-01-15 19:30:25
├── ✅ Status: Activă
└── 🕐 Timp rămas: 4h 23m

Configuration

The application uses environment variables for configuration with sensible defaults:

Variable	Default	Description
SESSION_DURATION_HOURS	5	Session window duration in hours
SESSION_FILE_PATH	"session.json"	Path to session storage file
CLAUDE_TIMEOUT_SECONDS	10	Claude CLI command timeout
CLAUDE_MAX_TURNS	1	Maximum conversation turns
CLAUDE_OUTPUT_FORMAT	"json"	Claude CLI output format

Setting Environment Variables

# Temporary (current session)
export SESSION_DURATION_HOURS=6
export SESSION_FILE_PATH="/path/to/custom/session.json"

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export SESSION_DURATION_HOURS=6' >> ~/.zshrc

Development

Setup Development Environment

# Install development dependencies
pip install -r requirements.txt

# Install pre-commit hooks (if using)
pre-commit install

Code Quality Tools

# Linting
ruff check .

# Code formatting
ruff format .

# Type checking
basedpyright

Testing

# Run all tests
python run_tests.py

# Run with different verbosity levels
python run_tests.py -v 1    # Less verbose
python run_tests.py -q      # Minimal output

# Run specific test module
python run_tests.py -m test_models

Project Structure

claude-code-sessions-manager/
├── src/
│   └── claude_code_session_manager/    # Main package directory
│       ├── __init__.py
│       ├── __main__.py                 # Module entry point (python -m)
│       ├── main.py                     # CLI entry point
│       ├── config/
│       │   ├── __init__.py
│       │   └── settings.py             # Configuration management
│       ├── domain/
│       │   ├── __init__.py
│       │   ├── models.py               # Session model
│       │   └── exceptions.py           # Custom exceptions
│       ├── infrastructure/
│       │   ├── __init__.py
│       │   ├── claude_client.py        # Claude CLI integration
│       │   └── storage.py              # File-based session storage
│       ├── services/
│       │   ├── __init__.py
│       │   └── session_manager.py      # Core business logic
│       └── utils/
│           ├── __init__.py
│           └── formatters.py           # Output formatting utilities
├── tests/                              # Comprehensive test suite
│   ├── __init__.py
│   ├── config/
│   │   ├── __init__.py
│   │   └── test_settings.py
│   ├── domain/
│   │   ├── __init__.py
│   │   ├── test_models.py
│   │   └── test_exceptions.py
│   ├── infrastructure/
│   │   ├── __init__.py
│   │   ├── test_claude_client.py
│   │   └── test_storage.py
│   ├── services/
│   │   ├── __init__.py
│   │   └── test_session_manager.py
│   └── utils/
│       ├── __init__.py
│       └── test_helpers.py
├── pyproject.toml                      # Modern Python packaging configuration
├── requirements.txt                    # Python dependencies
├── run_tests.py                        # Test runner script
├── CLAUDE.md                           # Development instructions
└── README.md                           # This file

How It Works

1. Session Activation: Tests Claude CLI availability and creates a new session
2. Data Persistence: Stores session metadata in JSON format for reliability
3. Status Tracking: Monitors session expiration and provides real-time status
4. CLI Integration: Seamless integration with Claude CLI for actual AI interactions

Session Lifecycle

graph LR
    A[Start Session] --> B[Test Claude CLI]
    B --> C[Create Session]
    C --> D[Store Data]
    D --> E[Active Session]
    E --> F{5 Hours Passed?}
    F -->|No| G[Session Active]
    F -->|Yes| H[Session Expired]
    G --> F
    H --> A

Loading

Troubleshooting

Common Issues

Claude CLI not found:

# Verify Claude CLI installation
which claude
# If not found, install from: https://github.com/anthropics/claude-cli

Permission denied on session file:

# Check file permissions
ls -la session.json
# Fix permissions if needed
chmod 644 session.json

Session not activating:

# Check Claude CLI status
claude --help
# Verify network connectivity
ping anthropic.com

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run tests and linting (python run_tests.py && ruff check .)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Automated Scheduling (macOS)

The application includes LaunchAgent integration for automated session management that runs every 5 minutes.

Installation

# Install LaunchAgent for automated scheduling
./install-scheduler.sh

# Uninstall LaunchAgent
./uninstall-scheduler.sh

Manual Setup

If you prefer manual setup:

1. Copy the template:

   cp com.claude-sessions.scheduler.plist.template com.claude-sessions.scheduler.plist

2. Replace placeholders:

   • {{USER_HOME}}: Your home directory (e.g., /Users/yourusername)
   • {{VENV_PATH}}: Path to your Python virtual environment

3. Install the LaunchAgent:

   cp com.claude-sessions.scheduler.plist ~/Library/LaunchAgents/
   launchctl load ~/Library/LaunchAgents/com.claude-sessions.scheduler.plist

Monitoring

# Check LaunchAgent status
launchctl list | grep claude-sessions

# Monitor logs
tail -f ~/.local/share/claude-sessions/scheduler.out

# View errors
tail -f ~/.local/share/claude-sessions/scheduler.err

macOS Privacy Permissions

Important: When using LaunchAgent automation on macOS, you may encounter permission prompts that prevent the scheduler from running automatically. This happens because Python needs permission to execute the Claude CLI.

Solution: Grant Full Disk Access

1. Open System Settings > Privacy & Security > Full Disk Access
2. Click the + button to add applications
3. Navigate to your Python executable (usually /usr/bin/python3 or your virtual environment's Python)
4. Add Python to the Full Disk Access list
5. Optionally, also add Terminal for additional compatibility

Alternative: Automation Permissions

If Full Disk Access seems too broad, you can try the more specific approach:

1. Open System Settings > Privacy & Security > Automation
2. Look for Python or Terminal in the list
3. Enable permissions for Claude CLI or other relevant applications

Verification

After granting permissions, test the LaunchAgent:

# Manually trigger the LaunchAgent to test
launchctl start com.claude-sessions.scheduler

# Check if it ran successfully
tail ~/.local/share/claude-sessions/scheduler.out

Note: This permission setup is required only once. The LaunchAgent will then run automatically every 5 minutes without further prompts.

Future Enhancements

• 🌐 Cross-platform Support: Windows and Linux compatibility
• 📈 Usage Analytics: Session usage statistics and insights
• 🔔 Notifications: Alert system for session expiration
• 🎯 Smart Scheduling: Intelligent session timing based on usage patterns

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

• 🐛 Bug Reports: Open an issue on GitHub
• 💡 Feature Requests: Create a feature request issue
• 📧 General Questions: Use GitHub Discussions

---

Made with ❤️ for optimizing Claude Pro usage