claudesavvy 2.0.0__tar.gz

claudesavvy-2.0.0/CHANGELOG.md

@@ -0,0 +1,163 @@
+# Changelog
+
+All notable changes to ClaudeSavvy will be documented in this file.
+
+## [2.0.0] - 2025-12-29
+
+### Changed
+- **BREAKING**: Major rebrand from "Claude Monitor" to "ClaudeSavvy"
+- **BREAKING**: Package name changed from `claude-monitor` to `claudesavvy` on PyPI
+- **BREAKING**: Command changed from `claude-monitor` to `claudesavvy`
+- Repository name remains as `claude_monitor` for historical reasons
+- Updated all documentation to reflect new brand name
+- Refreshed README with new branding, tagline, and visual identity
+- Updated package description to emphasize "dashboard" functionality
+
+### Fixed
+- Reorganized dashboard page layout for better navigation (see #18)
+- Updated all references in documentation and configuration files
+
+### Migration Guide
+
+If you were using Claude Monitor v1.x:
+
+**Before (v1.x):**
+```bash
+pip install claude-monitor
+claude-monitor
+```
+
+**Now (v2.0.0):**
+```bash
+pip install claudesavvy
+claudesavvy
+```
+
+To upgrade from v1.x to v2.0.0:
+```bash
+pip uninstall claude-monitor
+pip install claudesavvy
+```
+
+Note: Your data files remain unchanged. Only the package name and command have changed.
+
+## [1.0.1] - 2025-12-27
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] - 2025-12-27
+
+### Added
+- Automated PyPI publishing via GitHub Actions
+- Cross-platform binary builds (macOS, Linux, Windows) using PyInstaller
+- Pre-built executable distribution through GitHub Releases
+- Complete release infrastructure and documentation
+
+### Changed
+- Installation now supports three methods: PyPI, pre-built binaries, and from source
+- Updated README with installation instructions for all distribution methods
+
+### Fixed
+- Security: Fixed 8 instances of empty except blocks with specific exception handling
+- Cross-platform compatibility in PyInstaller spec file
+- Improved dependency handling for web components (Flask templates and static assets)
+
+## [1.0.0] - 2025-12-20
+
+### Added
+- Web-based dashboard interface with Flask
+- Multiple dedicated metric pages:
+  - Dashboard: Overview of all metrics
+  - Tokens: Detailed token usage and cost breakdown
+  - Projects: Per-project analytics
+  - Files: File operation statistics
+  - Integrations: MCP server usage
+  - Features: Tool usage and sub-agent statistics
+- Data export functionality (CSV and JSON formats)
+- Health check endpoint for monitoring
+- HTMX-powered dynamic content updates
+- Time period filtering (today, week, month, all-time)
+- Responsive web UI with modern styling
+- Production-ready documentation (LICENSE, CONTRIBUTING, CHANGELOG)
+
+### Changed
+- **BREAKING**: Removed CLI dashboard interface entirely
+- **BREAKING**: `claude-monitor` command now launches web server directly (no subcommand required)
+- Updated entry point from dual-mode (CLI/web) to web-only
+- Standardized dependency versions across all configuration files
+- Updated project description to "Web-based usage monitoring tool for Claude Code"
+- Bumped version to 1.0.0 to reflect major interface change
+
+### Removed
+- **BREAKING**: CLI interactive menu and dashboard views
+- **BREAKING**: CLI-specific options: `--today`, `--week`, `--month`, `--quarter`, `--year`, `--focus`, `--interactive`
+- Entire `display/` module (dashboard, menu, tables, cards, formatter)
+- CLI time filtering and project filtering flags
+
+### Fixed
+- Added Flask>=3.0.0 and Jinja2>=3.1.0 to setup.py (previously missing)
+- Standardized Flask version to 3.0.0 across setup.py, pyproject.toml, and requirements.txt
+- Fixed installation via `pip install .` which previously failed to install web dependencies
+
+### Migration Guide
+
+If you were using the CLI dashboard (v0.1.0):
+
+**Before (v0.1.0):**
+```bash
+claude-monitor                    # CLI dashboard
+claude-monitor --week             # CLI with time filter
+claude-monitor web                # Web server
+```
+
+**Now (v1.0.0):**
+```bash
+claude-monitor                    # Web server (default)
+claude-monitor --port 8080        # Web server on custom port
+claude-monitor --debug            # Web server in debug mode
+```
+
+To continue using the CLI dashboard, stay on version 0.1.0:
+```bash
+git checkout v0.1.0
+pip install -e .
+```
+
+## [0.1.0] - 2025-12-19
+
+### Added
+- Initial release with CLI dashboard interface
+- Interactive menu with logo and navigation
+- Usage metrics tracking (sessions, commands, projects)
+- Token usage and cost calculations
+- Prompt cache efficiency monitoring
+- Project breakdown analytics
+- File modification tracking
+- MCP integration statistics
+- Model usage breakdown
+- Time-based filtering (today, week, month, quarter, year, custom dates)
+- Rich terminal UI with tables and color-coded output
+- Support for custom Claude data directory
+- Web interface as optional subcommand
+
+### Data Sources
+- Reads from `~/.claude/` directory
+- Parses history.jsonl for command history
+- Analyzes session files for token usage
+- Processes debug logs for MCP activity
+- Tracks file editing history
+
+### Requirements
+- Python 3.9+
+- click>=8.1.0
+- rich>=13.0.0
+- python-dateutil>=2.8.0
+- Flask>=2.3.0 (for web mode)
+
+---
+
+## Version History
+
+- **1.0.0** (2025-12-20): Web-only release with production polish
+- **0.1.0** (2025-12-19): Initial release with dual CLI/web interface

