ai-spend-tracker 0.2.0__tar.gz

ai_spend_tracker-0.2.0/LICENSE

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

ai_spend_tracker-0.2.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: ai-spend-tracker
+Version: 0.2.0
+Summary: Aggregate token usage & cost across all your AI coding agents (Hermes, Codex, Claude Code, Copilot, OpenCode, OpenClaw, Kimi)
+Author: vick
+License: MIT
+Project-URL: Homepage, https://github.com/vick/ai-spend-tracker
+Project-URL: Repository, https://github.com/vick/ai-spend-tracker
+Project-URL: Bug Tracker, https://github.com/vick/ai-spend-tracker/issues
+Keywords: token-usage,cost-tracking,ai-coding-agent,claude-code,opencode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: rich>=13.0.0
+
+# AI Spend Tracker
+
+**Aggregate token usage & cost across all your AI coding agents in one CLI.**
+
+If you run multiple AI coding tools (Claude Code, Codex, Hermes, OpenClaw, OpenCode, GitHub Copilot, Kimi), you're probably flying blind on how much you're actually spending. AI Spend Tracker reads session data from every agent's local storage and shows you the big picture.
+
+## Features
+
+- **7 built-in collectors** — Hermes Agent, Codex CLI, GitHub Copilot CLI, OpenCode, Claude Code, OpenClaw, Kimi Code CLI
+- **Cross-platform** — Windows (native + WSL), Linux, macOS
+- **Multi-agent aggregation** — all agents in one report
+- **Extensible** — drop a custom collector in `~/.ai-spend/collectors/`
+- **Path override** — manual data source path via `~/.ai-spend/config.json`
+- **Rich terminal output** — agent summary, model breakdown, daily trends
+- **JSON output** — pipe data into your own dashboards
+
+## Supported Agents
+
+| Collector | Agent | Data Source |
+|-----------|-------|-------------|
+| `hermes` | Hermes Agent (Nous Research) | `~/.hermes/state.db` |
+| `codex` | OpenAI Codex CLI | `~/.codex/state_*.sqlite` |
+| `copilot` | GitHub Copilot CLI | `~/.copilot/session-store.db` |
+| `opencode` | OpenCode CLI | `~/.local/share/opencode/opencode.db` |
+| `claude-code` | Claude Code (Anthropic) | `~/.claude/projects/*.jsonl` |
+| `openclaw` | OpenClaw | `~/.openclaw/agents/*/sessions/*.jsonl` |
+| `kimi` | Kimi Code CLI (Moonshot AI) | `~/.kimi/sessions/*/*/wire.jsonl` |
+
+> Note: Claude Code v2.1.140+ may not persist session logs to disk. See [anthropics/claude-code#25941](https://github.com/anthropics/claude-code/issues/25941).
+
+## Quick Start
+
+```bash
+# Install
+pip install ai-spend-tracker
+
+# See your usage for the last 7 days
+ai-spend
+
+# List available data sources
+ai-spend --list-agents
+
+# See only Hermes data
+ai-spend --agent hermes
+
+# All historical data (no time limit)
+ai-spend --days 0
+
+# JSON output
+ai-spend --format json
+```
+
+## Usage
+
+```
+ai-spend [options]
+
+Options:
+  --list-agents         List all available data collectors
+  --init [name]         Initialize ~/.ai-spend/ directory
+  --agent AGENT         Filter by agent name (comma-separated)
+  --days DAYS           Days to look back (default: 7, 0 = all time)
+  --since YYYY-MM-DD    Start date
+  --until YYYY-MM-DD    End date
+  --format {table,json} Output format (default: table)
+  --demo                Show sample data (no real agents needed)
+```
+
+## Path Override
+
+If auto-detection fails, manually specify data source paths:
+
+```json
+// ~/.ai-spend/config.json
+{"paths": {
+  "hermes": "D:/custom/hermes/state.db",
+  "codex": "C:/Users/me/.codex/state_1.sqlite",
+  "copilot": "D:/copilot/session-store.db",
+  "opencode": "D:/opencode/opencode.db",
+  "claude-code": "D:/claude/projects",
+  "openclaw": "D:/.openclaw",
+  "kimi": "D:/.kimi"
+}}
+```
+
+## Custom Collectors
+
+Create your own collector in `~/.ai-spend/collectors/`:
+
+```bash
+ai-spend init my-agent
+# Edit ~/.ai-spend/collectors/my-agent.py
+# Implement BaseCollector.name(), display_name(), collect()
+```
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Linux | ✅ Full |
+| macOS | ✅ Full |
+| Windows (native) | ✅ Full |
+| Windows (WSL) | ✅ Full |
+
+## License
+
+MIT

ai_spend_tracker-0.2.0/README.md

@@ -0,0 +1,107 @@
+# AI Spend Tracker
+
+**Aggregate token usage & cost across all your AI coding agents in one CLI.**
+
+If you run multiple AI coding tools (Claude Code, Codex, Hermes, OpenClaw, OpenCode, GitHub Copilot, Kimi), you're probably flying blind on how much you're actually spending. AI Spend Tracker reads session data from every agent's local storage and shows you the big picture.
+
+## Features
+
+- **7 built-in collectors** — Hermes Agent, Codex CLI, GitHub Copilot CLI, OpenCode, Claude Code, OpenClaw, Kimi Code CLI
+- **Cross-platform** — Windows (native + WSL), Linux, macOS
+- **Multi-agent aggregation** — all agents in one report
+- **Extensible** — drop a custom collector in `~/.ai-spend/collectors/`
+- **Path override** — manual data source path via `~/.ai-spend/config.json`
+- **Rich terminal output** — agent summary, model breakdown, daily trends
+- **JSON output** — pipe data into your own dashboards
+
+## Supported Agents
+
+| Collector | Agent | Data Source |
+|-----------|-------|-------------|
+| `hermes` | Hermes Agent (Nous Research) | `~/.hermes/state.db` |
+| `codex` | OpenAI Codex CLI | `~/.codex/state_*.sqlite` |
+| `copilot` | GitHub Copilot CLI | `~/.copilot/session-store.db` |
+| `opencode` | OpenCode CLI | `~/.local/share/opencode/opencode.db` |
+| `claude-code` | Claude Code (Anthropic) | `~/.claude/projects/*.jsonl` |
+| `openclaw` | OpenClaw | `~/.openclaw/agents/*/sessions/*.jsonl` |
+| `kimi` | Kimi Code CLI (Moonshot AI) | `~/.kimi/sessions/*/*/wire.jsonl` |
+
+> Note: Claude Code v2.1.140+ may not persist session logs to disk. See [anthropics/claude-code#25941](https://github.com/anthropics/claude-code/issues/25941).
+
+## Quick Start
+
+```bash
+# Install
+pip install ai-spend-tracker
+
+# See your usage for the last 7 days
+ai-spend
+
+# List available data sources
+ai-spend --list-agents
+
+# See only Hermes data
+ai-spend --agent hermes
+
+# All historical data (no time limit)
+ai-spend --days 0
+
+# JSON output
+ai-spend --format json
+```
+
+## Usage
+
+```
+ai-spend [options]
+
+Options:
+  --list-agents         List all available data collectors
+  --init [name]         Initialize ~/.ai-spend/ directory
+  --agent AGENT         Filter by agent name (comma-separated)
+  --days DAYS           Days to look back (default: 7, 0 = all time)
+  --since YYYY-MM-DD    Start date
+  --until YYYY-MM-DD    End date
+  --format {table,json} Output format (default: table)
+  --demo                Show sample data (no real agents needed)
+```
+
+## Path Override
+
+If auto-detection fails, manually specify data source paths:
+
+```json
+// ~/.ai-spend/config.json
+{"paths": {
+  "hermes": "D:/custom/hermes/state.db",
+  "codex": "C:/Users/me/.codex/state_1.sqlite",
+  "copilot": "D:/copilot/session-store.db",
+  "opencode": "D:/opencode/opencode.db",
+  "claude-code": "D:/claude/projects",
+  "openclaw": "D:/.openclaw",
+  "kimi": "D:/.kimi"
+}}
+```
+
+## Custom Collectors
+
+Create your own collector in `~/.ai-spend/collectors/`:
+
+```bash
+ai-spend init my-agent
+# Edit ~/.ai-spend/collectors/my-agent.py
+# Implement BaseCollector.name(), display_name(), collect()
+```
+
+## Platform Support
+
+| Platform | Status |
+|----------|--------|
+| Linux | ✅ Full |
+| macOS | ✅ Full |
+| Windows (native) | ✅ Full |
+| Windows (WSL) | ✅ Full |
+
+## License
+
+MIT

ai_spend_tracker-0.2.0/ai_spend_tracker/collectors/__init__.py

@@ -0,0 +1,104 @@
+"""
+CollectorRegistry — 自动发现并注册所有可用的数据采集器。
+
+发现路径：
+1. ai_spend_tracker/collectors/ 下的 .py 文件 → 内置 collector（正常 import）
+2. ~/.ai-spend/collectors/ 下的 .py 文件 → 用户自定义 collector（file import）
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import inspect
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import Optional
+
+from ai_spend_tracker.collectors.base import BaseCollector
+
+
+def _builtin_dir() -> Path:
+    return Path(__file__).parent.resolve()
+
+
+def _user_dir() -> Path:
+    return Path.home() / ".ai-spend" / "collectors"
+
+
+def _import_user_module(file_path: Path) -> Optional[ModuleType]:
+    """从文件路径导入用户自定义模块。"""
+    try:
+        module_name = f"_custom_collector_{file_path.stem}"
+        spec = importlib.util.spec_from_file_location(module_name, file_path)
+        if spec is None or spec.loader is None:
+            return None
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[module_name] = module
+        spec.loader.exec_module(module)
+        return module
+    except Exception:
+        return None
+
+
+def _find_collectors_in_module(
+    module: ModuleType, base_module: str = ""
+) -> list[BaseCollector]:
+    """在模块中找出所有 BaseCollector 的非抽象子类实例。"""
+    collectors: list[BaseCollector] = []
+    for _name, obj in inspect.getmembers(module, inspect.isclass):
+        if (
+            issubclass(obj, BaseCollector)
+            and obj is not BaseCollector
+            and not inspect.isabstract(obj)
+        ):
+            try:
+                collectors.append(obj())
+            except Exception:
+                continue
+    return collectors
+
+
+def get_all_collectors() -> list[BaseCollector]:
+    """返回所有可用的采集器（内置 + 用户自定义）。"""
+    collectors: list[BaseCollector] = []
+
+    # 1. 内置 collector — 通过正常 import 发现
+    builtin_dir = _builtin_dir()
+    if builtin_dir.exists():
+        for file_path in sorted(builtin_dir.iterdir()):
+            if (
+                not file_path.name.endswith(".py")
+                or file_path.name == "__init__.py"
+                or file_path.name == "base.py"
+            ):
+                continue
+            module_name = f"ai_spend_tracker.collectors.{file_path.stem}"
+            try:
+                module = importlib.import_module(module_name)
+                collectors.extend(_find_collectors_in_module(module))
+            except Exception:
+                continue
+
+    # 2. 用户自定义 collector — 通过文件路径导入
+    user_dir = _user_dir()
+    if user_dir.exists():
+        for file_path in sorted(user_dir.iterdir()):
+            if (
+                not file_path.name.endswith(".py")
+                or file_path.name == "__init__.py"
+            ):
+                continue
+            module = _import_user_module(file_path)
+            if module:
+                collectors.extend(_find_collectors_in_module(module))
+
+    return collectors
+
+
+def get_collector(name: str) -> Optional[BaseCollector]:
+    for c in get_all_collectors():
+        if c.name() == name:
+            return c
+    return None

ai_spend_tracker-0.2.0/ai_spend_tracker/collectors/base.py

@@ -0,0 +1,104 @@
+"""
+BaseCollector — 所有数据采集器的抽象基类。
+
+内置 collector 放在 ai_spend_tracker/collectors/ 下，
+用户自定义 collector 放在 ~/.ai-spend/collectors/ 下，
+两者都继承此类即可自动被 CollectorRegistry 发现。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Optional
+
+from ai_spend_tracker.models import SessionRecord
+
+
+# 常用模型定价表（USD per 1M input tokens）
+# 用户自定义 collector 可以复用，也可以覆盖
+DEFAULT_PRICING: dict[str, float] = {
+    # DeepSeek
+    "deepseek-v4-pro": 3.0,
+    "deepseek-v4-flash": 0.5,
+    "deepseek-v3.2": 2.0,
+    "deepseek-v3.1": 2.0,
+    "deepseek-v3": 2.0,
+    "deepseek-r1": 4.0,
+    # Qwen
+    "qwen3.7-max": 4.0,
+    "qwen3.6-max": 3.5,
+    "qwen3.5-plus": 2.0,
+    "qwen3.5-flash": 0.5,
+    "qwen-max": 4.0,
+    "qwen-plus": 2.0,
+    "qwen-turbo": 0.5,
+    "qwen3.5-omni-plus": 3.0,
+    # MiniMax
+    "MiniMax-M2.7": 3.0,
+    "MiniMax-M2.5": 2.0,
+    "MiniMax-M2.1": 1.0,
+    # Claude
+    "claude-sonnet-4-6": 15.0,
+    "claude-sonnet-4": 15.0,
+    "claude-opus-4": 15.0,
+    "claude-opus-4-8": 15.0,
+    "claude-sonnet-4.5": 15.0,
+    "claude-haiku-3.5": 1.0,
+    # Claude Code 内部模型别名
+    "claude-sonnet-4-8": 15.0,
+    "claude-opus-4-5": 15.0,
+    # GitHub Copilot（常见模型）
+    "gpt-5.4": 10.0,
+    "gpt-5.5": 15.0,
+    "gpt-5.1": 5.0,
+    "claude-sonnet-4.5": 15.0,
+    # Kimi (Moonshot AI)
+    "kimi-for-coding": 4.0,
+    "moonshot-k2.5": 4.0,
+    "moonshot-k2.6": 4.0,
+}
+
+
+def estimate_cost(
+    input_tokens: int,
+    output_tokens: int,
+    model: str,
+    pricing: dict[str, float] | None = None,
+    output_multiplier: float = 4.0,
+) -> float:
+    """根据 token 用量和模型估算费用。"""
+    table = pricing if pricing is not None else DEFAULT_PRICING
+    price_per_1m_input = table.get(model, 2.0)
+    cost_input = input_tokens / 1_000_000 * price_per_1m_input
+    cost_output = output_tokens / 1_000_000 * price_per_1m_input * output_multiplier
+    return round(cost_input + cost_output, 6)
+
+
+class BaseCollector(ABC):
+    """所有数据采集器必须实现此接口。"""
+
+    @abstractmethod
+    def name(self) -> str:
+        """采集器名称，如 'hermes'、'codex'、'my-agent'。"""
+        ...
+
+    @abstractmethod
+    def display_name(self) -> str:
+        """用户友好的显示名称，如 'Hermes Agent'、'Codex CLI'。"""
+        ...
+
+    @abstractmethod
+    def collect(
+        self,
+        since: Optional[datetime] = None,
+        until: Optional[datetime] = None,
+    ) -> list[SessionRecord]:
+        """从数据源读取会话记录。"""
+        ...
+
+    def description(self) -> str:
+        return self.display_name()
+
+    def pricing_table(self) -> dict[str, float]:
+        return DEFAULT_PRICING