ccburn 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

ccburn/app.py

@@ -3,11 +3,13 @@
 import os
 import signal
 import threading
+import time as _time
 from datetime import datetime, timedelta, timezone
 from typing import Any
 
 from rich.console import Console
 from rich.live import Live
+from rich.text import Text
 
 try:
     from .data.credentials import CredentialsNotFoundError, TokenExpiredError
@@ -137,6 +139,7 @@ class CCBurnApp:
         Returns:
             True if fetch succeeded
         """
+        _ft0 = _time.perf_counter()
         try:
             snapshot = None
 
@@ -155,10 +158,16 @@ class CCBurnApp:
                             self.limit_type,
                             since=self._get_since_datetime(),
                         )
+                        if self.debug:
+                            self.console.print(f"[dim]  fetch: used cache (age={age:.1f}s) in {_time.perf_counter()-_ft0:.3f}s[/dim]")
                         return True
 
+            _ft1 = _time.perf_counter()
             # No fresh cached data, fetch from API
             snapshot = self.client.fetch_usage()
+            _ft2 = _time.perf_counter()
+            if self.debug:
+                self.console.print(f"[dim]  fetch: API call took {_ft2-_ft1:.3f}s[/dim]")
             self.last_snapshot = snapshot
             self.last_fetch_time = datetime.now(timezone.utc)
             self.last_error = None
@@ -197,26 +206,123 @@ class CCBurnApp:
             self.last_error = f"Unexpected error: {e}"
             return False
 
+    def _fetch_with_loading(self) -> bool:
+        """Fetch data while showing a loading message with elapsed time.
+
+        Returns:
+            True if fetch succeeded
+        """
+        result_holder = {"result": False, "done": False}
+
+        def fetch_thread():
+            result_holder["result"] = self._fetch_and_update()
+            result_holder["done"] = True
+
+        thread = threading.Thread(target=fetch_thread, daemon=True)
+        thread.start()
+
+        start_time = _time.perf_counter()
+        with Live(console=self.console, refresh_per_second=10, transient=True) as live:
+            while not result_holder["done"]:
+                elapsed = _time.perf_counter() - start_time
+                text = Text()
+                text.append("🔥 ", style="yellow")
+                text.append("Fetching data from Anthropic API... ", style="dim")
+                text.append(f"{elapsed:.1f}s", style="cyan")
+                live.update(text)
+                _time.sleep(0.1)
+
+        thread.join(timeout=1.0)
+        return result_holder["result"]
+
+    def _check_limit_available(self) -> bool:
+        """Check if the requested limit type is available in the fetched data.
+
+        Returns:
+            True if limit data is available
+        """
+        if self.last_snapshot is None:
+            return False
+        return self.last_snapshot.get_limit(self.limit_type) is not None
+
+    def _show_unavailable_error(self) -> None:
+        """Show helpful error when requested limit type is not available."""
+        self.console.print(
+            f"[red]{self.limit_type.display_name} data not available.[/red]"
+        )
+
+        # List what IS available
+        available = []
+        if self.last_snapshot:
+            if self.last_snapshot.session:
+                session = self.last_snapshot.session
+                available.append(
+                    f"  - [cyan]session[/cyan] - 5-hour limit "
+                    f"({session.utilization_percent:.0f}% used)"
+                )
+            if self.last_snapshot.monthly:
+                monthly = self.last_snapshot.monthly
+                available.append(
+                    f"  - [cyan]monthly[/cyan] - Credits usage "
+                    f"(${monthly.used_credits_dollars:.2f} / ${monthly.monthly_limit_dollars:.2f})"
+                )
+            if self.last_snapshot.weekly:
+                weekly = self.last_snapshot.weekly
+                available.append(
+                    f"  - [cyan]weekly[/cyan] - 7-day limit "
+                    f"({weekly.utilization_percent:.0f}% used)"
+                )
+            if self.last_snapshot.weekly_sonnet:
+                sonnet = self.last_snapshot.weekly_sonnet
+                available.append(
+                    f"  - [cyan]weekly-sonnet[/cyan] - 7-day Sonnet limit "
+                    f"({sonnet.utilization_percent:.0f}% used)"
+                )
+
+        if available:
+            self.console.print("\n[dim]Available:[/dim]")
+            for item in available:
+                self.console.print(item)
+            self.console.print("\n[dim]Tip: Run 'ccburn' to auto-detect.[/dim]")
+        else:
+            self.console.print(
+                "\n[dim]No usage data available. Check Claude Code authentication.[/dim]"
+            )
+
     def run(self) -> int:
         """Run the application.
 
         Returns:
             Exit code (0 for success, 1 for error)
         """
-        # Show loading message for TUI mode
-        if not self.json_output and not self.compact and not self.once:
-            self.console.print("[dim]🔥 Loading ccburn...[/dim]", end="\r")
+        _t0 = _time.perf_counter()
+        show_loading = not self.json_output and not self.compact
 
+        _t1 = _time.perf_counter()
         if not self._initialize():
             return 1
+        _t2 = _time.perf_counter()
 
-        # Initial fetch
-        if not self._fetch_and_update():
+        # Initial fetch - show loading timer for interactive modes
+        if show_loading:
+            fetch_success = self._fetch_with_loading()
+        else:
+            fetch_success = self._fetch_and_update()
+
+        if not fetch_success:
             if self.last_snapshot is None:
-                # No cached data available - error should have been printed in _fetch_and_update
                 self.console.print("[red]Failed to fetch usage data. Check your credentials.[/red]")
                 return 1
 
+        # Check if requested limit type is available
+        if not self._check_limit_available():
+            self._show_unavailable_error()
+            return 1
+
+        _t3 = _time.perf_counter()
+        if self.debug:
+            self.console.print(f"[dim]Timing: init={_t2-_t1:.3f}s fetch={_t3-_t2:.3f}s total={_t3-_t0:.3f}s[/dim]")
+
         # Handle different output modes
         if self.json_output:
             return self._run_json()
@@ -258,6 +364,7 @@ class CCBurnApp:
             self.last_snapshot.session,
             self.last_snapshot.weekly,
             self.last_snapshot.weekly_sonnet,
+            self.last_snapshot.monthly,
             budget_pace,
         )
         self.console.print(output)
@@ -418,6 +525,25 @@ class CCBurnApp:
                     "status": metrics.status,
                 }
 
+        # Add monthly credits if available
+        monthly_data = self.last_snapshot.monthly
+        if monthly_data:
+            metrics = calculate_burn_metrics(monthly_data, self.snapshots)
+            days_left = int(
+                (monthly_data.resets_at - datetime.now(timezone.utc)).total_seconds() / 86400
+            )
+            output["limits"]["monthly"] = {
+                "utilization": monthly_data.utilization,
+                "budget_pace": metrics.budget_pace,
+                "resets_at": monthly_data.resets_at.isoformat(),
+                "resets_in_days": days_left,
+                "window_hours": monthly_data.window_hours,
+                "status": metrics.status,
+                "used_credits_dollars": monthly_data.used_credits_dollars,
+                "monthly_limit_dollars": monthly_data.monthly_limit_dollars,
+                "remaining_dollars": monthly_data.remaining_dollars,
+            }
+
         # Add burn rate and projection for selected limit
         limit_data = self.last_snapshot.get_limit(self.limit_type)
         if limit_data:

ccburn/cli.py

@@ -99,6 +99,15 @@ WeeklyIntervalOption = typer.Option(
     max=300,
 )
 
+MonthlyIntervalOption = typer.Option(
+    60,
+    "--interval",
+    "-i",
+    help="Refresh interval in seconds (default: 60 for monthly).",
+    min=1,
+    max=300,
+)
+
 DebugOption = typer.Option(
     False,
     "--debug",
@@ -236,6 +245,34 @@ def create_weekly_sonnet_command(app: typer.Typer) -> None:
         )
 
 
+def create_monthly_command(app: typer.Typer) -> None:
+    """Create the monthly subcommand."""
+
+    @app.command()
+    def monthly(
+        json_output: bool = JsonOption,
+        once: bool = OnceOption,
+        compact: bool = CompactOption,
+        since: str | None = SinceOption,
+        interval: int = MonthlyIntervalOption,
+        debug: bool = DebugOption,
+    ) -> None:
+        """Display monthly credit usage (enterprise accounts).
+
+        Shows your monthly credit budget and current usage.
+        Resets on the 1st of each month.
+        """
+        run_app(
+            LimitType.MONTHLY,
+            json_output=json_output,
+            once=once,
+            compact=compact,
+            since=since,
+            interval=interval,
+            debug=debug,
+        )
+
+
 def create_clear_history_command(app: typer.Typer) -> None:
     """Create the clear-history command."""
 
@@ -281,4 +318,5 @@ def register_commands(app: typer.Typer) -> None:
     create_session_command(app)
     create_weekly_command(app)
     create_weekly_sonnet_command(app)
+    create_monthly_command(app)
     create_clear_history_command(app)

ccburn/data/history.py

@@ -6,9 +6,9 @@ from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
 try:
-    from .models import LimitData, LimitType, UsageSnapshot
+    from .models import LimitData, LimitType, MonthlyLimitData, UsageSnapshot
 except ImportError:
-    from ccburn.data.models import LimitData, LimitType, UsageSnapshot
+    from ccburn.data.models import LimitData, LimitType, MonthlyLimitData, UsageSnapshot
 
 
 logger = logging.getLogger(__name__)
@@ -39,6 +39,12 @@ class HistoryDB:
         seven_day_opus_utilization REAL,
         seven_day_opus_resets_at TEXT,
 
+        -- Monthly credits (enterprise)
+        monthly_limit_cents INTEGER,
+        monthly_used_credits_cents REAL,
+        monthly_utilization REAL,
+        monthly_resets_at TEXT,
+
         -- Raw API response for debugging
         raw_response TEXT
     );
@@ -84,6 +90,7 @@ class HistoryDB:
                 str(self.db_path) if isinstance(self.db_path, Path) else self.db_path,
                 detect_types=sqlite3.PARSE_DECLTYPES,
                 timeout=10.0,  # Wait up to 10 seconds for locks
+                check_same_thread=False,  # Allow cross-thread access for loading spinner
             )
             self._conn.row_factory = sqlite3.Row
             # Enable WAL mode for better concurrent read/write performance
@@ -104,6 +111,19 @@ class HistoryDB:
         conn.executescript(self.SCHEMA)
         conn.commit()
 
+        # Schema migration: Add monthly columns if they don't exist
+        cursor = conn.execute("PRAGMA table_info(usage_snapshots)")
+        columns = {row[1] for row in cursor.fetchall()}
+
+        if "monthly_utilization" not in columns:
+            conn.executescript("""
+                ALTER TABLE usage_snapshots ADD COLUMN monthly_limit_cents INTEGER;
+                ALTER TABLE usage_snapshots ADD COLUMN monthly_used_credits_cents REAL;
+                ALTER TABLE usage_snapshots ADD COLUMN monthly_utilization REAL;
+                ALTER TABLE usage_snapshots ADD COLUMN monthly_resets_at TEXT;
+            """)
+            conn.commit()
+
     def save_snapshot(self, snapshot: UsageSnapshot) -> None:
         """Save a usage snapshot to the database.
 
