claudemon 0.1.0__tar.gz

claudemon-0.1.0/.gitignore

@@ -0,0 +1,143 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# uv
+# Note: uv.lock should be committed to ensure reproducible builds
+
+# User skills directory (skills created with sutras new)
+.claude/
+
+# Project
+plan.md
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

claudemon-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Kumar Anirudha
+
+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.

claudemon-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: claudemon
+Version: 0.1.0
+Summary: Claude Usage Monitor TUI - monitor your Claude usage in real-time
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: term-piechart>=0.1.0
+Requires-Dist: textual>=1.0.0
+Description-Content-Type: text/markdown
+
+# claudemon
+
+Claude Usage Monitor TUI - monitor your Claude Pro/Max plan quota in real-time.
+
+[![PyPI - Version](https://img.shields.io/pypi/v/claudemon)](https://pypi.org/project/claudemon/)
+[![PyPI Downloads](https://static.pepy.tech/badge/claudemon/month)](https://pypi.org/project/claudemon/)
+![PyPI - Status](https://img.shields.io/pypi/status/claudemon)
+[![Open Source](https://img.shields.io/badge/open-source-brightgreen)](https://github.com/anistark/claudemon)
+![maintenance-status](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Install
+
+Requires Python 3.14+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv sync
+```
+
+## Setup
+
+```sh
+# Full setup: OAuth token + optional Admin API key
+uv run claudemon setup
+
+# Admin API key only
+uv run claudemon setup --api
+```
+
+## Usage
+
+```sh
+# Launch the TUI dashboard
+uv run claudemon
+
+# Launch in API monitoring mode
+uv run claudemon --mode api
+```
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `q` | Quit |
+| `r` | Force refresh |
+| `m` | Toggle API mode |
+| `?` | Show help |

claudemon-0.1.0/README.md

@@ -0,0 +1,47 @@
+# claudemon
+
+Claude Usage Monitor TUI - monitor your Claude Pro/Max plan quota in real-time.
+
+[![PyPI - Version](https://img.shields.io/pypi/v/claudemon)](https://pypi.org/project/claudemon/)
+[![PyPI Downloads](https://static.pepy.tech/badge/claudemon/month)](https://pypi.org/project/claudemon/)
+![PyPI - Status](https://img.shields.io/pypi/status/claudemon)
+[![Open Source](https://img.shields.io/badge/open-source-brightgreen)](https://github.com/anistark/claudemon)
+![maintenance-status](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Install
+
+Requires Python 3.14+ and [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv sync
+```
+
+## Setup
+
+```sh
+# Full setup: OAuth token + optional Admin API key
+uv run claudemon setup
+
+# Admin API key only
+uv run claudemon setup --api
+```
+
+## Usage
+
+```sh
+# Launch the TUI dashboard
+uv run claudemon
+
+# Launch in API monitoring mode
+uv run claudemon --mode api
+```
+
+### Keybindings
+
+| Key | Action |
+|-----|--------|
+| `q` | Quit |
+| `r` | Force refresh |
+| `m` | Toggle API mode |
+| `?` | Show help |

claudemon-0.1.0/justfile

@@ -0,0 +1,44 @@
+# Claudemon - Development Commands
+# https://github.com/casey/just
+
+# Default recipe to display help
+default:
+    @just --list
+
+# Format code with ruff
+format:
+    uv run ruff format src/claudemon/
+
+# Lint code with ruff
+lint:
+    uv run ruff check src/claudemon/
+
+# Fix linting issues automatically
+fix:
+    uv run ruff check --fix src/claudemon/
+
+# Type check with ty
+check:
+    uv run ty check src/claudemon/
+
+# Run all quality checks (format, lint, type check)
+qa: format lint check
+
+# Run tests
+test:
+    uv run python -m pytest
+
+# Build distribution packages
+build:
+    uv build
+
+# Clean build artifacts
+clean:
+    rm -rf dist/ build/ *.egg-info
+    find . -type d -name __pycache__ -exec rm -rf {} +
+    find . -type f -name "*.pyc" -delete
+
+# Publish to PyPI (requires credentials in ~/.pypirc)
+publish: clean build
+    @echo "Publishing to PyPI..."
+    uv publish --token "$(grep -A2 '\[pypi\]' ~/.pypirc | grep password | cut -d'=' -f2- | xargs)"

claudemon-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "claudemon"
+version = "0.1.0"
+description = "Claude Usage Monitor TUI - monitor your Claude usage in real-time"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.14"
+dependencies = [
+    "textual>=1.0.0",
+    "httpx>=0.28.0",
+    "term-piechart>=0.1.0",
+]
+
+[project.scripts]
+claudemon = "claudemon.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/claudemon"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "ruff>=0.15.0",
+    "ty>=0.0.15",
+]

claudemon-0.1.0/src/claudemon/__init__.py

@@ -0,0 +1,3 @@
+"""Claudemon — Claude Usage Monitor TUI."""
+
+__version__ = "0.1.0"

claudemon-0.1.0/src/claudemon/__main__.py

@@ -0,0 +1,65 @@
+"""CLI entry point for claudemon."""
+
+import sys
+
+
+def main() -> None:
+    args = sys.argv[1:]
+
+    if args and args[0] == "setup":
+        _run_setup(args[1:])
+        return
+
+    mode = "quota"
+    if "--mode" in args:
+        idx = args.index("--mode")
+        if idx + 1 < len(args):
+            mode = args[idx + 1]
+
+    if "--help" in args or "-h" in args:
+        _print_help()
+        return
+
+    if "--version" in args:
+        from . import __version__
+
+        print(f"claudemon {__version__}")
+        return
+
+    from .app import ClaudemonApp
+
+    app = ClaudemonApp(mode=mode)
+    app.run()
+
+
+def _run_setup(args: list[str]) -> None:
+    api_only = "--api" in args
+    from .auth import interactive_setup
+
+    interactive_setup(api_only=api_only)
+
+
+def _print_help() -> None:
+    print(
+        """claudemon — Claude Usage Monitor TUI
+
+Usage:
+  claudemon              Launch the TUI dashboard
+  claudemon setup        Interactive OAuth + API key setup
+  claudemon setup --api  Configure Admin API key only
+  claudemon --mode api   Launch in API monitoring mode
+
+Options:
+  --help, -h       Show this help message
+  --version        Show version
+
+Keybindings (in TUI):
+  q    Quit
+  r    Force refresh
+  m    Toggle API mode
+  ?    Show help"""
+    )
+
+
+if __name__ == "__main__":
+    main()

claudemon-0.1.0/src/claudemon/api.py

@@ -0,0 +1,153 @@
+"""API clients for Claude quota and admin usage endpoints."""
+
+from datetime import datetime
+
+import httpx
+
+from .models import ApiUsageData, ModelQuota, QuotaData, TokenData
+
+OAUTH_USAGE_URL = "https://api.anthropic.com/api/oauth/usage"
+ADMIN_MESSAGES_URL = "https://api.anthropic.com/v1/organizations/usage_report/messages"
+ADMIN_COSTS_URL = "https://api.anthropic.com/v1/organizations/cost_report"
+
+
+class QuotaFetchError(Exception):
+    pass
+
+
+class AuthenticationError(QuotaFetchError):
+    pass
+
+
+async def fetch_quota(oauth_token: str) -> QuotaData:
+    """Fetch quota usage from the OAuth usage endpoint."""
+    headers = {
+        "Authorization": f"Bearer {oauth_token}",
+        "Content-Type": "application/json",
+    }
+
+    async with httpx.AsyncClient(timeout=15.0) as client:
+        try:
+            resp = await client.get(OAUTH_USAGE_URL, headers=headers)
+        except httpx.RequestError as e:
+            raise QuotaFetchError(f"Network error: {e}") from e
+
+        if resp.status_code == 401:
+            raise AuthenticationError(
+                "OAuth token is invalid or expired. Run 'claudemon setup' to re-authenticate."
+            )
+        if resp.status_code == 403:
+            raise AuthenticationError(
+                "Access denied. Your token may lack the required permissions."
+            )
+        if resp.status_code != 200:
+            raise QuotaFetchError(
+                f"API returned status {resp.status_code}: {resp.text}"
+            )
+
+        data = resp.json()
+
+    return _parse_quota_response(data)
+
+
+def _parse_quota_response(data: dict) -> QuotaData:
+    """Parse the OAuth usage API response into QuotaData."""
+    quota = QuotaData()
+
+    # Parse 5-hour window
+    five_hour = data.get("five_hour", data.get("fiveHour", {}))
+    if five_hour:
+        quota.five_hour_usage_pct = (
+            five_hour.get("utilization", five_hour.get("usage_pct", 0.0)) * 100
+        )
+        reset_at = five_hour.get("reset_at", five_hour.get("resetAt"))
+        if reset_at:
+            quota.five_hour_reset_time = _parse_iso_time(reset_at)
+
+    # Parse 7-day window
+    seven_day = data.get("seven_day", data.get("sevenDay", {}))
+    if seven_day:
+        quota.seven_day_usage_pct = (
+            seven_day.get("utilization", seven_day.get("usage_pct", 0.0)) * 100
+        )
+        reset_at = seven_day.get("reset_at", seven_day.get("resetAt"))
+        if reset_at:
+            quota.seven_day_reset_time = _parse_iso_time(reset_at)
+
+    # Parse model-specific quotas
+    models = data.get("models", data.get("model_quotas", []))
+    for m in models:
+        name = m.get("model", m.get("name", "unknown"))
+        usage = m.get("utilization", m.get("usage_pct", 0.0)) * 100
+        quota.model_quotas.append(ModelQuota(model_name=name, usage_pct=usage))
+
+    # Plan type
+    quota.plan_type = data.get("plan_type", data.get("planType", "pro"))
+
+    return quota
+
+
+def _parse_iso_time(time_str: str) -> datetime:
+    """Parse an ISO 8601 timestamp."""
+    time_str = time_str.replace("Z", "+00:00")
+    return datetime.fromisoformat(time_str)
+
+
+async def fetch_api_usage(admin_api_key: str) -> ApiUsageData:
+    """Fetch usage from the Admin API endpoints."""
+    headers = {
+        "x-api-key": admin_api_key,
+        "Content-Type": "application/json",
+    }
+
+    usage = ApiUsageData()
+
+    async with httpx.AsyncClient(timeout=15.0) as client:
+        # Fetch token usage
+        try:
+            resp = await client.get(ADMIN_MESSAGES_URL, headers=headers)
+            if resp.status_code == 200:
+                msg_data = resp.json()
+                usage.token_counts = _parse_token_usage(msg_data)
+            elif resp.status_code in (401, 403):
+                raise AuthenticationError(
+                    "Admin API key is invalid. Run 'claudemon setup --api' to reconfigure."
+                )
+        except httpx.RequestError as e:
+            raise QuotaFetchError(f"Network error fetching token usage: {e}") from e
+
+        # Fetch costs
+        try:
+            resp = await client.get(ADMIN_COSTS_URL, headers=headers)
+            if resp.status_code == 200:
+                cost_data = resp.json()
+                usage.costs_usd = _parse_costs(cost_data)
+        except httpx.RequestError:
+            pass  # Costs are optional
+
+    return usage
+
+
+def _parse_token_usage(data: dict) -> TokenData:
+    """Parse token usage from admin API response."""
+    tokens = TokenData()
+    items = data.get("data", data.get("messages", []))
+    for item in items:
+        tokens.input_tokens += item.get("input_tokens", 0)
+        tokens.output_tokens += item.get("output_tokens", 0)
+        tokens.cache_read += item.get(
+            "cache_read_input_tokens", item.get("cache_read", 0)
+        )
+        tokens.cache_write += item.get(
+            "cache_creation_input_tokens", item.get("cache_write", 0)
+        )
+    return tokens
+
+
+def _parse_costs(data: dict) -> float:
+    """Parse cost data from admin API response."""
+    items = data.get("data", data.get("costs", []))
+    total = 0.0
+    for item in items:
+        total += item.get("cost_usd", item.get("amount", 0.0))
+    return total