claudesavvy-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,306 @@
+# Contributing to ClaudeSavvy
+
+Thank you for your interest in contributing to ClaudeSavvy! This document provides guidelines and instructions for contributing to the project.
+
+## Welcome
+
+We welcome contributions of all kinds:
+- Bug fixes
+- Feature enhancements
+- Documentation improvements
+- Performance optimizations
+- Code quality improvements
+
+## Code of Conduct
+
+Be respectful and constructive in all interactions. We're all here to build something useful together.
+
+## Getting Started
+
+### 1. Clone and Set Up
+
+```bash
+# Clone the repository
+git clone https://github.com/allannapier/claude_monitor.git
+cd claude_monitor
+
+# Create a virtual environment (recommended)
+python3 -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install in development mode
+pip install -e .
+
+# Or install with requirements
+pip install -r requirements.txt
+```
+
+### 2. Run Locally
+
+```bash
+# Start the web server
+claudesavvy
+
+# Or run directly
+python3 -m src.claudesavvy.cli
+
+# Enable debug mode for development
+claudesavvy --debug
+```
+
+The web interface will be available at http://localhost:5000
+
+## Development Workflow
+
+### Branch Naming
+
+- `feature/description` - New features
+- `fix/description` - Bug fixes
+- `docs/description` - Documentation changes
+- `refactor/description` - Code refactoring
+
+### Commit Messages
+
+Write clear, descriptive commit messages:
+
+```
+Add export functionality for CSV format
+
+- Implement CSV export route
+- Add download headers
+- Include all dashboard metrics
+```
+
+### Pull Request Process
+
+1. **Create a branch** from `main`:
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+2. **Make your changes** with clear, focused commits
+
+3. **Test your changes**:
+   - Verify the web server starts successfully
+   - Test all affected routes and functionality
+   - Check for Python errors and warnings
+
+4. **Update documentation** if needed:
+   - Update README.md for user-facing changes
+   - Add docstrings for new functions/classes
+   - Update CHANGELOG.md with your changes
+
+5. **Submit a pull request**:
+   - Describe what changes you made and why
+   - Link to any related issues
+   - Include screenshots for UI changes
+
+## Project Structure
+
+Understanding the architecture will help you contribute effectively:
+
+```
+src/claudesavvy/
+├── cli.py                 # Entry point - launches web server
+├── parsers/              # Data parsers (read Claude Code files)
+│   ├── history.py        # Command history parser
+│   ├── sessions.py       # Session and token data parser
+│   ├── debug.py          # MCP server logs parser
+│   ├── files.py          # File editing history parser
+│   ├── tools.py          # Tool usage parser
+│   └── skills.py         # Skills and config parser
+├── analyzers/            # Data analysis layer
+│   ├── usage.py          # Usage statistics analyzer
+│   ├── tokens.py         # Token usage and cost analyzer
+│   ├── integrations.py   # MCP integration analyzer
+│   └── features.py       # Features analyzer
+├── web/                  # Flask web application
+│   ├── app.py            # Flask app factory
+│   ├── routes/           # Route handlers
+│   │   └── dashboard.py  # Main dashboard routes
+│   ├── services/         # Business logic
+│   │   └── dashboard_service.py
+│   ├── templates/        # Jinja2 HTML templates
+│   │   ├── pages/        # Full page templates
+│   │   ├── partials/     # Reusable components
+│   │   └── components/   # UI components
+│   └── static/           # CSS, JS, images
+└── utils/                # Shared utilities
+    ├── paths.py          # Path management
+    └── time_filter.py    # Time-based filtering
+```
+
+## Adding Features
+
+### Adding a New Metric
+
+1. **Create/modify a parser** in `parsers/` to extract the data
+2. **Create/modify an analyzer** in `analyzers/` to process the data
+3. **Add to web service** in `web/services/dashboard_service.py`
+4. **Create a route** in `web/routes/dashboard.py`
+5. **Create a template** in `web/templates/pages/`
+6. **Update navigation** in `web/templates/base.html`
+
+### Adding a New Parser
+
+Parsers read Claude Code data files:
+
+```python
+from pathlib import Path
+from typing import List
+
+class MyParser:
+    def __init__(self, file_path: Path):
+        self.file_path = file_path
+
+    def parse(self) -> List[dict]:
+        """Parse the file and return structured data."""
+        # Your parsing logic here
+        pass
+```
+
+### Adding a New Analyzer
+
+Analyzers process parsed data:
+
+```python
+from .parsers.my_parser import MyParser
+from .utils.time_filter import TimeFilter
+
+class MyAnalyzer:
+    def __init__(self, parser: MyParser, time_filter: TimeFilter):
+        self.parser = parser
+        self.time_filter = time_filter
+
+    def get_summary(self):
+        """Analyze data and return summary."""
+        # Your analysis logic here
+        pass
+```
+
+### Adding a New Web Page
+
+1. **Add route** in `web/routes/dashboard.py`:
+   ```python
+   @dashboard_bp.route('/my-page')
+   def my_page():
+       data = dashboard_service.get_my_data()
+       return render_template('pages/my_page.html', data=data)
+   ```
+
+2. **Create template** in `web/templates/pages/my_page.html`:
+   ```html
+   {% extends "base.html" %}
+   {% block content %}
+   <!-- Your page content -->
+   {% endblock %}
+   ```
+
+## Testing
+
+Currently, testing is manual. When making changes:
+
+### Manual Testing Checklist
+
+- [ ] Web server starts without errors
+- [ ] All existing pages load correctly
+- [ ] New functionality works as expected
+- [ ] No Python exceptions in console
+- [ ] Data displays correctly with real Claude data
+- [ ] Export functionality works (if modified)
+- [ ] Browser console has no errors
+- [ ] Responsive design works (if UI changes)
+
+### Test in Multiple Scenarios
+
+- Test with minimal Claude usage data
+- Test with extensive Claude usage data
+- Test with missing/incomplete data files
+- Test edge cases (no sessions, no projects, etc.)
+
+## Style Guide
+
+### Python Style
+
+- Follow PEP 8 conventions
+- Use type hints where helpful:
+  ```python
+  def calculate_cost(tokens: int) -> float:
+      return tokens / 1_000_000 * 3.0
+  ```
+- Write descriptive variable names
+- Add docstrings for public functions:
+  ```python
+  def get_summary(self) -> dict:
+      """
+      Get usage summary statistics.
+
+      Returns:
+          dict: Summary statistics including sessions, commands, and projects
+      """
+  ```
+
+### HTML/Jinja2 Style
+
+- Use semantic HTML elements
+- Keep templates DRY (Don't Repeat Yourself)
+- Use partials for reusable components
+- Include helpful comments in complex templates
+
+### Code Organization
+
+- Keep functions focused and single-purpose
+- Avoid deep nesting (max 3-4 levels)
+- Extract complex logic into helper functions
+- Group related functionality together
+
+## Submitting Pull Requests
+
+### Before Submitting
+
+- [ ] Code follows project style guidelines
+- [ ] All manual tests pass
+- [ ] Documentation is updated
+- [ ] Commit messages are clear
+- [ ] No commented-out code or debug statements
+- [ ] No secrets or personal data in code
+
+### PR Description Template
+
+```markdown
+## Description
+Brief description of what this PR does
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Refactoring
+- [ ] Performance improvement
+
+## Changes Made
+- Bullet point list of changes
+
+## Testing Done
+- How you tested these changes
+
+## Screenshots (if UI changes)
+[Add screenshots here]
+
+## Related Issues
+Closes #123
+```
+
+## Questions or Issues?
+
+- Open an issue on GitHub for bugs or feature requests
+- Start a discussion for questions or ideas
+- Check existing issues before creating new ones
+
+## License
+
+By contributing to ClaudeSavvy, you agree that your contributions will be licensed under the MIT License.
+
+---
+
+Thank you for contributing to ClaudeSavvy! 🚀

claudesavvy-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Allan Napier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claudesavvy-2.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include requirements.txt
+recursive-include src/claudesavvy/web/templates *.html
+recursive-include src/claudesavvy/web/static *