@@ -152,6 +172,18 @@ class HistoryDB:
             snapshot.weekly_opus.resets_at.isoformat() if snapshot.weekly_opus else None
         )
 
+        # Monthly credits data
+        monthly_limit = (
+            snapshot.monthly.monthly_limit_cents if snapshot.monthly else None
+        )
+        monthly_used = (
+            snapshot.monthly.used_credits_cents if snapshot.monthly else None
+        )
+        monthly_util = snapshot.monthly.utilization if snapshot.monthly else None
+        monthly_resets = (
+            snapshot.monthly.resets_at.isoformat() if snapshot.monthly else None
+        )
+
         conn.execute(
             """
             INSERT INTO usage_snapshots (
@@ -160,8 +192,10 @@ class HistoryDB:
                 seven_day_all_utilization, seven_day_all_resets_at,
                 seven_day_sonnet_utilization, seven_day_sonnet_resets_at,
                 seven_day_opus_utilization, seven_day_opus_resets_at,
+                monthly_limit_cents, monthly_used_credits_cents,
+                monthly_utilization, monthly_resets_at,
                 raw_response
-            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """,
             (
                 snapshot.timestamp.isoformat(),
@@ -173,6 +207,10 @@ class HistoryDB:
                 sonnet_resets,
                 opus_util,
                 opus_resets,
+                monthly_limit,
+                monthly_used,
+                monthly_util,
+                monthly_resets,
                 snapshot.raw_response,
             ),
         )
