Metadata-Version: 2.4
Name: token-pulse
Version: 0.1.0
Summary: Attribute AI assistant token usage to turns, sessions, commits, branches, PRs, time windows, or files.
Project-URL: Homepage, https://github.com/618coffee/token-pulse
Project-URL: Issues, https://github.com/618coffee/token-pulse/issues
Author: token-pulse contributors
License: MIT
License-File: LICENSE
Keywords: ai,ccusage,claude,claude-code,copilot,llm,tokens,usage
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: estimate
Requires-Dist: tiktoken>=0.7; extra == 'estimate'
Description-Content-Type: text/markdown

# token-pulse

Attribute AI assistant token usage to **turns, sessions, commits, branches, PRs, time windows, or files** — answering questions like *"how many tokens did this PR cost me?"*

Reads local Claude Code session logs (`~/.claude/projects/**/*.jsonl`) for accurate per-turn API token counts (input / output / cache_read / cache_creation), and provides an estimated mode for VS Code GitHub Copilot chat logs.

> **Status:** v0.1 — Claude Code backend is accurate. Copilot backend is best-effort estimation.

## Install

```bash
# pipx (recommended)
pipx install token-pulse

# or pip
pip install token-pulse

# with optional tiktoken-based estimation for Copilot logs
pip install 'token-pulse[estimate]'
```

## Quick start

```bash
# Last conversation turn
token-pulse turn

# Current session
token-pulse session

# A specific commit
token-pulse commit HEAD
token-pulse commit a1b2c3d

# Range of commits
token-pulse commit HEAD~5..HEAD

# Everything since branching off main
token-pulse branch --base main

# A pull request (uses `gh` CLI)
token-pulse pr 1234

# Arbitrary time window
token-pulse window --since "2026-04-20" --until "2026-04-22"

# Per-file attribution from tool calls (Edit/Write/Read targets)
token-pulse file src/foo.py

# JSON output for piping
token-pulse session --json
```

### Sample output

```
Scope: commit a1b2c3d  "feat: add scoring service"
Window: 2026-04-22 14:31:08 → 2026-04-22 15:08:47 (37m 39s)
Backend: claude-code (12 turns, 1 session)

  Input tokens:           48,210
  Output tokens:          12,883
  Cache read:            312,456
  Cache creation:         18,902
  ─────────────────────────────
  Billable in:            67,112
  Billable out:           12,883

  Estimated cost:         $0.42  (claude-sonnet-4-5)
```

## Why?

Existing tools (`ccusage`, `splitrail`, etc.) give you per-day/per-session totals. `token-pulse` lets you slice the **same underlying data** by VCS-meaningful boundaries:

| Question | Command |
|---|---|
| How much did this PR cost? | `token-pulse pr 42` |
| Which commit was most token-expensive? | `token-pulse commit HEAD~10..HEAD --rank` |
| Which file consumes the most agent context? | `token-pulse file --top 10` |
| What was the burn rate this morning? | `token-pulse window --since 09:00` |

## Backends

### `claude-code` (default, accurate)
Parses JSONL files in `~/.claude/projects/` (override with `CLAUDE_PROJECTS_DIR`). Token counts come straight from the Anthropic API `usage` field — exact, including cache hits.

### `copilot` (estimated, opt-in)
Parses VS Code workspace storage chat logs (`~/Library/Application Support/Code/User/workspaceStorage/<id>/GitHub.copilot-chat/`). Token counts are *estimated* by re-tokenizing message text with `tiktoken` (or a `chars/4` heuristic if `tiktoken` is not installed). **Does not include hidden system prompts or tool-call payloads**, so expect 30–60% under-counting. Useful for relative comparisons, not billing.

```bash
token-pulse session --backend copilot
```

## Use as an agent skill

This repo doubles as an agent skill (Claude Code & VS Code Copilot). Drop the repo into your skills dir:

```bash
# Claude Code
git clone https://github.com/618coffee/token-pulse ~/.claude/skills/token-pulse

# VS Code Copilot (workspace-scoped)
git clone https://github.com/618coffee/token-pulse .github/skills/token-pulse
```

Then ask your agent: *"How many tokens did the last commit cost?"* and it will run `token-pulse commit HEAD` for you. See [SKILL.md](SKILL.md).

## Configuration

Optional `~/.config/token-pulse/config.toml`:

```toml
default_backend = "claude-code"
default_currency = "USD"

[pricing.overrides]
"claude-sonnet-4-5" = { input = 3.00, output = 15.00, cache_read = 0.30, cache_creation = 3.75 }  # $/Mtok
```

## Limitations

- Copilot backend is estimation only (see above).
- PR scope requires the [`gh` CLI](https://cli.github.com/) authenticated to the repo.
- Per-file attribution is heuristic: assistant turn tokens are split equally across files touched by `tool_use` blocks in that turn.
- Time-window filtering uses entry `timestamp`; clock skew between machines may cause edge-case misattribution.

## Contributing

PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT
