ccburn 0.1.0__py3-none-any.whl

ccburn/utils/formatting.py

@@ -0,0 +1,127 @@
+"""Formatting utilities for ccburn."""
+
+from datetime import datetime, timezone
+
+
+def format_duration(minutes: int) -> str:
+    """Format minutes as human-readable duration.
+
+    Args:
+        minutes: Duration in minutes
+
+    Returns:
+        Formatted string like "2h 14m", "3d 5h", "45m"
+    """
+    if minutes < 0:
+        return "0m"
+
+    if minutes < 60:
+        return f"{minutes}m"
+
+    hours = minutes // 60
+    mins = minutes % 60
+
+    if hours < 24:
+        if mins:
+            return f"{hours}h {mins}m"
+        return f"{hours}h"
+
+    days = hours // 24
+    remaining_hours = hours % 24
+
+    if remaining_hours:
+        return f"{days}d {remaining_hours}h"
+    return f"{days}d"
+
+
+def format_percentage(value: float, decimal_places: int = 0) -> str:
+    """Format 0-1 float as percentage string.
+
+    Args:
+        value: Float between 0 and 1
+        decimal_places: Number of decimal places (default 0)
+
+    Returns:
+        Formatted string like "62%" or "62.5%"
+    """
+    percent = value * 100
+    if decimal_places == 0:
+        return f"{percent:.0f}%"
+    return f"{percent:.{decimal_places}f}%"
+
+
+def format_reset_time(resets_at: datetime, now: datetime | None = None) -> str:
+    """Format reset time as relative or absolute.
+
+    Args:
+        resets_at: When the limit resets
+        now: Current time (default: now)
+
+    Returns:
+        "Resets in 2h 14m" for < 24h, "Resets Tue 4:00 PM" otherwise
+    """
+    if now is None:
+        now = datetime.now(timezone.utc)
+
+    # Ensure both are timezone-aware
+    if resets_at.tzinfo is None:
+        resets_at = resets_at.replace(tzinfo=timezone.utc)
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+
+    delta = resets_at - now
+    total_minutes = int(delta.total_seconds() / 60)
+
+    if total_minutes < 0:
+        return "Reset pending"
+
+    if total_minutes < 24 * 60:  # Less than 24 hours
+        return f"Resets in {format_duration(total_minutes)}"
+
+    # More than 24 hours - use absolute time
+    # Convert to local time for display
+    local_time = resets_at.astimezone()
+    day_name = local_time.strftime("%a")  # "Tue"
+    time_str = local_time.strftime("%-I:%M %p")  # "4:00 PM"
+    return f"Resets {day_name} {time_str}"
+
+
+def get_utilization_color(utilization: float) -> str:
+    """Get color based on utilization percentage.
+
+    Args:
+        utilization: Float between 0 and 1
+
+    Returns:
+        Color name: "green", "yellow", "orange", or "red"
+    """
+    if utilization < 0.5:
+        return "green"
+    elif utilization < 0.75:
+        return "yellow"
+    elif utilization < 0.9:
+        return "bright_red"  # Rich uses "bright_red" for orange-like
+    else:
+        return "red"
+
+
+def get_status_indicator(utilization: float, budget_pace: float) -> str:
+    """Get status indicator for compact output.
+
+    Args:
+        utilization: Current usage (0-1)
+        budget_pace: How much of window has elapsed (0-1)
+
+    Returns:
+        Status indicator: "[ ]", "[*]", "[!]", or "[X]"
+    """
+    if utilization < 0.5:
+        return "[ ]"  # Plenty available
+    elif utilization < 0.75:
+        if utilization <= budget_pace:
+            return "[*]"  # On track
+        return "[!]"  # Above pace
+    elif utilization < 0.9:
+        return "[!]"  # Caution
+    else:
+        return "[X]"  # Critical

ccburn-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,22 @@
+ccburn/__init__.py,sha256=u8tlHJ2bTam19CROn2nufmcfCONN9BwlRLY-8AOu8Os,191
+ccburn/app.py,sha256=FcVHLbnygKbMTGIFZRN5jS_Pve8VdKImfLi2KsDuEoU,15510
+ccburn/cli.py,sha256=5qYYmOWcUXNYEdK-E3DBixfWQK4wKIQs6FPvTrIfOVI,7184
+ccburn/main.py,sha256=TqWLl9xxOtbpTQr-ObomzSLG3jNec2GZ6RKEQYYdGLg,2474
+ccburn/data/__init__.py,sha256=ZczEZwodQ-MMO5F7fVNsyIpUCRY8Ya9W4pwdOOJWxm4,803
+ccburn/data/credentials.py,sha256=23ABImkZ3yC5CaArsFk3p5ujEHhEwQufJ7QUgWbSTIs,3569
+ccburn/data/history.py,sha256=ouBxrXpMp_eTs0kba1Bg55TI6bsBSMToJ32tH1wNHQI,12879
+ccburn/data/models.py,sha256=Sd2T36gH6OaNHl9zRlnnQXI-ziBA8Gl6rPYQIzmr7G4,5403
+ccburn/data/usage_client.py,sha256=_dGwmI5vYPk4S-HUe2_fnTwSuAfTPaOFff7mKPFnhps,4570
+ccburn/display/__init__.py,sha256=aL7TV53kU5oxlIwJ8M17stG2aC6UeGB-pj2u5BOpegs,495
+ccburn/display/chart.py,sha256=j1qM6YX_K5SfKCxaob3-mT1vJjr8VMdsHIN8ORJu-2c,11421
+ccburn/display/gauges.py,sha256=jkPy3BuPsN1__4Ynt0DxK8t3Su_2jl5HAJifCmdtiiA,8696
+ccburn/display/layout.py,sha256=UndPxyh32jWGdDgOZCvedz06WcKxYMSchLwpOkkXQKo,8093
+ccburn/utils/__init__.py,sha256=N6EzUX9hUJkuga_l9Ci3of1CWNtQgpNmMmNyY2DgYrg,1119
+ccburn/utils/calculator.py,sha256=QcFm5X-VWZzucHdInEjjqKV5oZaNsdpMgl8oKvHAQYc,6174
+ccburn/utils/formatting.py,sha256=vFpGY8v60G8OjTmZ1I1dYCr3h7YIfB8ezVMICb6RyZk,3327
+ccburn-0.1.0.dist-info/licenses/LICENSE,sha256=Qf2mqNi2qJ35JytfoTdR1SgYhZ2Mt4Ohcf-tu_MuYC0,1068
+ccburn-0.1.0.dist-info/METADATA,sha256=VKdT00_p1-erNPI_QzwCOjEHYn4X6ytdm2babq99uBs,6604
+ccburn-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ccburn-0.1.0.dist-info/entry_points.txt,sha256=GfFQ5VusMR8RJ9meygqWjaErdmYsf_arbILzf64WjLU,43
+ccburn-0.1.0.dist-info/top_level.txt,sha256=SM8TwGQZqQKKIQObVWQkfpA0OI4gRut7bPl-iM3g5RI,7
+ccburn-0.1.0.dist-info/RECORD,,

ccburn-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ccburn-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ccburn = ccburn.main:app

ccburn-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+ccburn