Metadata-Version: 2.4
Name: code-meter
Version: 0.5.0
Summary: Local AI coding token usage tracker and cost estimator for Claude Code and future agents.
Author-email: Dhanush Nayak <dhanushnayak.ram@mail.com>
License: MIT
Project-URL: Homepage, https://github.com/dhanushnayak/code-meter
Project-URL: Repository, https://github.com/dhanushnayak/code-meter
Project-URL: Bug Tracker, https://github.com/dhanushnayak/code-meter/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer[all]>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# code-meter

> **Local AI Coding Token Usage Tracker, Prompt Log & Cost Estimator**

`code-meter` (also available via `claude-meter`, `codex-meter`, `antigravity-meter`, and `agy-meter` aliases) is a production-quality local CLI application designed to track local usage for **Claude Code**, **OpenAI Codex**, and **Google Antigravity**, including tokens (input, output, cache-read, cache-write), session prompts, and code change history over time.

It features an extensible multi-provider architecture so all AI coding agents operate seamlessly within unified analytics and SQLite storage.

---

## 🔒 Privacy First

* **100% Local**: Operates completely offline using your local filesystem.
* **No Gateway / Telemetry**: `code-meter` is NOT an API gateway, proxy, or interceptor.
* **Zero Uploads**: No prompts, assistant responses, source code files, or conversation texts are uploaded anywhere. Only local token metrics, session prompts, and diff logs are saved to SQLite.
* **No API Key Required**: Analyzes existing local session logs generated by Claude Code (`~/.claude`), OpenAI Codex (`~/.codex`), and Google Antigravity (`~/.gemini/antigravity-ide`).

---

## 📦 Installation

### From PyPI (Standard Installation)

```bash
pip install code-meter
```

### Local / Development (Editable Mode)

```bash
git clone https://github.com/dhanushnayak/code-meter.git
cd code-meter
pip install -e .
```

---

## 🚀 Basic Usage

Simply run:

```bash
code-meter
```

Or use one of the provider aliases (`claude-meter`, `codex-meter`, `antigravity-meter`, `agy-meter`).

This launches the interactive Rich terminal dashboard displaying key metrics, model breakdowns, project breakdowns, today's usage, and token burn rates.

---

## 🖥️ Interactive Rich Terminal UI

`code-meter` includes a full-featured, responsive **Rich Terminal User Interface** that presents live token metrics, USD costs, user queries, and model outputs in real-time.

```text
+--------------------------------------------------------------------+
|                             CODE METER                             |
|                              Overview                              |
+--------------------------------------------------------------------+
+--------------------------- Key Metrics ----------------------------+
| Requests:                                                        3 |
| Input Tokens:                                                 1.5K |
| Output Tokens:                                                 400 |
| Cache Read:                                                    300 |
| Total Tokens:                                                 2.2K |
| Estimated Cost:                                              $0.02 |
+--------------------------------------------------------------------+
| BY MODEL            | Tokens   | Cost                              |
| gemini-2.5-flash    | 2.20K    | $0.02                             |
+--------------------------------------------------------------------+
| RECENT USER QUERIES / PROMPTS                                      |
| 09-01 12:00 | antigravity | Build an interactive dashboard UI     |
+--------------------------------------------------------------------+
| RECENT OUTPUTS & CODE EDITS                                       |
| 09-01 12:01 | WRITE_FILE  | src/main.py | + print('Hello')        |
+--------------------------------------------------------------------+
```

---

## 🛠️ CLI Commands

| Command | Description |
| :--- | :--- |
| `code-meter` | Open main interactive Rich terminal dashboard UI |
| `code-meter ui` | Launch live Web Dashboard on **http://localhost:5005** (auto-opens browser) |
| `code-meter ui --terminal` | Launch live interactive Rich terminal UI |
| `code-meter watch` | Live watch mode (auto-refreshes UI as AI agents write logs) |
| `code-meter update-pricing` | Fetch latest real-time token pricing for 2,800+ models |
| `code-meter scan` | Force an incremental scan of local usage directories |
| `code-meter today` | Summary of token usage and cost for today |
| `code-meter week` | Summary of token usage and cost for the past 7 days |
| `code-meter month` | Summary of token usage and cost for the past 30 days |
| `code-meter status` | View system status (scanned files, records, prompts, code edits, DB size) |
| `code-meter prompts` | View log of user prompts and queries asked over time |
| `code-meter history` | View log of code modifications, file writes, and assistant actions |
| `code-meter diffs` | View formatted code diff summaries saved in SQLite |
| `code-meter report` | Detailed aggregated report with optional filters |
| `code-meter models` | Usage and cost breakdown by model |
| `code-meter projects` | Usage and cost breakdown by working project directory |
| `code-meter sessions` | Usage and cost breakdown by session ID |
| `code-meter export` | Export usage records to CSV or JSON format |
| `code-meter config` | Display active configuration settings and file paths |

---

## 🔍 Filters & Examples

Combine filters on reporting, prompts, and history commands:

```bash
# Update real-time token costs for 2,800+ models
code-meter update-pricing

# Filter report by provider, project, model, and timeframe
code-meter report --provider codex --model gpt-4o --days 30
code-meter report --provider antigravity --model gemini-2.5-flash

# View prompts for a specific session or project
code-meter prompts --project rag-agent --limit 20

# View code changes and diffs for a file or session
code-meter history --file src/main.py
code-meter diffs --session abc12345

# Export usage stats to CSV or JSON
code-meter export --format csv --days 7 --output usage_report.csv
```

---

## ⚙️ Configuration

Configuration is stored in `~/.config/code-meter/config.toml` (or Windows `%APPDATA%/code-meter/config.toml`).

```toml
[general]
database = "~/.local/share/code-meter/usage.db"

[claude_code]
directory = "~/.claude"

[codex]
directory = "~/.codex"

[antigravity]
directory = "~/.gemini/antigravity-ide"

[ui]
refresh_seconds = 2

[pricing]
currency = "USD"
```

Environment variables take precedence:
* `CODE_METER_DB`
* `CODE_METER_CLAUDE_DIR`
* `CODE_METER_CODEX_DIR`
* `CODE_METER_ANTIGRAVITY_DIR`
* `CODE_METER_REFRESH`

---

## 🧩 Architecture

```text
Claude Code (~/.claude)  Codex (~/.codex)  Antigravity (~/.gemini/antigravity-ide)
         │                       │                       │
         ▼                       ▼                       ▼
ClaudeCodeProvider        CodexProvider          AntigravityProvider
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 ▼
         UsageRecord / SessionPrompt / SessionCodeChange (Pydantic models)
                                 │
                                 ▼
            Database Repository & Incremental Scanner (SQLite)
                                 │
                                 ▼
           Pricing Engine (Auto Daily Sync & Live Model Pricing)
                                 │
                                 ▼
             Analytics Engine (Token counts, Costs, Aggregations)
                                 │
                                 ▼
          Rich Terminal UI & Interactive Dashboard Commands
```

---

## 🧪 Running Tests

```bash
pytest -v
```

---

## 📜 License

Distributed under the **MIT License**. See [LICENSE](LICENSE) for details.
