agentabacus 0.1.0__tar.gz

agentabacus-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "agentabacus",
+  "owner": {
+    "name": "Ayoade Adegbite"
+  },
+  "plugins": [
+    {
+      "name": "agentabacus",
+      "source": "./plugin",
+      "description": "Archives this session's token usage and tool calls to your local agentabacus database when the session ends, before Claude Code's cleanup can delete the transcript."
+    }
+  ]
+}

agentabacus-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,107 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      # setup-python must come first: it provides the matrix interpreter.
+      # Without it, `uv pip install --system` targets the runner's own Python,
+      # which on macOS is Homebrew-managed and refuses installs (PEP 668).
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install
+        run: uv pip install --system -e .
+
+      # The dedupe contract is the one invariant that, if broken, makes every
+      # cost figure the tool reports wrong. It runs before anything else.
+      - name: Contract tests
+        run: python tests/test_dedupe.py
+
+      - name: CLI smoke test
+        run: |
+          agentabacus --help
+          agentabacus doctor
+          agentabacus collect
+          agentabacus report --since all || true
+
+      # A fresh machine has no agent logs. Collecting nothing must exit 0 and
+      # print something sane rather than traceback -- that is most contributors'
+      # very first run.
+      - name: Empty-environment behaviour
+        env:
+          CLAUDE_CONFIG_DIR: /tmp/definitely-not-here
+          CODEX_HOME: /tmp/definitely-not-here
+          AGENTABACUS_HOME: /tmp/al-empty
+        run: |
+          agentabacus doctor
+          agentabacus collect
+
+  pricing:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Pricing is community-edited. A malformed row would silently zero out
+      # cost for that model, so the CSV is validated on every PR.
+      - name: Validate pricing table
+        run: |
+          python - <<'PY'
+          import csv, sys
+          from datetime import date
+
+          required = [
+              "model_id", "speed", "valid_from", "valid_to",
+              "input_per_mtok", "output_per_mtok", "cache_read_per_mtok",
+              "cache_write_5m_per_mtok", "cache_write_1h_per_mtok", "source_note",
+          ]
+          path = "src/agentabacus/data/pricing.csv"
+          rows = list(csv.DictReader(open(path)))
+          errors = []
+
+          if not rows:
+              errors.append("pricing.csv is empty")
+          if rows and list(rows[0].keys()) != required:
+              errors.append(f"columns must be exactly {required}")
+
+          seen = set()
+          for i, r in enumerate(rows, start=2):
+              key = (r["model_id"], r["speed"], r["valid_from"])
+              if key in seen:
+                  errors.append(f"line {i}: duplicate {key}")
+              seen.add(key)
+              try:
+                  date.fromisoformat(r["valid_from"])
+                  if r["valid_to"]:
+                      date.fromisoformat(r["valid_to"])
+              except ValueError as exc:
+                  errors.append(f"line {i}: bad date ({exc})")
+              for col in required[4:9]:
+                  try:
+                      if float(r[col]) < 0:
+                          errors.append(f"line {i}: {col} is negative")
+                  except ValueError:
+                      errors.append(f"line {i}: {col}={r[col]!r} is not a number")
+              if r["speed"] not in {"standard", "fast"}:
+                  errors.append(f"line {i}: speed must be standard or fast")
+
+          for e in errors:
+              print(f"::error file={path}::{e}")
+          sys.exit(1 if errors else 0)
+          PY

agentabacus-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,65 @@
+name: release
+
+# Publishes to PyPI via Trusted Publishing (OIDC). No API token is stored in
+# this repo or on any developer machine -- GitHub proves the workflow's identity
+# to PyPI directly.
+#
+# One-time setup on PyPI (https://pypi.org/manage/account/publishing/):
+#   PyPI project name : agentabacus
+#   Owner             : tripleaceme
+#   Repository name   : agentabacus
+#   Workflow name     : release.yml
+#   Environment name  : pypi
+#
+# Then release with:
+#   git tag v0.1.0 && git push origin v0.1.0
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Verify the tag matches the packaged version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::tag v$TAG does not match pyproject version $PKG"
+            exit 1
+          fi
+        if: startsWith(github.ref, 'refs/tags/')
+
+      - name: Contract tests
+        run: |
+          uv pip install --system -e .
+          python tests/test_dedupe.py
+
+      - run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

