agent-tally 0.5.0__tar.gz

agent_tally-0.5.0/LICENSE

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

agent_tally-0.5.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: agent-tally
+Version: 0.5.0
+Summary: Real-time cost tracking for AI coding agents with budget limits, kill switch, and TUI dashboard.
+Author: Hiren Thakore
+Author-email: Hiren Thakore <thakoreh@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/thakoreh/agent-tally
+Project-URL: Repository, https://github.com/thakoreh/agent-tally
+Project-URL: Issues, https://github.com/thakoreh/agent-tally/issues
+Keywords: ai,agents,cost-tracking,cli,claude-code,codex,openclaw
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: author
+Dynamic: license-file
+Dynamic: requires-python
+
+# agent-tally
+
+[![PyPI version](https://img.shields.io/pypi/v/agent-tally.svg)](https://pypi.org/project/agent-tally/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://pypi.org/project/agent-tally/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/thakoreh/agent-tally?style=social)](https://github.com/thakoreh/agent-tally)
+
+**Real-time cost tracker for AI coding agents.** Wrap any CLI agent, see a live cost ticker while it runs, and enforce budgets with an automatic kill switch.
+
+## Install
+
+```bash
+pip install agent-tally
+```
+
+## Quick Start
+
+```bash
+# Track a Claude Code session
+agent-tally run claude "refactor auth module"
+
+# Set budgets
+agent-tally budget set --daily 5.00 --session 1.00
+
+# Watch costs live
+agent-tally dashboard
+```
+
+Output while your agent runs:
+
+```
+$ agent-tally run claude "fix the login bug"
+⠋ Running claude...  $0.42 │ 2.1k tokens │ 14s elapsed
+```
+
+## Features
+
+- **Live cost ticker** — dollar amount updates in real-time as the agent runs, like a taxi meter
+- **Budget enforcement** — set daily and per-session limits; auto-kills the process at 100%, warns at 80% and 95%
+- **Shell-level interception** — wraps subprocess calls. No API hooks, no SDK changes, no config files
+- **Cross-agent** — works with Claude Code, Codex CLI, Gemini CLI, OpenClaw, Cursor, and any CLI tool
+- **TUI dashboard** — `agent-tally dashboard` for a live overview of all tracked sessions
+- **Webhook alerts** — get Discord or Slack notifications when you hit budget thresholds
+- **Export** — dump cost history as JSON or CSV for your own analytics
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `agent-tally run <command> [args...]` | Wrap and track an agent |
+| `agent-tally budget set --daily 5.00 --session 1.00` | Set budget limits |
+| `agent-tally budget show` | Show current budget and usage |
+| `agent-tally dashboard` | Live TUI cost dashboard |
+| `agent-tally summary [--by-agent\|--by-model] [--since 7d]` | Usage summary |
+| `agent-tally export [--format json\|csv]` | Export cost data |
+| `agent-tally agents` | List supported agents |
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   agent-tally                        │
+│                                                      │
+│  ┌──────────┐   ┌──────────────┐   ┌─────────────┐ │
+│  │  CLI run  │──▶│   Wrapper    │──▶│  Subprocess  │ │
+│  │  command  │   │  intercepts  │   │  (agent CLI) │ │
+│  └──────────┘   │  stdout/err  │   └──────┬───────┘ │
+│                  └──────┬───────┘          │         │
+│                         │                  │         │
+│                         ▼                  │         │
+│                  ┌──────────────┐          │         │
+│                  │ Token parser │◀─────────┘         │
+│                  │ counts tokens│  (reads agent      │
+│                  │ from output  │   output stream)   │
+│                  └──────┬───────┘                    │
+│                         │                            │
+│              ┌──────────┴──────────┐                 │
+│              ▼                     ▼                 │
+│     ┌──────────────┐    ┌────────────────┐          │
+│     │  Live ticker │    │ Budget checker │          │
+│     │  $X.XX ████  │    │ warn @ 80/95%  │          │
+│     └──────────────┘    │ kill @ 100%    │          │
+│                         └───────┬────────┘          │
+│                                 ▼                    │
+│                    ┌────────────────────┐            │
+│                    │  Webhook alerts    │            │
+│                    │  Discord / Slack   │            │
+│                    └────────────────────┘            │
+└─────────────────────────────────────────────────────┘
+```
+
+agent-tally wraps your agent command as a subprocess. It parses the agent's output stream to count tokens in real-time, calculates cost using model-specific pricing, and displays a live ticker. If spending hits your budget limit, it kills the process automatically.
+
+## Supported Agents
+
+| Agent | Status |
+|---|---|
+| Claude Code | ✅ Supported |
+| Codex CLI | ✅ Supported |
+| Gemini CLI | ✅ Supported |
+| OpenClaw | ✅ Supported |
+| Cursor | ✅ Supported |
+| Any CLI agent | ✅ Generic support |
+
+## Why agent-tally over tokscale?
+
+| | agent-tally | tokscale |
+|---|---|---|
+| **Approach** | Active — wraps commands in real-time | Passive — reads session logs after the fact |
+| **Live cost display** | ✅ Ticker updates as the agent runs | ❌ Post-hoc only |
+| **Budget enforcement** | ✅ Kill switch at budget limit | ❌ No enforcement |
+| **Kill switch** | ✅ Auto-terminates runaway agents | ❌ Not possible (after the fact) |
+| **Setup** | Wrap your command, done | Parse exported logs |
+
+tokscale is great for retroactive analysis. agent-tally is for when you want to **control spend while it's happening**.
+
+## Contributing
+
+1. Fork the repo
+2. Create a branch: `git checkout -b feat/my-feature`
+3. Make changes and add tests
+4. Run `pytest`
+5. Open a PR
+
+Bug reports and feature requests welcome in [Issues](https://github.com/thakoreh/agent-tally/issues).
+
+## License
+
+[MIT](LICENSE)

agent_tally-0.5.0/README.md

@@ -0,0 +1,129 @@
+# agent-tally
+
+[![PyPI version](https://img.shields.io/pypi/v/agent-tally.svg)](https://pypi.org/project/agent-tally/)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://pypi.org/project/agent-tally/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/thakoreh/agent-tally?style=social)](https://github.com/thakoreh/agent-tally)
+
+**Real-time cost tracker for AI coding agents.** Wrap any CLI agent, see a live cost ticker while it runs, and enforce budgets with an automatic kill switch.
+
+## Install
+
+```bash
+pip install agent-tally
+```
+
+## Quick Start
+
+```bash
+# Track a Claude Code session
+agent-tally run claude "refactor auth module"
+
+# Set budgets
+agent-tally budget set --daily 5.00 --session 1.00
+
+# Watch costs live
+agent-tally dashboard
+```
+
+Output while your agent runs:
+
+```
+$ agent-tally run claude "fix the login bug"
+⠋ Running claude...  $0.42 │ 2.1k tokens │ 14s elapsed
+```
+
+## Features
+
+- **Live cost ticker** — dollar amount updates in real-time as the agent runs, like a taxi meter
+- **Budget enforcement** — set daily and per-session limits; auto-kills the process at 100%, warns at 80% and 95%
+- **Shell-level interception** — wraps subprocess calls. No API hooks, no SDK changes, no config files
+- **Cross-agent** — works with Claude Code, Codex CLI, Gemini CLI, OpenClaw, Cursor, and any CLI tool
+- **TUI dashboard** — `agent-tally dashboard` for a live overview of all tracked sessions
+- **Webhook alerts** — get Discord or Slack notifications when you hit budget thresholds
+- **Export** — dump cost history as JSON or CSV for your own analytics
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `agent-tally run <command> [args...]` | Wrap and track an agent |
+| `agent-tally budget set --daily 5.00 --session 1.00` | Set budget limits |
+| `agent-tally budget show` | Show current budget and usage |
+| `agent-tally dashboard` | Live TUI cost dashboard |
+| `agent-tally summary [--by-agent\|--by-model] [--since 7d]` | Usage summary |
+| `agent-tally export [--format json\|csv]` | Export cost data |
+| `agent-tally agents` | List supported agents |
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   agent-tally                        │
+│                                                      │
+│  ┌──────────┐   ┌──────────────┐   ┌─────────────┐ │
+│  │  CLI run  │──▶│   Wrapper    │──▶│  Subprocess  │ │
+│  │  command  │   │  intercepts  │   │  (agent CLI) │ │
+│  └──────────┘   │  stdout/err  │   └──────┬───────┘ │
+│                  └──────┬───────┘          │         │
+│                         │                  │         │
+│                         ▼                  │         │
+│                  ┌──────────────┐          │         │
+│                  │ Token parser │◀─────────┘         │
+│                  │ counts tokens│  (reads agent      │
+│                  │ from output  │   output stream)   │
+│                  └──────┬───────┘                    │
+│                         │                            │
+│              ┌──────────┴──────────┐                 │
+│              ▼                     ▼                 │
+│     ┌──────────────┐    ┌────────────────┐          │
+│     │  Live ticker │    │ Budget checker │          │
+│     │  $X.XX ████  │    │ warn @ 80/95%  │          │
+│     └──────────────┘    │ kill @ 100%    │          │
+│                         └───────┬────────┘          │
+│                                 ▼                    │
+│                    ┌────────────────────┐            │
+│                    │  Webhook alerts    │            │
+│                    │  Discord / Slack   │            │
+│                    └────────────────────┘            │
+└─────────────────────────────────────────────────────┘
+```
+
+agent-tally wraps your agent command as a subprocess. It parses the agent's output stream to count tokens in real-time, calculates cost using model-specific pricing, and displays a live ticker. If spending hits your budget limit, it kills the process automatically.
+
+## Supported Agents
+
+| Agent | Status |
+|---|---|
+| Claude Code | ✅ Supported |
+| Codex CLI | ✅ Supported |
+| Gemini CLI | ✅ Supported |
+| OpenClaw | ✅ Supported |
+| Cursor | ✅ Supported |
+| Any CLI agent | ✅ Generic support |
+
+## Why agent-tally over tokscale?
+
+| | agent-tally | tokscale |
+|---|---|---|
+| **Approach** | Active — wraps commands in real-time | Passive — reads session logs after the fact |
+| **Live cost display** | ✅ Ticker updates as the agent runs | ❌ Post-hoc only |
+| **Budget enforcement** | ✅ Kill switch at budget limit | ❌ No enforcement |
+| **Kill switch** | ✅ Auto-terminates runaway agents | ❌ Not possible (after the fact) |
+| **Setup** | Wrap your command, done | Parse exported logs |
+
+tokscale is great for retroactive analysis. agent-tally is for when you want to **control spend while it's happening**.
+
+## Contributing
+
+1. Fork the repo
+2. Create a branch: `git checkout -b feat/my-feature`
+3. Make changes and add tests
+4. Run `pytest`
+5. Open a PR
+
+Bug reports and feature requests welcome in [Issues](https://github.com/thakoreh/agent-tally/issues).
+
+## License
+
+[MIT](LICENSE)

agent_tally-0.5.0/agent_tally/__init__.py

@@ -0,0 +1,32 @@
+"""agent-tally — track costs across every AI coding agent in real-time."""
+
+__version__ = "0.5.0"
+
+from .budget import BudgetManager, BudgetConfig, BudgetStatus
+from .config import AgentTallyConfig, load_config, save_config
+from .ticker import CostTicker, IncrementalCostTracker
+from .notifier import Notifier, Alert
+from .dashboard import Dashboard
+from .storage import Storage, Session
+from .pricing import PricingConfig
+from .detector import detect_agent, parse_tokens, parse_model
+
+__all__ = [
+    "BudgetManager",
+    "BudgetConfig",
+    "BudgetStatus",
+    "AgentTallyConfig",
+    "load_config",
+    "save_config",
+    "CostTicker",
+    "IncrementalCostTracker",
+    "Notifier",
+    "Alert",
+    "Dashboard",
+    "Storage",
+    "Session",
+    "PricingConfig",
+    "detect_agent",
+    "parse_tokens",
+    "parse_model",
+]

agent_tally-0.5.0/agent_tally/budget.py

@@ -0,0 +1,193 @@
+"""Budget tracking and kill switch for agent-tally."""
+
+from __future__ import annotations
+import json
+import os
+import signal
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, date
+from pathlib import Path
+from typing import Optional, Callable
+
+import yaml
+
+
+DEFAULT_CONFIG_DIR = Path.home() / ".agent-tally"
+DEFAULT_BUDGET_FILE = DEFAULT_CONFIG_DIR / "budget.yaml"
+
+
+@dataclass
+class BudgetConfig:
+    """Budget limits configuration."""
+    daily_limit: Optional[float] = None  # USD
+    session_limit: Optional[float] = None  # USD
+    warn_at_80: bool = True
+    warn_at_95: bool = True
+    kill_at_100: bool = True
+    webhook_url: Optional[str] = None  # For notifications
+
+
+@dataclass 
+class BudgetStatus:
+    """Current budget status."""
+    session_cost: float = 0.0
+    daily_cost: float = 0.0
+    daily_limit: Optional[float] = None
+    session_limit: Optional[float] = None
+    session_pct: float = 0.0
+    daily_pct: float = 0.0
+    session_exceeded: bool = False
+    daily_exceeded: bool = False
+    session_warning: Optional[str] = None  # "80" or "95"
+    daily_warning: Optional[str] = None
+
+
+class BudgetManager:
+    """Manages budget limits and tracking."""
+    
+    def __init__(self, config_path: Optional[Path] = None):
+        self.config_path = config_path or DEFAULT_BUDGET_FILE
+        self.config = self._load_config()
+        self._session_costs: dict[str, float] = {}  # session_id -> cost
+        self._warned_sessions: set[str] = set()  # sessions that hit 80%
+        _warned_95_sessions: set[str] = set()  # sessions that hit 95%
+    
+    def _load_config(self) -> BudgetConfig:
+        """Load budget configuration from file."""
+        if not self.config_path.exists():
+            return BudgetConfig()
+        
+        with open(self.config_path) as f:
+            data = yaml.safe_load(f) or {}
+        
+        return BudgetConfig(
+            daily_limit=data.get("daily_limit"),
+            session_limit=data.get("session_limit"),
+            warn_at_80=data.get("warn_at_80", True),
+            warn_at_95=data.get("warn_at_95", True),
+            kill_at_100=data.get("kill_at_100", True),
+            webhook_url=data.get("webhook_url"),
+        )
+    
+    def save_config(self) -> None:
+        """Save current config to file."""
+        self.config_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(self.config_path, "w") as f:
+            yaml.dump({
+                "daily_limit": self.config.daily_limit,
+                "session_limit": self.config.session_limit,
+                "warn_at_80": self.config.warn_at_80,
+                "warn_at_95": self.config.warn_at_95,
+                "kill_at_100": self.config.kill_at_100,
+                "webhook_url": self.config.webhook_url,
+            }, f, default_flow_style=False)
+    
+    def set_limits(self, daily: Optional[float] = None, session: Optional[float] = None) -> None:
+        """Set budget limits.
+
+        Raises:
+            ValueError: If daily or session limit is negative.
+        """
+        if daily is not None:
+            if daily < 0:
+                raise ValueError(f"daily_limit cannot be negative, got {daily}")
+            self.config.daily_limit = daily
+        if session is not None:
+            if session < 0:
+                raise ValueError(f"session_limit cannot be negative, got {session}")
+            self.config.session_limit = session
+        self.save_config()
+    
+    def check(self, session_id: str, current_cost: float, daily_total: float) -> BudgetStatus:
+        """Check budget status and return warnings/exceeded flags."""
+        config = self.config
+        
+        # Calculate percentages
+        session_pct = 0.0
+        daily_pct = 0.0
+        
+        if config.session_limit and config.session_limit > 0:
+            session_pct = (current_cost / config.session_limit) * 100
+        
+        if config.daily_limit and config.daily_limit > 0:
+            daily_pct = (daily_total / config.daily_limit) * 100
+        
+        # Check warnings
+        session_warning = None
+        daily_warning = None
+        
+        if config.warn_at_80:
+            if session_pct >= 80 and session_id not in self._warned_sessions:
+                session_warning = "80"
+                self._warned_sessions.add(session_id)
+            if daily_pct >= 80:
+                daily_warning = "80"
+        
+        if config.warn_at_95:
+            if session_pct >= 95:
+                session_warning = "95"
+            if daily_pct >= 95:
+                daily_warning = "95"
+        
+        # Check exceeded
+        session_exceeded = config.kill_at_100 and config.session_limit and current_cost >= config.session_limit
+        daily_exceeded = config.kill_at_100 and config.daily_limit and daily_total >= config.daily_limit
+        
+        return BudgetStatus(
+            session_cost=current_cost,
+            daily_cost=daily_total,
+            daily_limit=config.daily_limit,
+            session_limit=config.session_limit,
+            session_pct=session_pct,
+            daily_pct=daily_pct,
+            session_exceeded=session_exceeded,
+            daily_exceeded=daily_exceeded,
+            session_warning=session_warning,
+            daily_warning=daily_warning,
+        )
+    
+    def should_kill(self, status: BudgetStatus) -> bool:
+        """Return True if process should be killed due to budget exceeded."""
+        return status.session_exceeded or status.daily_exceeded
+    
+    def get_warning_level(self, status: BudgetStatus) -> str:
+        """Get warning level: 'none', 'yellow' (80%), 'red' (95%), 'kill' (100%)."""
+        if status.session_exceeded or status.daily_exceeded:
+            return "kill"
+        if (status.session_warning == "95" or status.daily_warning == "95"):
+            return "red"
+        if (status.session_warning == "80" or status.daily_warning == "80"):
+            return "yellow"
+        return "none"
+    
+    @staticmethod
+    def kill_process(pid: int) -> None:
+        """Kill a process by PID."""
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except ProcessLookupError:
+            pass
+        except PermissionError:
+            # Try SIGKILL if SIGTERM fails
+            try:
+                os.kill(pid, signal.SIGKILL)
+            except (ProcessLookupError, PermissionError):
+                pass
+    
+    def get_status_text(self, status: BudgetStatus) -> str:
+        """Get human-readable status text."""
+        lines = []
+        
+        if status.session_limit:
+            pct = status.session_pct
+            cost = status.session_cost
+            limit = status.session_limit
+            lines.append(f"Session: ${cost:.4f}/${limit:.2f} ({pct:.1f}%)")
+        
+        if status.daily_limit:
+            pct = status.daily_pct
+            cost = status.daily_cost
+            limit = status.daily_limit
+            lines.append(f"Daily: ${cost:.4f}/${limit:.2f} ({pct:.1f}%)")
+        
+        return " | ".join(lines) if lines else "No budget limits set"