ccburn 0.1.0__tar.gz

ccburn-0.1.0/LICENSE

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

ccburn-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: ccburn
+Version: 0.1.0
+Summary: Terminal-based Claude Code usage limit visualizer with real-time burn-up charts
+Author: JuanjoFuchs
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JuanjoFuchs/ccburn
+Project-URL: Repository, https://github.com/JuanjoFuchs/ccburn.git
+Project-URL: Issues, https://github.com/JuanjoFuchs/ccburn/issues
+Project-URL: Documentation, https://github.com/JuanjoFuchs/ccburn#readme
+Keywords: claude,anthropic,usage,monitoring,tui,visualization,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer[all]>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: plotext>=5.2.0
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Requires-Dist: pyinstaller>=6.0.0; extra == "dev"
+Dynamic: license-file
+
+# ccburn
+
+[![CI](https://img.shields.io/github/actions/workflow/status/JuanjoFuchs/ccburn/ci.yml?branch=main&label=CI)](https://github.com/JuanjoFuchs/ccburn/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/actions/workflow/status/JuanjoFuchs/ccburn/release.yml?label=Release)](https://github.com/JuanjoFuchs/ccburn/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/ccburn)](https://pypi.org/project/ccburn/)
+[![Python](https://img.shields.io/pypi/pyversions/ccburn)](https://pypi.org/project/ccburn/)
+[![GitHub Release](https://img.shields.io/github/v/release/JuanjoFuchs/ccburn)](https://github.com/JuanjoFuchs/ccburn/releases)
+[![WinGet](https://img.shields.io/badge/WinGet-JuanjoFuchs.ccburn-blue)](https://winstall.app/apps/JuanjoFuchs.ccburn)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+TUI and CLI for Claude Code usage limits — burn-up charts, compact mode for status bars, JSON for automation.
+
+![ccburn screenshot](docs/ccburn.png)
+
+## Features
+
+- **Real-time burn-up charts** — Visualize session and weekly usage with live-updating terminal graphics
+- **Pace indicators** — See if you're ahead, on pace, or behind your usage budget (🧊/🔥/🚨)
+- **Multiple output modes** — Full TUI, compact single-line for status bars, or JSON for scripting
+- **Automatic data persistence** — SQLite-backed history for trend analysis
+- **Dynamic window title** — Terminal tab shows current usage at a glance
+- **Zoom views** — Focus on recent activity with `--since`
+
+## Installation
+
+### Windows (WinGet)
+
+```powershell
+winget install JuanjoFuchs.ccburn
+```
+
+### Cross-Platform (pip)
+
+```bash
+pip install ccburn
+```
+
+### From Source
+
+```bash
+git clone https://github.com/JuanjoFuchs/ccburn.git
+cd ccburn
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+1. **Ensure Claude Code is installed** — ccburn reads credentials from Claude Code's config
+2. **Run ccburn:**
+   ```bash
+   ccburn              # Session limit (default)
+   ccburn weekly       # Weekly limit
+   ccburn weekly-sonnet # Weekly Sonnet limit
+   ```
+
+## Usage Examples
+
+```bash
+# Full TUI with burn-up chart (default)
+ccburn
+
+# Weekly usage view
+ccburn weekly
+
+# Compact output for tmux/status bars
+ccburn --compact
+# Output: Session: 🔥 45% (2h14m) | Weekly: 🧊 12% | Sonnet: 🧊 3%
+
+# JSON output for scripting/automation
+ccburn --json
+
+# Zoom to last 30 minutes
+ccburn --since 30m
+
+# Single snapshot (no live updates)
+ccburn --once
+
+# Custom refresh interval (seconds)
+ccburn --interval 10
+```
+
+## Command Line Reference
+
+```
+Usage: ccburn [OPTIONS] [LIMIT]
+
+Arguments:
+  [LIMIT]  Which limit to display [default: session]
+           Options: session, weekly, weekly-sonnet
+
+Options:
+  -i, --interval INTEGER  Refresh interval in seconds [default: 5/30]
+  -s, --since TEXT        Only show data since (e.g., 30m, 2h, 1d)
+  -j, --json              Output JSON and exit
+  -o, --once              Print once and exit (no live updates)
+  -c, --compact           Single-line output for status bars
+  --debug                 Show debug information
+  --version               Show version and exit
+  --help                  Show this message and exit
+```
+
+## Pace Indicators
+
+| Emoji | Status | Meaning |
+|-------|--------|---------|
+| 🧊 | Behind pace | Usage below expected budget — you have headroom |
+| 🔥 | On pace | Usage tracking with expected budget |
+| 🚨 | Ahead of pace | Usage above expected budget — slow down! |
+
+## Requirements
+
+- **Python 3.10+**
+- **Claude Code** installed with valid credentials
+- Terminal with Unicode support (for charts and emojis)
+
+## How It Works
+
+ccburn reads your Claude Code credentials and fetches usage data from the Anthropic API. It calculates:
+
+- **Budget pace** — Where you "should" be based on time elapsed in the window
+- **Burn rate** — How fast you're consuming your limit
+- **Time to limit** — Estimated time until you hit 100% (if current rate continues)
+
+Data is stored locally in SQLite for historical analysis and to minimize API calls when running multiple instances.
+
+## Troubleshooting
+
+### "Credentials not found"
+
+Ensure Claude Code is installed and you've logged in at least once:
+```bash
+claude  # This will prompt for login if needed
+```
+
+### Chart not displaying correctly
+
+Ensure your terminal supports Unicode and has a monospace font with emoji support. Recommended terminals:
+- **Windows**: Windows Terminal
+- **macOS**: iTerm2, Terminal.app
+- **Linux**: Kitty, Alacritty, GNOME Terminal
+
+### Stale data indicator
+
+If you see "(stale)" in the header, ccburn couldn't reach the API. It will continue showing cached data and retry automatically.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+[MIT](LICENSE)
+
+## Acknowledgments
+
+- [Rich](https://github.com/Textualize/rich) — Beautiful terminal formatting
+- [Plotext](https://github.com/piccolomo/plotext) — Terminal plotting
+- [Typer](https://github.com/tiangolo/typer) — CLI framework

ccburn-0.1.0/README.md

@@ -0,0 +1,158 @@
+# ccburn
+
+[![CI](https://img.shields.io/github/actions/workflow/status/JuanjoFuchs/ccburn/ci.yml?branch=main&label=CI)](https://github.com/JuanjoFuchs/ccburn/actions/workflows/ci.yml)
+[![Release](https://img.shields.io/github/actions/workflow/status/JuanjoFuchs/ccburn/release.yml?label=Release)](https://github.com/JuanjoFuchs/ccburn/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/ccburn)](https://pypi.org/project/ccburn/)
+[![Python](https://img.shields.io/pypi/pyversions/ccburn)](https://pypi.org/project/ccburn/)
+[![GitHub Release](https://img.shields.io/github/v/release/JuanjoFuchs/ccburn)](https://github.com/JuanjoFuchs/ccburn/releases)
+[![WinGet](https://img.shields.io/badge/WinGet-JuanjoFuchs.ccburn-blue)](https://winstall.app/apps/JuanjoFuchs.ccburn)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+TUI and CLI for Claude Code usage limits — burn-up charts, compact mode for status bars, JSON for automation.
+
+![ccburn screenshot](docs/ccburn.png)
+
+## Features
+
+- **Real-time burn-up charts** — Visualize session and weekly usage with live-updating terminal graphics
+- **Pace indicators** — See if you're ahead, on pace, or behind your usage budget (🧊/🔥/🚨)
+- **Multiple output modes** — Full TUI, compact single-line for status bars, or JSON for scripting
+- **Automatic data persistence** — SQLite-backed history for trend analysis
+- **Dynamic window title** — Terminal tab shows current usage at a glance
+- **Zoom views** — Focus on recent activity with `--since`
+
+## Installation
+
+### Windows (WinGet)
+
+```powershell
+winget install JuanjoFuchs.ccburn
+```
+
+### Cross-Platform (pip)
+
+```bash
+pip install ccburn
+```
+
+### From Source
+
+```bash
+git clone https://github.com/JuanjoFuchs/ccburn.git
+cd ccburn
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+1. **Ensure Claude Code is installed** — ccburn reads credentials from Claude Code's config
+2. **Run ccburn:**
+   ```bash
+   ccburn              # Session limit (default)
+   ccburn weekly       # Weekly limit
+   ccburn weekly-sonnet # Weekly Sonnet limit
+   ```
+
+## Usage Examples
+
+```bash
+# Full TUI with burn-up chart (default)
+ccburn
+
+# Weekly usage view
+ccburn weekly
+
+# Compact output for tmux/status bars
+ccburn --compact
+# Output: Session: 🔥 45% (2h14m) | Weekly: 🧊 12% | Sonnet: 🧊 3%
+
+# JSON output for scripting/automation
+ccburn --json
+
+# Zoom to last 30 minutes
+ccburn --since 30m
+
+# Single snapshot (no live updates)
+ccburn --once
+
+# Custom refresh interval (seconds)
+ccburn --interval 10
+```
+
+## Command Line Reference
+
+```
+Usage: ccburn [OPTIONS] [LIMIT]
+
+Arguments:
+  [LIMIT]  Which limit to display [default: session]
+           Options: session, weekly, weekly-sonnet
+
+Options:
+  -i, --interval INTEGER  Refresh interval in seconds [default: 5/30]
+  -s, --since TEXT        Only show data since (e.g., 30m, 2h, 1d)
+  -j, --json              Output JSON and exit
+  -o, --once              Print once and exit (no live updates)
+  -c, --compact           Single-line output for status bars
+  --debug                 Show debug information
+  --version               Show version and exit
+  --help                  Show this message and exit
+```
+
+## Pace Indicators
+
+| Emoji | Status | Meaning |
+|-------|--------|---------|
+| 🧊 | Behind pace | Usage below expected budget — you have headroom |
+| 🔥 | On pace | Usage tracking with expected budget |
+| 🚨 | Ahead of pace | Usage above expected budget — slow down! |
+
+## Requirements
+
+- **Python 3.10+**
+- **Claude Code** installed with valid credentials
+- Terminal with Unicode support (for charts and emojis)
+
+## How It Works
+
+ccburn reads your Claude Code credentials and fetches usage data from the Anthropic API. It calculates:
+
+- **Budget pace** — Where you "should" be based on time elapsed in the window
+- **Burn rate** — How fast you're consuming your limit
+- **Time to limit** — Estimated time until you hit 100% (if current rate continues)
+
+Data is stored locally in SQLite for historical analysis and to minimize API calls when running multiple instances.
+
+## Troubleshooting
+
+### "Credentials not found"
+
+Ensure Claude Code is installed and you've logged in at least once:
+```bash
+claude  # This will prompt for login if needed
+```
+
+### Chart not displaying correctly
+
+Ensure your terminal supports Unicode and has a monospace font with emoji support. Recommended terminals:
+- **Windows**: Windows Terminal
+- **macOS**: iTerm2, Terminal.app
+- **Linux**: Kitty, Alacritty, GNOME Terminal
+
+### Stale data indicator
+
+If you see "(stale)" in the header, ccburn couldn't reach the API. It will continue showing cached data and retry automatically.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+[MIT](LICENSE)
+
+## Acknowledgments
+
+- [Rich](https://github.com/Textualize/rich) — Beautiful terminal formatting
+- [Plotext](https://github.com/piccolomo/plotext) — Terminal plotting
+- [Typer](https://github.com/tiangolo/typer) — CLI framework

ccburn-0.1.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ccburn"
+version = "0.1.0"
+description = "Terminal-based Claude Code usage limit visualizer with real-time burn-up charts"
+authors = [{name = "JuanjoFuchs"}]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = ["claude", "anthropic", "usage", "monitoring", "tui", "visualization", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+    "Topic :: System :: Monitoring",
+]
+dependencies = [
+    "typer[all]>=0.9.0",
+    "rich>=13.0.0",
+    "plotext>=5.2.0",
+    "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+    "build>=1.0.0",
+    "twine>=4.0.0",
+    "pyinstaller>=6.0.0",
+]
+
+[project.scripts]
+ccburn = "ccburn.main:app"
+
+[project.urls]
+Homepage = "https://github.com/JuanjoFuchs/ccburn"
+Repository = "https://github.com/JuanjoFuchs/ccburn.git"
+Issues = "https://github.com/JuanjoFuchs/ccburn/issues"
+Documentation = "https://github.com/JuanjoFuchs/ccburn#readme"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+ignore = [
+    "E501",  # line too long, handled by formatter
+    "B008",  # do not perform function calls in argument defaults (typer uses this)
+]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+strict_equality = true
+
+[[tool.mypy.overrides]]
+module = ["plotext", "httpx"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+minversion = "7.0"
+addopts = "-ra -q --strict-markers"
+testpaths = ["tests"]

ccburn-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ccburn-0.1.0/src/ccburn/__init__.py

@@ -0,0 +1,8 @@
+# ccburn - Terminal-based Claude Code usage limit visualizer
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("ccburn")
+except Exception:
+    __version__ = "0.0.0"