agentabacus-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.DS_Store
+*.duckdb
+*.duckdb.wal
+agentabacus_export/
+.pytest_cache/

agentabacus-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing
+
+Two contributions matter more than any others, and both are small.
+
+## 1. Add or correct a model price
+
+`src/agentabacus/data/pricing.csv` — one line, no Python:
+
+```csv
+model_id,speed,valid_from,valid_to,input_per_mtok,output_per_mtok,cache_read_per_mtok,cache_write_5m_per_mtok,cache_write_1h_per_mtok,source_note
+claude-opus-5,standard,2020-01-01,,5.00,25.00,0.50,6.25,10.00,anthropic list price
+```
+
+Rules:
+
+- **`valid_to` empty means "still current."** To change a price, close the old row with a `valid_to` and add a new row starting the next day. Never edit a historical row's rates — that silently reprices everyone's past sessions.
+- **Cache columns are not optional.** Reads bill at 0.1× input, 5-minute writes at 1.25×, 1-hour writes at 2×. If a provider prices them differently, put the real numbers in; the schema doesn't assume the multipliers.
+- **Dated snapshot IDs need no row.** `claude-haiku-4-5-20251001` normalizes to `claude-haiku-4-5` automatically.
+- Cite where the numbers came from in `source_note`.
+
+CI validates column order, date parsing, duplicate keys, and negative values.
+
+Run `agentabacus doctor` to see models present in your own data with no pricing row — that list is the to-do list.
+
+## 2. Add an adapter
+
+One module exposing `parse(path, kind, start_offset) -> Batch`, a walker in `discovery.py`, one line in `adapters/__init__.py`.
+
+Read `adapters/claude_code.py` as the reference and `adapters/codex.py` as the minimal template.
+
+**The one rule: be a tolerant parser.** These log formats are undocumented, version-dependent, and change without notice. Route on known shapes, count what you skip, and never raise — a vendor's routine release must not become a crash for every user. Strictness belongs in `schema.py`, not at the edges.
+
+Things that have already bitten this codebase, so check for them in yours:
+
+- **Repeated usage across records.** Claude Code writes one line per content block, each carrying the parent response's *full* usage. Summing per line overcounts 2–3×. Key on a request id and merge with `max()`.
+- **More than one file layout.** Claude Code nests subagent transcripts at two different depths. A fixed-depth glob silently dropped the majority of them. Recurse.
+- **Torn trailing lines.** A file caught mid-write must be re-read whole next run, never half-parsed. `iter_lines()` handles this; use it.
+- **Model IDs in two forms.** Aliased and date-stamped. Normalize before joining to pricing.
+
+### Verifying the Codex adapter
+
+`adapters/codex.py` is shape-agnostic and **unverified** — it was written without access to real rollout files. If you have `~/.codex/sessions/*.jsonl`, paste two or three redacted records into a test fixture and tighten the parsing. That's the highest-value PR in the repo right now.
+
+## Running things
+
+```bash
+uv venv && uv pip install -e .
+python tests/test_dedupe.py     # the contract tests
+agentabacus doctor              # what's discoverable on your machine
+```
+
+## What this project deliberately does not do
+
+- No hosted service, no account, no telemetry.
+- **Prompt and response bodies never enter the pipeline.** The `prompts` table stores a hash and a length; there is no column for the text. Please don't add one — that property is why the tool is installable inside companies.
+- No agent that acts on the data.
+
+Team/warehouse sinks and a dbt package are on the roadmap, not in scope yet.

agentabacus-0.1.0/LICENSE

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

