'''

Claude Code Token Optimizer Skill

A production-ready Python package and command-line tool to optimize your Claude API token usage when generating code. This skill helps you save 50-80% on token costs by intelligently routing tasks to the most cost-effective model (Sonnet for simple tasks, Opus for complex ones).

Features

• Intelligent Model Routing: Analyzes task complexity and recommends the best model (Sonnet vs. Opus).
• Pre-Execution Cost Estimation: Calculates token usage and cost before you make an API call.
• Automatic Quality Validation: Checks generated code for completeness, quality, and style issues.
• Team-wide Usage Tracking: Logs all API calls to a local JSON file for easy monitoring and reporting.
• Command-Line Interface: Easy-to-use CLI for analyzing, estimating, and validating.
• Shareable & Installable: Packaged as a proper Python skill that can be installed via pip.

Why Use This?

Claude Opus is powerful but expensive. For many coding tasks (formatting, simple functions, bug fixes), Claude Sonnet is 80% cheaper and just as effective. This skill automates the decision-making process, ensuring you always use the right tool for the job and never overspend on tokens.

Cost Savings Example

Scenario	All Opus	80/20 Sonnet/Opus Mix	Savings
100 Tasks/Month	~$3.00	~$1.38	54%
Team of 5 (Annual)	~$1,800	~$828	$972/year

Installation

# Clone the repository
git clone https://github.com/Theesamkos/claude-code-token-optimizer-skill.git
cd claude-code-token-optimizer-skill

# Install the package
pip install .

Configuration

Before using the tool, set your Claude API key as an environment variable:

export ANTHROPIC_API_KEY="your-claude-api-key"

Usage

The skill provides a command-line tool, optimize-claude-code, with three main commands:

1. Analyze Task Complexity

Before writing your prompt, get a recommendation on which model to use.

optimize-claude-code analyze "YOUR_PROMPT_HERE"

Example:

optimize-claude-code analyze "refactor this python function to be more readable"

Output:

{
  "complexity_score": 20,
  "complexity_level": "moderate",
  "recommended_model": "claude-3-5-sonnet-20241022",
  "reasoning": "Moderate task - Sonnet recommended, validate if needed",
  "should_validate": true,
  "estimated_cost_reduction": "60%"
}

2. Estimate Token Cost

Get an estimate of the token usage and cost before you run the prompt.

optimize-claude-code estimate "YOUR_PROMPT_HERE"

Example:

optimize-claude-code estimate "create a react component for a login form"

Output:

{
  "model": "claude-3-5-sonnet-20241022",
  "input_tokens": 12,
  "estimated_output_tokens": 30,
  "total_estimated_tokens": 42,
  "estimated_cost_usd": 0.0005,
  "pricing_per_1m_input": 3.0,
  "pricing_per_1m_output": 15.0
}

3. Validate Generated Code

After Claude generates code, check its quality.

optimize-claude-code validate "YOUR_GENERATED_CODE_HERE"

Example:

optimize-claude-code validate "def my_func(a,b) return a+b"

Output:

{
  "overall_score": 70,
  "quality_level": "acceptable",
  "completeness": {
    "is_complete": false,
    "completeness_score": 80,
    "issues": [
      "Possible incomplete function definition"
    ]
  },
  "quality_issues": [
    "No documentation or comments found"
  ],
  "style_issues": [],
  "should_regenerate": false,
  "regeneration_reason": "No regeneration needed"
}

Usage Tracking

All token usage can be logged to a local claude_usage.json file. The UsageTracker class can be used programmatically to log usage and generate reports.

from claude_code_token_optimizer import UsageTracker

# Initialize the tracker
tracker = UsageTracker()

# Log a usage entry
tracker.log_usage(
    model="claude-3-5-sonnet-20241022",
    input_tokens=150,
    output_tokens=1200,
    project="collab-board",
    task_type="feature-development"
)

# Get a summary report
summary = tracker.get_usage_summary()
print(summary)

Contributing

Contributions are welcome! Please feel free to submit a pull request or open an issue.

License

This project is licensed under the MIT License. See the LICENSE file for details. '''