aiusage

Name	aiusage JSON
Version	0.1.0 JSON
	download
home_page	None
Summary	A smart command-line tool for tracking AI credit consumption across billing cycles
upload_time	2025-10-12 18:35:45
maintainer	None
docs_url	None
author	Michael Kennedy
requires_python	>=3.13
license	MIT
keywords	ai credits usage tracking cursor copilot
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # AI Usage 💳

A smart command-line tool for tracking AI credit consumption across billing cycles. Designed for AI-powered development tools like Cursor, GitHub Copilot, and other subscription-based AI services.

## 🎯 Why This Matters

Managing AI credits effectively can save you money and frustration:

- **Avoid overages**: Get warned before you hit pay-as-you-go pricing
- **Optimize usage**: Know when you have credits to spare for big projects
- **Track trends**: See if you're conserving or burning through credits
- **Plan ahead**: Project your usage through the end of the billing cycle

## But my AI already shows percentage used

![](./readme_resources/cursor-progress.webp)

Yes it might! But that's only half the story. At your current rate, will you still have creates to spare at the end of the period? How much? Are you going over? 

If you have a bunch extra, you can switch to a smarter model or tackle a huge upcoming feature / project sooner rather than later. And visa versa if you're going to be over.

This is a simple CLI tool. But I find knowing the answers with clear numbers for those questions very useful.

## ✨ Features

- 📊 **Real-time Usage Analysis**: Compares your credit usage against time elapsed in billing cycle
- 🎨 **Color-Coded Feedback**: Green for conserving, red for warning, instant visual feedback
- 🔮 **Smart Projections**: Predicts remaining credits at renewal based on current usage rate
- 📅 **Flexible Billing Cycles**: Works with any renewal day of the month
- ⚡ **Zero Dependencies**: Pure Python with no external packages required
- 🧮 **Accurate Calculations**: Handles month boundaries and varying cycle lengths
- 🔒 **Privacy First**: No web services, no logins, no data collection—runs entirely offline

## 📸 Example Output

When you're conserving credits (good):
```
💳 Credit Usage Analysis
==================================================
Current Date: 2025-10-12
Billing Cycle: Day 12 of 31
Renewal Day: 1st of the month

🎯 Analysis:
  Credits Used: 25.0%
  Difference: -13.7%
  Status: CONSERVING WELL

🔮 Projection (at current rate):
  Expected usage by renewal: 64.6%
  Expected surplus: 35.4%

✅ Great! You're conserving credits - using 13.7% slower than time
   You'll have ~35.4% credits remaining at renewal.
```

When you're using too fast (warning):
```
💳 Credit Usage Analysis
==================================================
Current Date: 2025-10-12
Billing Cycle: Day 12 of 31
Renewal Day: 1st of the month

🎯 Analysis:
  Credits Used: 75.0%
  Difference: +36.3%
  Status: USING TOO FAST

🔮 Projection (at current rate):
  Expected usage by renewal: 193.8%
  Expected surplus: -93.8%

⚠️  WARNING: You're using credits 36.3% faster than time!
   💥 You'll exceed 100% usage by 93.8% before renewal!
```

## 🚀 Installation

### From PyPI (when published)

```bash
uv pip install aiusage
```

### From Source

```bash
git clone https://github.com/mikeckennedy/aiusage.git
cd aiusage
uv pip install -e .
```

## 📖 Usage

### Basic Usage

```bash
aiusage 15 45  # Renewal on 15th, 45% used
aiusage 25     # Default renewal day (1st), 25% used
```

### Finding Your Current Usage

**For Cursor:**
1. Open Cursor Settings
2. Navigate to your subscription/usage page
3. Look for "Usage this billing period" or similar
4. Use the percentage shown

**For GitHub Copilot:**
- Check your GitHub billing page for usage metrics

## 🔧 How It Works

The tool performs three key calculations:

1. **Time Progress**: Calculates how far through your billing cycle you are
   - Example: Day 18 of 31 = 58.1% through cycle

2. **Usage Ratio**: Compares credit usage to time progress
   - Ratio > 1.0 = Using too fast ⚠️
   - Ratio < 1.0 = Conserving well ✅
   - Ratio = 1.0 = On track 📊

3. **Projection**: Estimates final usage based on current rate
   - Daily rate = Current % ÷ Days elapsed
   - Projected = Daily rate × Total cycle days

## 📋 Requirements

- Python 3.13+ (uses modern type hints)
- No external dependencies
- Works on macOS, Linux, and Windows

## 💡 Use Cases

### Scenario 1: Pre-Project Planning
You're at 30% usage with 40% of your cycle remaining. You have credits to spare—perfect time to tackle that AI-intensive refactoring project!