agentabacus-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: agentabacus
+Version: 0.1.0
+Summary: Local-first analytics for AI coding agents. Reads the session logs already on your disk.
+Project-URL: Homepage, https://github.com/tripleaceme/agentabacus
+Project-URL: Issues, https://github.com/tripleaceme/agentabacus/issues
+Author: Ayoade Adegbite
+License: MIT
+License-File: LICENSE
+Keywords: agents,analytics,claude,codex,cost,duckdb,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: duckdb>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# agentabacus
+
+**Local-first analytics for AI coding agents.** Every agent CLI writes session logs to your disk in its own format. Nothing reads all of them. `agentabacus` normalizes them into one schema and answers: what did this cost, which model actually finishes the work, and where is the spend going?
+
+No server. No account. No network calls. It reads files that are already on your machine and writes one DuckDB file.
+
+```bash
+uvx agentabacus collect      # read new log data into the archive
+uvx agentabacus report       # cost and tokens, last 30 days
+```
+
+---
+
+## Why this exists
+
+Three things make the naive version of this tool wrong, and all three are handled here.
+
+### 1. Summing usage per log line overcounts by 2–3×
+
+Claude Code writes **one JSONL line per content block** — thinking, text, each `tool_use` — and every one of those lines repeats the **full usage of the parent API response**. Measured on a real session: 16 assistant lines, 6 actual requests.
+
+|  | naive per-line sum | deduped by `requestId` | overcount |
+|---|---:|---:|---:|
+| input | 5,273 | 1,759 | 3.0× |
+| output | 18,555 | 7,861 | 2.4× |
+| cache read | 712,283 | 264,865 | 2.7× |
+| cache write | 61,219 | 25,647 | 2.4× |
+
+The multiplier depends on how many content blocks a response happened to emit, so it can't be corrected after the fact with a constant. `agentabacus` keys the `turns` table on `request_id` and merges with `MAX()`.
+
+### 2. Cache writes are not one number
+
+A **1-hour** TTL cache write bills at **2×** base input. A **5-minute** write bills at **1.25×**. A cache read bills at **0.1×**. Claude Code records the split (`cache_creation.ephemeral_1h_input_tokens` vs `ephemeral_5m_input_tokens`); collapsing them into a single `cache_creation_input_tokens` figure misprices exactly the long sessions where cache tokens accumulate.
+
+### 3. Subagent transcripts live in separate files
+
+```
+~/.claude/projects/<slug>/<uuid>.jsonl                             # main transcript
+~/.claude/projects/<slug>/<uuid>/subagents/agent-*.jsonl           # plain subagent
+~/.claude/projects/<slug>/<uuid>/subagents/workflows/wf_*/agent-*.jsonl   # workflow subagent
+```
+
+Two things bite here. A `projects/*/*.jsonl` glob — the obvious one — misses every subagent file. And a `*/subagents/*.jsonl` glob still misses the **workflow** subagents one level deeper, which on a machine that runs workflows are the *majority* (measured: 80 of 127). Discovery has to recurse.
+
+Subagent files carry the **parent's** `sessionId` plus their own `agentId`, so the thread is what separates them, not the session. `agentabacus report --by thread` splits main-loop from subagent spend — a number no other tool surfaces.
+
+---
+
+## Install
+
+```bash
+uvx agentabacus report          # zero-install trial
+pipx install agentabacus        # permanent CLI
+```
+
+Then:
+
+```bash
+agentabacus doctor              # what's discoverable, what's collected, what has no price
+agentabacus collect             # incremental; safe to run repeatedly
+```
+
+### Collect automatically (Claude Code plugin)
+
+Transcripts get garbage-collected, so collection has to happen without you remembering. The plugin registers a `SessionEnd` hook that archives each session as it closes:
+
+```
+/plugin marketplace add tripleaceme/agentabacus
+/plugin install agentabacus@agentabacus
+```
+
+The CLI must be on your `PATH` (`pipx install agentabacus`). No daemon, no cron entry.
+
+## Commands
+
+```bash
+agentabacus report --since 30d --by model      # or: source project branch day effort speed thread
+agentabacus top --limit 10                     # most expensive sessions
+agentabacus cache                              # read share and the 1h/5m write split, priced
+agentabacus tools                              # tool-call volume and error rate
+agentabacus doctor                             # health + pricing gaps
+agentabacus export --format parquet            # hand the tables to dbt / Metabase
+agentabacus sql "select ..."                   # the schema is yours
+```
+
+`--by thread` splits main-loop spend from subagent spend — the number most tools can't show you at all.
+
+## Where the data lives
+
+```
+~/.agentabacus/agentabacus.duckdb     # the archive: everything, all time
+```
+
+Override with `AGENTABACUS_HOME`. The collector is incremental: it records a byte offset per file and re-reads nothing, so a repeat run over a 350 MB corpus costs one `stat()` per file.
+
+**This matters more than it sounds.** Claude Code garbage-collects old transcripts. Project directories with a `memory/` folder and zero `.jsonl` files are what that looks like afterwards — that history is gone permanently. Once cleanup runs, this database is the only copy. `agentabacus` is an archive with a dashboard on top, not a dashboard.
+
+## Privacy
+
+Prompt and response bodies **never enter the pipeline**. The `prompts` table stores a SHA-256 and a character count; there is no column for the text. That's a schema property, not a filter you have to trust — "does this leak my code?" is answerable by reading `schema.py`.
+
+Nothing is uploaded anywhere. There is no telemetry.
+
+## Pricing
+
+`src/agentabacus/data/pricing.csv` — effective-dated, one row per model per speed tier:
+
+```csv
+model_id,speed,valid_from,valid_to,input_per_mtok,output_per_mtok,cache_read_per_mtok,cache_write_5m_per_mtok,cache_write_1h_per_mtok,source_note
+claude-opus-5,standard,2020-01-01,,5.00,25.00,0.50,6.25,10.00,anthropic list price
+```
+
+Cost is computed as **tokens × price-at-event-timestamp**, via the `turns_costed` view. Joining against a "current price" table would silently reprice last quarter's sessions.
+
+`agentabacus doctor` lists any model seen in your data that has no pricing row — that's the alarm for "a new model shipped and the table is stale", which is otherwise a silent undercount.
+
+**Adding a model is a one-line CSV edit.** Dates currently use an early `valid_from` so historical sessions price at today's rate; real effective dates are welcome as PRs.
+
+## Contributing an adapter
+
+One module exposing `parse(path, kind, start_offset) -> Batch`, a walker in `discovery.py`, one line in `adapters/__init__.py`. See `adapters/claude_code.py` for the reference and `adapters/codex.py` for the minimal template.
+
+**The rule: be a tolerant parser.** These formats are undocumented and change without notice. Route on known shapes, count what you skipped, never raise — a vendor's routine release must not become a crash for every user. Strictness belongs in `schema.py`, not at the edges.
+
+```bash
+python tests/test_dedupe.py    # pins the dedupe contract, the TTL split, and torn-line handling
+```
+
+## Status
+
+| Source | State |
+|---|---|
+| Claude Code | verified against real transcripts |
+| Codex CLI | **shape-agnostic, unverified** — needs someone with real rollout files |
+| Gemini CLI, Cursor, Aider, Cline | not yet written |
+
+## Roadmap
+
+- Edit-survival metric from `file-history-snapshot.trackedFileBackups` (pre-edit backups are already in the transcript, so no git join is needed for Claude Code)
+- More adapters
+- `agentabacus dash` — local static dashboard
+- **Teams**: warehouse sinks (Postgres/Snowflake/BigQuery), redaction policy in version control, a GitHub Action for rollups
+- **`dbt_agentabacus`**: staging models over the parquet export, pricing as a seed, tests as drift detection
+
+## License
+
+MIT