@@ -324,12 +362,27 @@ class HistoryDB:
                     limit_type=LimitType.WEEKLY,  # Same window as weekly
                 )
 
+            # Parse monthly credits
+            monthly = None
+            monthly_util = row["monthly_utilization"] if "monthly_utilization" in row.keys() else None
+            if monthly_util is not None:
+                resets_at = datetime.fromisoformat(row["monthly_resets_at"])
+                if resets_at.tzinfo is None:
+                    resets_at = resets_at.replace(tzinfo=timezone.utc)
+                monthly = MonthlyLimitData(
+                    monthly_limit_cents=row["monthly_limit_cents"],
+                    used_credits_cents=row["monthly_used_credits_cents"],
+                    utilization=monthly_util,
+                    resets_at=resets_at,
+                )
+
             return UsageSnapshot(
                 timestamp=timestamp,
                 session=session,
                 weekly=weekly,
                 weekly_sonnet=weekly_sonnet,
                 weekly_opus=weekly_opus,
+                monthly=monthly,
                 raw_response=row["raw_response"],
             )
         except (ValueError, KeyError, TypeError) as e:

ccburn/data/models.py

@@ -6,16 +6,22 @@ from enum import Enum
 
 
 class LimitType(str, Enum):
-    """The three usage limits we track."""
+    """The usage limits we track."""
 
     SESSION = "session"  # 5-hour rolling
     WEEKLY = "weekly"  # 7-day all models
     WEEKLY_SONNET = "weekly-sonnet"  # 7-day sonnet only
+    MONTHLY = "monthly"  # Monthly credits (enterprise)
 
     @property
-    def window_hours(self) -> int:
-        """Get the window duration in hours."""
-        return 5 if self == LimitType.SESSION else 168  # 7 * 24
+    def window_hours(self) -> int | None:
+        """Get the window duration in hours. None for variable-length windows."""
+        if self == LimitType.SESSION:
+            return 5
+        elif self == LimitType.MONTHLY:
+            return None  # Variable - calculated at runtime based on month
+        else:
+            return 168  # 7 * 24
 
     @property
     def display_name(self) -> str:
@@ -24,16 +30,18 @@ class LimitType(str, Enum):
             LimitType.SESSION: "Session (5h)",
             LimitType.WEEKLY: "Weekly",
             LimitType.WEEKLY_SONNET: "Weekly Sonnet",
+            LimitType.MONTHLY: "Monthly Credits",
         }[self]
 
     @property
-    def api_field(self) -> str:
-        """Get the corresponding API field name."""
+    def api_field(self) -> str | None:
+        """Get the corresponding API field name. None for extra_usage-based types."""
         return {
             LimitType.SESSION: "five_hour",
             LimitType.WEEKLY: "seven_day",
             LimitType.WEEKLY_SONNET: "seven_day_sonnet",
-        }[self]
+            LimitType.MONTHLY: None,  # Uses extra_usage block
+        }.get(self)
 
 
 @dataclass
@@ -47,7 +55,8 @@ class LimitData:
     @property
     def window_hours(self) -> int:
         """Get the window duration in hours."""
-        return self.limit_type.window_hours
+        hours = self.limit_type.window_hours
+        return hours if hours is not None else 168  # Fallback for type safety
 
     @property
     def window_start(self) -> datetime:
@@ -60,6 +69,51 @@ class LimitData:
         return self.utilization * 100
 
 
