A command-line tool that analyzes Claude API usage patterns across coding sessions, identifies token waste, suggests prompt optimizations, and provides cost forecasting for different usage scenarios. Integrates with popular coding agents to provide real-time spend visibility and automatic context compression.

Quick Start • Features • Examples • Contributing

What is this?

The Claude Usage Optimizer CLI helps developers monitor and reduce Claude API costs by analyzing token usage from coding agents. It provides real-time visibility into consumption patterns and actionable optimization suggestions.

$ claude-optimizer monitor --agent cursor
🔍 Monitoring Cursor logs...
📊 Session started: 2024-05-20 14:30:00
Token usage: 18,420 tokens | Estimated cost: $0.92
Top prompt type: Code generation (52%)

Problem

Solo developers using Claude-powered coding agents struggle with unpredictable API costs and token waste. They often hit rate limits unexpectedly, can't forecast monthly spend, and don't know which prompts or agent behaviors are driving high costs. Current monitoring is either non-existent or requires complex setup, leaving developers to discover overruns after the fact.

Features

Feature	Description
Agent Integration Monitor	Automatically detects and monitors Claude API usage from popular coding agents by parsing log files and HTTP traffic, providing real-time visibility into token consumption and request patterns.
Context Waste Analyzer	Analyzes prompt patterns to identify unnecessary context repetition, oversized code blocks, and redundant information that drives up token costs without adding value.
Cost Forecasting Engine	Provides accurate monthly and project-based cost predictions using historical usage patterns, seasonal trends, and configurable development scenarios.
Prompt Optimization Recommender	Analyzes prompt effectiveness and suggests specific optimizations to reduce token usage while maintaining or improving code generation quality.
Session-based Tracking	Tracks usage per coding session with agent identification, enabling detailed analysis of specific workflows and time periods.
Real-time Alerts	Sends configurable notifications when approaching budget thresholds or rate limits to prevent unexpected overruns.

Quick Start

1. Clone the repository:
   git clone https://github.com/m2ai-portfolio/claude-usage-optimizer-cli.git
2. Install dependencies:
   cd claude-usage-optimizer-cli && pip install -e .
3. Configure your API key:
   export CLAUDE_API_KEY=your_anthropic_key_here
4. Start monitoring:
   claude-optimizer monitor --agent cursor --log-path ~/.cursor/logs

Examples

Real-time monitoring for Cursor agent

$ claude-optimizer monitor --agent cursor --log-path ~/Library/Application\ Support/Cursor/User/workspaceStorage
🔍 Monitoring Cursor logs...
📊 Session: 2024-05-20 10:15:00 - 11:02:00
Token usage: 42,180 tokens | Cost: $2.11
Requests/min: 8.3 | Avg. tokens/request: 5,082
💡 Tip: Consider enabling context compression for debugging sessions

Context waste analysis for last session

$ claude-optimizer analyze --focus context --session last
📈 Session Analysis: 2024-05-20 10:15:00
⚠️  Context waste: 61% (25,730 tokens wasted)
🔍 Primary waste: Repeated boilerplate imports (38% of waste)
🚀 Optimization: Use relative path references instead of full imports
💰 Estimated savings: $1.29 per session

Monthly cost forecast for heavy development

$ claude-optimizer forecast --period monthly --scenario heavy --budget 50
📊 Monthly Forecast (Heavy Development)
💰 Projected cost: $78.40 (90% CI: $72.10 - $84.70)
📅 Daily average: 2,613 tokens | $0.31/day
⚠️  Budget alert: Projected cost exceeds $50 limit by 57%
💡 Recommendation: Enable context compression to reduce usage by ~35%

File Structure

Claude Usage Optimizer CLI/
├── claude_optimizer/          # Core source code
│   ├── agents/                # Log parsers for coding agents
│   │   ├── cursor_parser.py
│   │   ├── cline_parser.py
│   │   └── generic_parser.py
│   ├── analysis/              # Token analysis and optimization
│   │   ├── context_analyzer.py
│   │   ├── cost_calculator.py
│   │   └── optimizer.py
│   ├── monitoring/            # Real-time usage tracking
│   │   ├── file_monitor.py
│   │   └── session_tracker.py
│   ├── reporting/             # Visualization and export
│   │   ├── visualizer.py
│   │   └── exporter.py
│   ├── storage/               # SQLite data management
│   │   └── database.py
│   └── utils/                 # Helper utilities
│       ├── prompt_classifier.py
│       └── token_counter.py
├── tests/                     # Test suite
│   └── test_*.py
├── assets/                    # Documentation assets
│   └── infographic.png
├── screenshots/               # Example outputs
├── pyproject.toml             # Project configuration
└── README.md

Tech Stack

Technology	Purpose
Python 3.11+	Core language
Click	CLI framework
SQLite	Local usage data storage
Rich	Terminal UI and progress displays
Anthropic SDK	API integration and token counting
Pydantic	Data validation and models
Matplotlib	Usage visualization
Watchdog	File system monitoring
Requests	HTTP monitoring and log parsing
Pytest	Testing framework
JSON	Configuration management

Contributing

Fork the repository, create a feature branch, make changes, run tests, and submit a pull request. Ensure all tests pass before contributing.

License

MIT

Author

Matthew Snow -- M2AI | @m2ai-portfolio