agentabacus-0.1.0/README.md

@@ -0,0 +1,147 @@
+# agentabacus
+
+**Local-first analytics for AI coding agents.** Every agent CLI writes session logs to your disk in its own format. Nothing reads all of them. `agentabacus` normalizes them into one schema and answers: what did this cost, which model actually finishes the work, and where is the spend going?
+
+No server. No account. No network calls. It reads files that are already on your machine and writes one DuckDB file.
+
+```bash
+uvx agentabacus collect      # read new log data into the archive
+uvx agentabacus report       # cost and tokens, last 30 days
+```
+
+---
+
+## Why this exists
+
+Three things make the naive version of this tool wrong, and all three are handled here.
+
+### 1. Summing usage per log line overcounts by 2–3×
+
+Claude Code writes **one JSONL line per content block** — thinking, text, each `tool_use` — and every one of those lines repeats the **full usage of the parent API response**. Measured on a real session: 16 assistant lines, 6 actual requests.
+
+|  | naive per-line sum | deduped by `requestId` | overcount |
+|---|---:|---:|---:|
+| input | 5,273 | 1,759 | 3.0× |
+| output | 18,555 | 7,861 | 2.4× |
+| cache read | 712,283 | 264,865 | 2.7× |
+| cache write | 61,219 | 25,647 | 2.4× |
+
+The multiplier depends on how many content blocks a response happened to emit, so it can't be corrected after the fact with a constant. `agentabacus` keys the `turns` table on `request_id` and merges with `MAX()`.
+
+### 2. Cache writes are not one number
+
+A **1-hour** TTL cache write bills at **2×** base input. A **5-minute** write bills at **1.25×**. A cache read bills at **0.1×**. Claude Code records the split (`cache_creation.ephemeral_1h_input_tokens` vs `ephemeral_5m_input_tokens`); collapsing them into a single `cache_creation_input_tokens` figure misprices exactly the long sessions where cache tokens accumulate.
+
+### 3. Subagent transcripts live in separate files
+
+```
+~/.claude/projects/<slug>/<uuid>.jsonl                             # main transcript
+~/.claude/projects/<slug>/<uuid>/subagents/agent-*.jsonl           # plain subagent
+~/.claude/projects/<slug>/<uuid>/subagents/workflows/wf_*/agent-*.jsonl   # workflow subagent
+```
+
+Two things bite here. A `projects/*/*.jsonl` glob — the obvious one — misses every subagent file. And a `*/subagents/*.jsonl` glob still misses the **workflow** subagents one level deeper, which on a machine that runs workflows are the *majority* (measured: 80 of 127). Discovery has to recurse.
+
+Subagent files carry the **parent's** `sessionId` plus their own `agentId`, so the thread is what separates them, not the session. `agentabacus report --by thread` splits main-loop from subagent spend — a number no other tool surfaces.
+
+---
+
+## Install
+
+```bash
+uvx agentabacus report          # zero-install trial
+pipx install agentabacus        # permanent CLI
+```
+
+Then:
+
+```bash
+agentabacus doctor              # what's discoverable, what's collected, what has no price
+agentabacus collect             # incremental; safe to run repeatedly
+```
+
+### Collect automatically (Claude Code plugin)
+
+Transcripts get garbage-collected, so collection has to happen without you remembering. The plugin registers a `SessionEnd` hook that archives each session as it closes:
+
+```
+/plugin marketplace add tripleaceme/agentabacus
+/plugin install agentabacus@agentabacus
+```
+
+The CLI must be on your `PATH` (`pipx install agentabacus`). No daemon, no cron entry.
+
+## Commands
+
+```bash
+agentabacus report --since 30d --by model      # or: source project branch day effort speed thread
+agentabacus top --limit 10                     # most expensive sessions
+agentabacus cache                              # read share and the 1h/5m write split, priced
+agentabacus tools                              # tool-call volume and error rate
+agentabacus doctor                             # health + pricing gaps
+agentabacus export --format parquet            # hand the tables to dbt / Metabase
+agentabacus sql "select ..."                   # the schema is yours
+```
+
+`--by thread` splits main-loop spend from subagent spend — the number most tools can't show you at all.
+
+## Where the data lives
+
+```
+~/.agentabacus/agentabacus.duckdb     # the archive: everything, all time
+```
+
+Override with `AGENTABACUS_HOME`. The collector is incremental: it records a byte offset per file and re-reads nothing, so a repeat run over a 350 MB corpus costs one `stat()` per file.
+
+**This matters more than it sounds.** Claude Code garbage-collects old transcripts. Project directories with a `memory/` folder and zero `.jsonl` files are what that looks like afterwards — that history is gone permanently. Once cleanup runs, this database is the only copy. `agentabacus` is an archive with a dashboard on top, not a dashboard.
+
+## Privacy
+
+Prompt and response bodies **never enter the pipeline**. The `prompts` table stores a SHA-256 and a character count; there is no column for the text. That's a schema property, not a filter you have to trust — "does this leak my code?" is answerable by reading `schema.py`.
+
+Nothing is uploaded anywhere. There is no telemetry.
+
+## Pricing
+
+`src/agentabacus/data/pricing.csv` — effective-dated, one row per model per speed tier:
+
+```csv
+model_id,speed,valid_from,valid_to,input_per_mtok,output_per_mtok,cache_read_per_mtok,cache_write_5m_per_mtok,cache_write_1h_per_mtok,source_note
+claude-opus-5,standard,2020-01-01,,5.00,25.00,0.50,6.25,10.00,anthropic list price
+```
+
+Cost is computed as **tokens × price-at-event-timestamp**, via the `turns_costed` view. Joining against a "current price" table would silently reprice last quarter's sessions.
+
+`agentabacus doctor` lists any model seen in your data that has no pricing row — that's the alarm for "a new model shipped and the table is stale", which is otherwise a silent undercount.
+
+**Adding a model is a one-line CSV edit.** Dates currently use an early `valid_from` so historical sessions price at today's rate; real effective dates are welcome as PRs.
+
+## Contributing an adapter
+
+One module exposing `parse(path, kind, start_offset) -> Batch`, a walker in `discovery.py`, one line in `adapters/__init__.py`. See `adapters/claude_code.py` for the reference and `adapters/codex.py` for the minimal template.
+
+**The rule: be a tolerant parser.** These formats are undocumented and change without notice. Route on known shapes, count what you skipped, never raise — a vendor's routine release must not become a crash for every user. Strictness belongs in `schema.py`, not at the edges.
+
+```bash
+python tests/test_dedupe.py    # pins the dedupe contract, the TTL split, and torn-line handling
+```
+
+## Status
+
+| Source | State |
+|---|---|
+| Claude Code | verified against real transcripts |
+| Codex CLI | **shape-agnostic, unverified** — needs someone with real rollout files |
+| Gemini CLI, Cursor, Aider, Cline | not yet written |
+
+## Roadmap
+
+- Edit-survival metric from `file-history-snapshot.trackedFileBackups` (pre-edit backups are already in the transcript, so no git join is needed for Claude Code)
+- More adapters
+- `agentabacus dash` — local static dashboard
+- **Teams**: warehouse sinks (Postgres/Snowflake/BigQuery), redaction policy in version control, a GitHub Action for rollups
+- **`dbt_agentabacus`**: staging models over the parquet export, pricing as a seed, tests as drift detection
+
+## License
+
+MIT