+@dataclass
+class MonthlyLimitData:
+    """Data for monthly credit usage (enterprise accounts)."""
+
+    monthly_limit_cents: int  # e.g., 30000 = $300.00
+    used_credits_cents: float  # e.g., 7475.0 = $74.75
+    utilization: float  # 0.0 to 1.0 normalized
+    resets_at: datetime  # 1st of next month UTC
+    limit_type: LimitType = LimitType.MONTHLY
+
+    @property
+    def monthly_limit_dollars(self) -> float:
+        """Get monthly limit in dollars."""
+        return self.monthly_limit_cents / 100.0
+
+    @property
+    def used_credits_dollars(self) -> float:
+        """Get used credits in dollars."""
+        return self.used_credits_cents / 100.0
+
+    @property
+    def remaining_dollars(self) -> float:
+        """Get remaining credits in dollars."""
+        return self.monthly_limit_dollars - self.used_credits_dollars
+
+    @property
+    def window_hours(self) -> int:
+        """Get days in current month * 24."""
+        now = datetime.now(timezone.utc)
+        first_of_month = datetime(now.year, now.month, 1, tzinfo=timezone.utc)
+        days_in_month = (self.resets_at - first_of_month).days
+        return days_in_month * 24
+
+    @property
+    def window_start(self) -> datetime:
+        """1st of current month at 00:00 UTC."""
+        now = datetime.now(timezone.utc)
+        return datetime(now.year, now.month, 1, tzinfo=timezone.utc)
+
+    @property
+    def utilization_percent(self) -> float:
+        """Get utilization as a percentage (0-100)."""
+        return self.utilization * 100
+
+
 @dataclass
 class UsageSnapshot:
     """A point-in-time snapshot of all usage limits."""
@@ -69,14 +123,16 @@ class UsageSnapshot:
     weekly: LimitData | None  # seven_day from API
     weekly_sonnet: LimitData | None  # seven_day_sonnet from API
     weekly_opus: LimitData | None  # seven_day_opus from API (tracked but not displayed)
+    monthly: MonthlyLimitData | None = None  # extra_usage from API (enterprise)
     raw_response: str | None = None  # Original JSON for debugging
 
-    def get_limit(self, limit_type: LimitType) -> LimitData | None:
+    def get_limit(self, limit_type: LimitType) -> LimitData | MonthlyLimitData | None:
         """Get limit data by type."""
         return {
             LimitType.SESSION: self.session,
             LimitType.WEEKLY: self.weekly,
             LimitType.WEEKLY_SONNET: self.weekly_sonnet,
+            LimitType.MONTHLY: self.monthly,
         }.get(limit_type)
 
     @classmethod
@@ -125,12 +181,39 @@ class UsageSnapshot:
                 except (ValueError, TypeError):
                     pass
 
+        # Parse monthly credits from extra_usage (enterprise accounts)
+        monthly = None
+        extra_usage = data.get("extra_usage")
+        if extra_usage and isinstance(extra_usage, dict):
+            if extra_usage.get("is_enabled") and extra_usage.get("monthly_limit"):
+                try:
+                    monthly_limit = int(extra_usage["monthly_limit"])
+                    used_credits = float(extra_usage.get("used_credits", 0))
+                    utilization_pct = float(extra_usage.get("utilization", 0))
+
+                    # Calculate resets_at as 1st of next month UTC
+                    now = datetime.now(timezone.utc)
+                    if now.month == 12:
+                        resets_at = datetime(now.year + 1, 1, 1, tzinfo=timezone.utc)
+                    else:
+                        resets_at = datetime(now.year, now.month + 1, 1, tzinfo=timezone.utc)
+
+                    monthly = MonthlyLimitData(
+                        monthly_limit_cents=monthly_limit,
+                        used_credits_cents=used_credits,
+                        utilization=utilization_pct / 100.0,  # Normalize to 0-1
+                        resets_at=resets_at,
+                    )
+                except (ValueError, TypeError, KeyError):
+                    pass
+
         return cls(
             timestamp=timestamp,
             session=parse_limit(data.get("five_hour"), LimitType.SESSION),
             weekly=parse_limit(data.get("seven_day"), LimitType.WEEKLY),
             weekly_sonnet=parse_limit(data.get("seven_day_sonnet"), LimitType.WEEKLY_SONNET),
             weekly_opus=weekly_opus,
+            monthly=monthly,
             raw_response=json.dumps(data),
         )
 

ccburn/display/chart.py

@@ -9,10 +9,10 @@ from rich.console import Console, ConsoleOptions, Group, RenderableType
 from rich.jupyter import JupyterMixin
 
 try:
-    from ..data.models import BurnMetrics, LimitData, UsageSnapshot
+    from ..data.models import BurnMetrics, LimitData, MonthlyLimitData, UsageSnapshot
     from ..utils.formatting import get_utilization_color
 except ImportError:
-    from ccburn.data.models import BurnMetrics, LimitData, UsageSnapshot
+    from ccburn.data.models import BurnMetrics, LimitData, MonthlyLimitData, UsageSnapshot
     from ccburn.utils.formatting import get_utilization_color
 
 