### Scenario 2: Usage Warning
You're at 80% usage with 50% of your cycle remaining. Time to be more selective with AI requests or risk hitting overages.

### Scenario 3: End-of-Cycle Push
You're at 60% usage with only 5 days left. Use those remaining credits before they reset!

## 🤝 Contributing

Contributions are welcome! Feel free to:
- Report bugs
- Suggest features
- Submit pull requests

## 📄 License

MIT License - feel free to use this tool in your own projects!

## 🙏 Acknowledgments

Built for developers who want to maximize their AI tool subscriptions without breaking the bank.

---

**Pro Tip**: The package installs a `aiusage` command globally:
```bash
# If your renewal day is the 15th of the month, and usage is 45%
aiusage 15 45

# Or use the default renewal day (1st)
aiusage 25
``` 
            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "aiusage",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.13",
    "maintainer_email": null,
    "keywords": "ai, credits, usage, tracking, cursor, copilot",
    "author": "Michael Kennedy",
    "author_email": "Michael Kennedy <mikeckennedy@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/a6/58/06d67a4466264c0c31bd5d7748d8519e0e3c80afa2d9727ba3396793189b/aiusage-0.1.0.tar.gz",
    "platform": null,
    "description": "# AI Usage \ud83d\udcb3\n\nA smart command-line tool for tracking AI credit consumption across billing cycles. Designed for AI-powered development tools like Cursor, GitHub Copilot, and other subscription-based AI services.\n\n## \ud83c\udfaf Why This Matters\n\nManaging AI credits effectively can save you money and frustration:\n\n- **Avoid overages**: Get warned before you hit pay-as-you-go pricing\n- **Optimize usage**: Know when you have credits to spare for big projects\n- **Track trends**: See if you're conserving or burning through credits\n- **Plan ahead**: Project your usage through the end of the billing cycle\n\n## But my AI already shows percentage used\n\n![](./readme_resources/cursor-progress.webp)\n\nYes it might! But that's only half the story. At your current rate, will you still have creates to spare at the end of the period? How much? Are you going over? \n\nIf you have a bunch extra, you can switch to a smarter model or tackle a huge upcoming feature / project sooner rather than later. And visa versa if you're going to be over.\n\nThis is a simple CLI tool. But I find knowing the answers with clear numbers for those questions very useful.\n\n## \u2728 Features\n\n- \ud83d\udcca **Real-time Usage Analysis**: Compares your credit usage against time elapsed in billing cycle\n- \ud83c\udfa8 **Color-Coded Feedback**: Green for conserving, red for warning, instant visual feedback\n- \ud83d\udd2e **Smart Projections**: Predicts remaining credits at renewal based on current usage rate\n- \ud83d\udcc5 **Flexible Billing Cycles**: Works with any renewal day of the month\n- \u26a1 **Zero Dependencies**: Pure Python with no external packages required\n- \ud83e\uddee **Accurate Calculations**: Handles month boundaries and varying cycle lengths\n- \ud83d\udd12 **Privacy First**: No web services, no logins, no data collection\u2014runs entirely offline\n\n## \ud83d\udcf8 Example Output\n\nWhen you're conserving credits (good):\n```\n\ud83d\udcb3 Credit Usage Analysis\n==================================================\nCurrent Date: 2025-10-12\nBilling Cycle: Day 12 of 31\nRenewal Day: 1st of the month\n\n\ud83c\udfaf Analysis:\n  Credits Used: 25.0%\n  Difference: -13.7%\n  Status: CONSERVING WELL\n\n\ud83d\udd2e Projection (at current rate):\n  Expected usage by renewal: 64.6%\n  Expected surplus: 35.4%\n\n\u2705 Great! You're conserving credits - using 13.7% slower than time\n   You'll have ~35.4% credits remaining at renewal.\n```\n\nWhen you're using too fast (warning):\n```\n\ud83d\udcb3 Credit Usage Analysis\n==================================================\nCurrent Date: 2025-10-12\nBilling Cycle: Day 12 of 31\nRenewal Day: 1st of the month\n\n\ud83c\udfaf Analysis:\n  Credits Used: 75.0%\n  Difference: +36.3%\n  Status: USING TOO FAST\n\n\ud83d\udd2e Projection (at current rate):\n  Expected usage by renewal: 193.8%\n  Expected surplus: -93.8%\n\n\u26a0\ufe0f  WARNING: You're using credits 36.3% faster than time!\n   \ud83d\udca5 You'll exceed 100% usage by 93.8% before renewal!\n```\n\n## \ud83d\ude80 Installation\n\n### From PyPI (when published)\n\n```bash\nuv pip install aiusage\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/mikeckennedy/aiusage.git\ncd aiusage\nuv pip install -e .\n```\n\n## \ud83d\udcd6 Usage\n\n### Basic Usage\n\n```bash\naiusage 15 45  # Renewal on 15th, 45% used\naiusage 25     # Default renewal day (1st), 25% used\n```\n\n### Finding Your Current Usage\n\n**For Cursor:**\n1. Open Cursor Settings\n2. Navigate to your subscription/usage page\n3. Look for \"Usage this billing period\" or similar\n4. Use the percentage shown\n\n**For GitHub Copilot:**\n- Check your GitHub billing page for usage metrics\n\n## \ud83d\udd27 How It Works\n\nThe tool performs three key calculations:\n\n1. **Time Progress**: Calculates how far through your billing cycle you are\n   - Example: Day 18 of 31 = 58.1% through cycle\n\n2. **Usage Ratio**: Compares credit usage to time progress\n   - Ratio > 1.0 = Using too fast \u26a0\ufe0f\n   - Ratio < 1.0 = Conserving well \u2705\n   - Ratio = 1.0 = On track \ud83d\udcca\n\n3. **Projection**: Estimates final usage based on current rate\n   - Daily rate = Current % \u00f7 Days elapsed\n   - Projected = Daily rate \u00d7 Total cycle days\n\n## \ud83d\udccb Requirements\n\n- Python 3.13+ (uses modern type hints)\n- No external dependencies\n- Works on macOS, Linux, and Windows\n\n## \ud83d\udca1 Use Cases\n\n### Scenario 1: Pre-Project Planning\nYou're at 30% usage with 40% of your cycle remaining. You have credits to spare\u2014perfect time to tackle that AI-intensive refactoring project!\n\n### Scenario 2: Usage Warning\nYou're at 80% usage with 50% of your cycle remaining. Time to be more selective with AI requests or risk hitting overages.\n\n### Scenario 3: End-of-Cycle Push\nYou're at 60% usage with only 5 days left. Use those remaining credits before they reset!\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Feel free to:\n- Report bugs\n- Suggest features\n- Submit pull requests\n\n## \ud83d\udcc4 License\n\nMIT License - feel free to use this tool in your own projects!\n\n## \ud83d\ude4f Acknowledgments\n\nBuilt for developers who want to maximize their AI tool subscriptions without breaking the bank.\n\n---\n\n**Pro Tip**: The package installs a `aiusage` command globally:\n```bash\n# If your renewal day is the 15th of the month, and usage is 45%\naiusage 15 45\n\n# Or use the default renewal day (1st)\naiusage 25\n``` ",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A smart command-line tool for tracking AI credit consumption across billing cycles",
    "version": "0.1.0",
    "project_urls": {
        "Homepage": "https://github.com/mikeckennedy/aiusage",
        "Repository": "https://github.com/mikeckennedy/aiusage"
    },
    "split_keywords": [
        "ai",
        " credits",
        " usage",
        " tracking",
        " cursor",
        " copilot"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "2c7e5f1eb59cb0daecf04cb7b9c45197354b9c34e2c7d5fca43f64f058879629",
                "md5": "9d0ed783f3bbbe4075df3598c1525613",
                "sha256": "6cac6f8b9de2186fa510bb7abb0c0add8f91db1d1ffaaad272b0417f195f559e"
            },
            "downloads": -1,
            "filename": "aiusage-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "9d0ed783f3bbbe4075df3598c1525613",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.13",
            "size": 9963,
            "upload_time": "2025-10-12T18:35:44",
            "upload_time_iso_8601": "2025-10-12T18:35:44.329505Z",
            "url": "https://files.pythonhosted.org/packages/2c/7e/5f1eb59cb0daecf04cb7b9c45197354b9c34e2c7d5fca43f64f058879629/aiusage-0.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "a65806d67a4466264c0c31bd5d7748d8519e0e3c80afa2d9727ba3396793189b",
                "md5": "ffff95f9ecc1889fc1a156126e3c25f5",
                "sha256": "93eb079549f2ecc63b28d3b6a927eafe228d5e43ff984f57bf94ed2e147ee01b"
            },
            "downloads": -1,
            "filename": "aiusage-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "ffff95f9ecc1889fc1a156126e3c25f5",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.13",
            "size": 8122,
            "upload_time": "2025-10-12T18:35:45",
            "upload_time_iso_8601": "2025-10-12T18:35:45.647778Z",
            "url": "https://files.pythonhosted.org/packages/a6/58/06d67a4466264c0c31bd5d7748d8519e0e3c80afa2d9727ba3396793189b/aiusage-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-10-12 18:35:45",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "mikeckennedy",
    "github_project": "aiusage",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "aiusage"
}