agentabacus-0.1.0/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "agentabacus",
+  "version": "0.1.0",
+  "description": "Archives this session's usage to your local agentabacus database when the session ends.",
+  "author": { "name": "Ayoade Adegbite" },
+  "homepage": "https://github.com/tripleaceme/agentabacus",
+  "license": "MIT"
+}

agentabacus-0.1.0/plugin/README.md

@@ -0,0 +1,40 @@
+# agentabacus — Claude Code plugin
+
+Runs `agentabacus collect` when a session ends, so usage is archived **before**
+Claude Code's cleanup can delete the transcript.
+
+## Why a plugin rather than a cron job
+
+Transcripts are garbage-collected. A directory with a `memory/` folder and no
+`.jsonl` files is what a project looks like after cleanup has run — that history
+is unrecoverable. Collection therefore has to happen without the user
+remembering to run it.
+
+A `SessionEnd` hook is the cheapest way to guarantee that:
+
+- fires exactly when the data is freshest, long before cleanup
+- incremental by construction — one session's new bytes, milliseconds of work
+- no daemon, no cron entry, no background process to explain
+- installs from inside the tool people already have open
+
+## Install
+
+```bash
+pipx install agentabacus              # the CLI must be on PATH
+```
+
+```
+/plugin marketplace add tripleaceme/agentabacus
+/plugin install agentabacus
+```
+
+Then `agentabacus report` any time.
+
+## Notes
+
+- The hook is `|| true`: a collection failure must never interfere with your
+  session ending.
+- It writes only to `~/.agentabacus/agentabacus.duckdb` (or `$AGENTABACUS_HOME`).
+  Nothing is uploaded.
+- Other agent CLIs (Codex, Gemini) aren't covered by this hook — for those,
+  run `agentabacus collect` on a timer or before reporting.

agentabacus-0.1.0/plugin/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "agentabacus collect --quiet || true",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}