@@ -21,7 +21,7 @@ class BurnupChart(JupyterMixin):
 
     def __init__(
         self,
-        limit_data: LimitData | None,
+        limit_data: LimitData | MonthlyLimitData | None,
         snapshots: list[UsageSnapshot],
         since_duration: timedelta | None = None,
         explicit_height: int | None = None,
@@ -253,8 +253,6 @@ class BurnupChart(JupyterMixin):
         num_ticks = 5
         tick_positions = []
         tick_labels = []
-        # Use date format for windows > 24 hours
-        use_date_format = display_hours > 24
         for i in range(num_ticks):
             hours = i * display_hours / (num_ticks - 1)
             tick_positions.append(hours)
@@ -267,7 +265,10 @@ class BurnupChart(JupyterMixin):
             else:
                 local_time = local_time.replace(second=0, microsecond=0)
             # Format based on window size
-            if use_date_format:
+            if display_hours > 168:  # > 7 days (monthly)
+                # Show month/day for multi-week windows (e.g., "2/8" for Feb 8)
+                tick_labels.append(f"{local_time.month}/{local_time.day}")
+            elif display_hours > 24:
                 # Show day and time for multi-day windows (e.g., "Mon 15h")
                 tick_labels.append(local_time.strftime("%a %Hh"))
             else:
@@ -291,7 +292,9 @@ class BurnupChart(JupyterMixin):
                 local_now = local_now.replace(second=0, microsecond=0) + timedelta(minutes=1)
             else:
                 local_now = local_now.replace(second=0, microsecond=0)
-            if use_date_format:
+            if display_hours > 168:
+                tick_labels.append(f"{local_now.month}/{local_now.day} {local_now.hour}h")
+            elif display_hours > 24:
                 tick_labels.append(local_now.strftime("%a %Hh"))
             else:
                 tick_labels.append(local_now.strftime("%H:%M"))
@@ -313,7 +316,9 @@ class BurnupChart(JupyterMixin):
             else:
                 local_hits_100 = local_hits_100.replace(second=0, microsecond=0)
             tick_positions.append(hits_100_hours_for_tick)
-            if use_date_format:
+            if display_hours > 168:
+                tick_labels.append(f"{local_hits_100.month}/{local_hits_100.day} {local_hits_100.hour}h")
+            elif display_hours > 24:
                 tick_labels.append(local_hits_100.strftime("%a %Hh"))
             else:
                 tick_labels.append(local_hits_100.strftime("%H:%M"))
@@ -358,7 +363,7 @@ class BurnupChart(JupyterMixin):
 
 
 def create_simple_chart(
-    limit_data: LimitData | None,
+    limit_data: LimitData | MonthlyLimitData | None,
     snapshots: list[UsageSnapshot],
     width: int = 80,
     height: int = 15,

ccburn/display/gauges.py

@@ -9,11 +9,11 @@ from rich.table import Table
 from rich.text import Text
 
 try:
-    from ..data.models import LimitData, LimitType
+    from ..data.models import LimitData, LimitType, MonthlyLimitData
     from ..utils.calculator import calculate_budget_pace
     from ..utils.formatting import format_reset_time, get_utilization_color
 except ImportError:
-    from ccburn.data.models import LimitData, LimitType
+    from ccburn.data.models import LimitData, LimitType, MonthlyLimitData
     from ccburn.utils.calculator import calculate_budget_pace
     from ccburn.utils.formatting import format_reset_time, get_utilization_color
 
@@ -64,6 +64,23 @@ def _supports_emoji() -> bool:
     return _emoji_support_cache
 
 
+def format_credits(dollars: float) -> str:
+    """Format dollar amount for display.
+
+    Args:
+        dollars: Amount in dollars
+
+    Returns:
+        Formatted string like "$74.75" or "$1,234"
+    """
+    if dollars >= 1000:
+        return f"${dollars:,.0f}"
+    elif dollars >= 100:
+        return f"${dollars:.0f}"
+    else:
+        return f"${dollars:.2f}"
+
+
 def get_pace_emoji(utilization: float, budget_pace: float, ascii_fallback: bool = False) -> str:
     """Get emoji indicator based on utilization vs budget pace.
 
@@ -90,7 +107,9 @@ def get_pace_emoji(utilization: float, budget_pace: float, ascii_fallback: bool
         return "[=]" if use_ascii else "🔥"  # On pace - normal burn
 
 
-def create_header(limit_type: LimitType, limit_data: LimitData | None) -> Table:
+def create_header(
+    limit_type: LimitType, limit_data: LimitData | MonthlyLimitData | None
+) -> Table:
     """Create the header line with limit name and reset countdown.
 
     Args:
@@ -129,13 +148,13 @@ def create_header(limit_type: LimitType, limit_data: LimitData | None) -> Table:
 
 
 def create_gauge_section(
-    limit_data: LimitData | None,
+    limit_data: LimitData | MonthlyLimitData | None,
     budget_pace: float,
 ) -> Table:
     """Create the 2-bar gauge section for a limit.
 
     Args:
-        limit_data: Current limit data
+        limit_data: Current limit data (LimitData or MonthlyLimitData)
         budget_pace: Percentage of window elapsed (0-1)
 
     Returns:
@@ -144,18 +163,18 @@ def create_gauge_section(
     table = Table.grid(padding=(0, 1), expand=True)
     table.add_column(width=14)  # Label
     table.add_column(ratio=1)  # Bar
-    table.add_column(width=8, justify="right")  # Value
+    table.add_column(width=18, justify="right")  # Value (wider for dollar amounts)
 
     if limit_data is None:
         # Show empty/loading state
         table.add_row(
             Text("📊 Usage", style="dim"),
-            ProgressBar(total=100, completed=0, style=Style(color="dim")),
+            ProgressBar(total=100, completed=0, style=Style(color="grey37")),
             Text("--%", style="dim"),
         )
         table.add_row(
             Text("⏳ Elapsed", style="dim"),
-            ProgressBar(total=100, completed=0, style=Style(color="dim")),
+            ProgressBar(total=100, completed=0, style=Style(color="grey37")),
             Text("--%", style="dim"),
         )
         return table
@@ -178,10 +197,18 @@ def create_gauge_section(
     usage_label.append("📊 ", style="")
     usage_label.append("Usage", style=f"bold {usage_color}")
 
+    # Format value text - dollars for monthly, percentage for others
+    if isinstance(limit_data, MonthlyLimitData):
+        used = format_credits(limit_data.used_credits_dollars)
+        total = format_credits(limit_data.monthly_limit_dollars)
+        value_text = Text(f"{used} / {total}", style=usage_color)
+    else:
+        value_text = Text(f"{utilization_percent:.0f}%", style=usage_color)
+
     table.add_row(
         usage_label,
         usage_bar,
-        Text(f"{utilization_percent:.0f}%", style=usage_color),
+        value_text,
     )
 
     # Time Elapsed bar - always blue
@@ -210,17 +237,19 @@ def create_compact_output(
     session: LimitData | None,
     weekly: LimitData | None,
     weekly_sonnet: LimitData | None,
+    monthly: MonthlyLimitData | None,
     budget_pace_session: float,
 ) -> str:
     """Create compact single-line output for status bars.
 
-    Format: Session: 🧊 62% (2h14m) | Weekly: 🔥 29% | Sonnet: 🧊 1%
+    Format: Session: 🧊 62% (2h14m) | Weekly: 🔥 29% | Sonnet: 🧊 1% | Monthly: 🧊 $74.75
     Emojis indicate pace: 🧊 (behind), 🔥 (on pace), 🚨 (ahead)
 
     Args:
         session: Session limit data
         weekly: Weekly limit data
         weekly_sonnet: Weekly sonnet limit data
+        monthly: Monthly credits data
         budget_pace_session: Budget pace for session (for status indicator)
 
     Returns:
@@ -240,24 +269,29 @@ def create_compact_output(
         pace = calculate_budget_pace(session.resets_at, session.window_hours)
         emoji = get_pace_emoji(session.utilization, pace)
         parts.append(f"Session: {emoji} {session.utilization*100:.0f}% {time_str}".strip())
-    else:
-        parts.append("Session: --")
 
     # Weekly
     if weekly:
         pace = calculate_budget_pace(weekly.resets_at, weekly.window_hours)
         emoji = get_pace_emoji(weekly.utilization, pace)
         parts.append(f"Weekly: {emoji} {weekly.utilization*100:.0f}%")
-    else:
-        parts.append("Weekly: --")
 
     # Sonnet
     if weekly_sonnet:
         pace = calculate_budget_pace(weekly_sonnet.resets_at, weekly_sonnet.window_hours)
         emoji = get_pace_emoji(weekly_sonnet.utilization, pace)
         parts.append(f"Sonnet: {emoji} {weekly_sonnet.utilization*100:.0f}%")
-    else:
-        parts.append("Sonnet: --")
+
+    # Monthly credits
+    if monthly:
+        pace = calculate_budget_pace(monthly.resets_at, monthly.window_hours)
+        emoji = get_pace_emoji(monthly.utilization, pace)
+        dollars = format_credits(monthly.used_credits_dollars)
+        parts.append(f"Monthly: {emoji} {dollars}")
+
+    # If nothing available, show placeholder
+    if not parts:
+        parts.append("No data available")
 
     return " | ".join(parts)
 

ccburn/display/layout.py

@@ -8,12 +8,18 @@ from rich.layout import Layout
 from rich.text import Text
 
 try:
-    from ..data.models import BurnMetrics, LimitData, LimitType, UsageSnapshot
+    from ..data.models import BurnMetrics, LimitData, LimitType, MonthlyLimitData, UsageSnapshot
     from ..utils.calculator import calculate_budget_pace, calculate_burn_metrics
     from .chart import BurnupChart
     from .gauges import create_gauge_section, create_header
 except ImportError:
-    from ccburn.data.models import BurnMetrics, LimitData, LimitType, UsageSnapshot
+    from ccburn.data.models import (
+        BurnMetrics,
+        LimitData,
+        LimitType,
+        MonthlyLimitData,
+        UsageSnapshot,
+    )
     from ccburn.display.chart import BurnupChart
     from ccburn.display.gauges import create_gauge_section, create_header
     from ccburn.utils.calculator import calculate_budget_pace, calculate_burn_metrics
@@ -24,7 +30,7 @@ class BurnupLayout:
 
     MIN_WIDTH = 40
     MIN_HEIGHT = 10
-    COMPACT_WIDTH = 60
+    COMPACT_WIDTH = 40
     COMPACT_HEIGHT = 15
 
     def __init__(self, console: Console | None = None):
@@ -34,7 +40,7 @@ class BurnupLayout:
             console: Rich Console instance (creates one if not provided)
         """
         self.console = console or Console()
-        self._last_limit_data: LimitData | None = None
+        self._last_limit_data: LimitData | MonthlyLimitData | None = None
         self._last_snapshots: list[UsageSnapshot] = []
         self._last_metrics: BurnMetrics | None = None
         self._error_message: str | None = None
@@ -64,7 +70,7 @@ class BurnupLayout:
     def update(
         self,
         limit_type: LimitType,
-        limit_data: LimitData | None,
+        limit_data: LimitData | MonthlyLimitData | None,
         snapshots: list[UsageSnapshot],
         error: str | None = None,
         stale_since: datetime | None = None,

ccburn/main.py

@@ -2,6 +2,7 @@
 
 
 import typer
+from rich.console import Console
 
 try:
     from .cli import (
@@ -15,6 +16,7 @@ try:
         run_app,
     )
     from .data.models import LimitType
+    from .data.usage_client import UsageClient
 except ImportError:
     from ccburn.cli import (
         CompactOption,
@@ -27,6 +29,31 @@ except ImportError:
         run_app,
     )
     from ccburn.data.models import LimitType
+    from ccburn.data.usage_client import UsageClient
+
+
+def auto_detect_limit_type() -> LimitType | None:
+    """Auto-detect which limit type to use based on available data.
+
+    Priority: session -> monthly -> weekly
+
+    Returns:
+        Best available LimitType, or None if no data available.
+    """
+    try:
+        client = UsageClient()
+        snapshot = client.fetch_usage()
+
+        if snapshot.session is not None:
+            return LimitType.SESSION
+        if snapshot.monthly is not None:
+            return LimitType.MONTHLY
+        if snapshot.weekly is not None:
+            return LimitType.WEEKLY
+
+        return None
+    except Exception:
+        return None
 
 
 app = typer.Typer(
@@ -60,14 +87,14 @@ def main(
     """ccburn - Claude Code usage limit visualizer.
 
     Visualize your Claude Code usage limits with real-time burn-up charts.
-    Shows 5-hour rolling session limit by default.
+    Auto-detects available data (session or monthly credits).
 
     \b
     Examples:
-        ccburn              # Live TUI showing session limit
-        ccburn session      # Same as above (explicit)
-        ccburn weekly       # Show 7-day weekly limit
-        ccburn weekly-sonnet # Show 7-day Sonnet limit
+        ccburn              # Auto-detect best available data
+        ccburn session      # Explicit: 5-hour rolling session limit
+        ccburn weekly       # Explicit: 7-day weekly limit
+        ccburn monthly      # Explicit: Monthly credits (enterprise)
         ccburn --json       # JSON output
         ccburn --compact    # Single-line for status bars
         ccburn --once       # Print once and exit
@@ -81,10 +108,20 @@ def main(
             typer.echo("ccburn 1.0.0")
         raise typer.Exit()
 
-    # If no subcommand, default to session
+    # If no subcommand, auto-detect best available limit type
     if ctx.invoked_subcommand is None:
+        console = Console()
+
+        # Auto-detect which data is available
+        limit_type = auto_detect_limit_type()
+
+        if limit_type is None:
+            console.print("[red]No usage data available.[/red]")
+            console.print("\n[dim]Check that Claude Code is running and authenticated.[/dim]")
+            raise typer.Exit(1)
+
         run_app(
-            LimitType.SESSION,
+            limit_type,
             json_output=json_output,
             once=once,
             compact=compact,

ccburn/utils/calculator.py

@@ -3,9 +3,15 @@
 from datetime import datetime, timedelta, timezone
 
 try:
-    from ..data.models import BurnMetrics, LimitData, LimitType, UsageSnapshot
+    from ..data.models import BurnMetrics, LimitData, LimitType, MonthlyLimitData, UsageSnapshot
 except ImportError:
-    from ccburn.data.models import BurnMetrics, LimitData, LimitType, UsageSnapshot
+    from ccburn.data.models import (
+        BurnMetrics,
+        LimitData,
+        LimitType,
+        MonthlyLimitData,
+        UsageSnapshot,
+    )
 
 
 def calculate_budget_pace(resets_at: datetime, window_hours: float) -> float:
@@ -93,9 +99,10 @@ def calculate_burn_rate(
     # Check that data spans at least min_span_pct of the window
     # e.g., for 5h session at 10%, need 30 min of data
     # e.g., for 168h weekly at 10%, need ~17 hours of data
+    # Cap at 6 hours max so monthly (744h) doesn't require 3+ days of data
     if first_timestamp and last_timestamp:
         span_hours = (last_timestamp - first_timestamp).total_seconds() / 3600
-        min_span_hours = window_hours * min_span_pct
+        min_span_hours = min(window_hours * min_span_pct, 6.0)
         if span_hours < min_span_hours:
             return 0.0
 
@@ -208,7 +215,7 @@ def get_status(utilization: float, budget_pace: float) -> str:
 
 
 def calculate_burn_metrics(
-    limit_data: LimitData,
+    limit_data: LimitData | MonthlyLimitData,
     snapshots: list[UsageSnapshot],
 ) -> BurnMetrics:
     """Calculate all burn metrics for a limit.

{ccburn-0.3.1.dist-info → ccburn-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ccburn
-Version: 0.3.1
+Version: 0.4.0
 Summary: Terminal-based Claude Code usage limit visualizer with real-time burn-up charts
 Author: JuanjoFuchs
 License-Expression: MIT

ccburn-0.4.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+ccburn/__init__.py,sha256=u8tlHJ2bTam19CROn2nufmcfCONN9BwlRLY-8AOu8Os,191
+ccburn/app.py,sha256=VaXkI2CpMqH71KvZelTx4hpmllwQ6tIHlC5Ytya3bsk,22877
+ccburn/cli.py,sha256=FRDA2zDJjMvjLPG66g-PqZNRJQN0dVYkdO4M4pdZmEM,8109
+ccburn/main.py,sha256=giLHAxugFP8Go0i2TMryJBAbhNLw2LYQe2IavzfnMrE,3636
+ccburn/data/__init__.py,sha256=ZczEZwodQ-MMO5F7fVNsyIpUCRY8Ya9W4pwdOOJWxm4,803
+ccburn/data/credentials.py,sha256=wDiiTkZZDBjnYspvtWJ_52xXdTdIgBndLlfFMi-peZ8,5228
+ccburn/data/history.py,sha256=a318JaiXucHY1dUA-xCQlhSY-K9q4Z9w4JR568lYB9U,15284
+ccburn/data/models.py,sha256=d1PrxBXfxPC_eN44VaPrmndsMvq5eZtkjDYEVdRXd-0,8864
+ccburn/data/usage_client.py,sha256=_dGwmI5vYPk4S-HUe2_fnTwSuAfTPaOFff7mKPFnhps,4570
+ccburn/display/__init__.py,sha256=aL7TV53kU5oxlIwJ8M17stG2aC6UeGB-pj2u5BOpegs,495
+ccburn/display/chart.py,sha256=vyk-INnzIgkzJmEf1YKKntzlS_XhDdfKuybV2NDmRAA,16394
+ccburn/display/gauges.py,sha256=yWrQh3WBb7hm7GLb1kvIyxrtBQL5_t8zqxoD1OA9SqI,11852
+ccburn/display/layout.py,sha256=6y-jG3epA0SRzfYdPbv2WACD1GGP-Ign6UbK6fCkUTg,8367
+ccburn/utils/__init__.py,sha256=N6EzUX9hUJkuga_l9Ci3of1CWNtQgpNmMmNyY2DgYrg,1119
+ccburn/utils/calculator.py,sha256=66DycRT2o92ahA5P75u-EfTwWddNqPzn-msggkCfRx0,7895
+ccburn/utils/formatting.py,sha256=MEVIohBmvSur0hcc67oyYRDooiUMf0rPa4LO1fc2Ud4,4174
+ccburn-0.4.0.dist-info/licenses/LICENSE,sha256=Qf2mqNi2qJ35JytfoTdR1SgYhZ2Mt4Ohcf-tu_MuYC0,1068
+ccburn-0.4.0.dist-info/METADATA,sha256=g5l8YNh2o4lQLGDPgEVpGpTNmcpE6GBxN7ZIU6LVM0g,7343
+ccburn-0.4.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+ccburn-0.4.0.dist-info/entry_points.txt,sha256=GfFQ5VusMR8RJ9meygqWjaErdmYsf_arbILzf64WjLU,43
+ccburn-0.4.0.dist-info/top_level.txt,sha256=SM8TwGQZqQKKIQObVWQkfpA0OI4gRut7bPl-iM3g5RI,7
+ccburn-0.4.0.dist-info/RECORD,,

{ccburn-0.3.1.dist-info → ccburn-0.4.0.dist-info}/WHEEL

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

ccburn-0.3.1.dist-info/RECORD

@@ -1,22 +0,0 @@
-ccburn/__init__.py,sha256=u8tlHJ2bTam19CROn2nufmcfCONN9BwlRLY-8AOu8Os,191
-ccburn/app.py,sha256=IvIFOX10AFD103P5XiIenkEB2clAq2o3XJR6lceMVhE,17775
-ccburn/cli.py,sha256=dvh6V8I1TQlqbCv4-5j3ANRdKpoQKPHgA2QrBZUSkJY,7120
-ccburn/main.py,sha256=TqWLl9xxOtbpTQr-ObomzSLG3jNec2GZ6RKEQYYdGLg,2474
-ccburn/data/__init__.py,sha256=ZczEZwodQ-MMO5F7fVNsyIpUCRY8Ya9W4pwdOOJWxm4,803
-ccburn/data/credentials.py,sha256=wDiiTkZZDBjnYspvtWJ_52xXdTdIgBndLlfFMi-peZ8,5228
-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=7Rg9KeeeDjr8jwvEhHbmBYmZ0Wj3N1ijfzsQy6u6kqA,15917
-ccburn/display/gauges.py,sha256=qPjFmTJd3RcwMfpmONFHByno5ByDPaVpvDttHnfct1E,10628
-ccburn/display/layout.py,sha256=DlgmH3G2RbpyYfWYD6YP1IlohYmhWBSiqjM7Y7fto-U,8244
-ccburn/utils/__init__.py,sha256=N6EzUX9hUJkuga_l9Ci3of1CWNtQgpNmMmNyY2DgYrg,1119
-ccburn/utils/calculator.py,sha256=m-XATeOqgD5Z4ZranuI7QSlSb4pnW43_rtaJSF2Te6Q,7706
-ccburn/utils/formatting.py,sha256=MEVIohBmvSur0hcc67oyYRDooiUMf0rPa4LO1fc2Ud4,4174
-ccburn-0.3.1.dist-info/licenses/LICENSE,sha256=Qf2mqNi2qJ35JytfoTdR1SgYhZ2Mt4Ohcf-tu_MuYC0,1068
-ccburn-0.3.1.dist-info/METADATA,sha256=UnlFr_QEFUjXnwh0ho0iw_1KHYesD7g_uzOL5DJSWjk,7343
-ccburn-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ccburn-0.3.1.dist-info/entry_points.txt,sha256=GfFQ5VusMR8RJ9meygqWjaErdmYsf_arbILzf64WjLU,43
-ccburn-0.3.1.dist-info/top_level.txt,sha256=SM8TwGQZqQKKIQObVWQkfpA0OI4gRut7bPl-iM3g5RI,7
-ccburn-0.3.1.dist-info/RECORD,,