mikehasa/agentacct

agentacct – Honest Work Receipts for your coding agents

What it is – A local‑first utility that watches the log files that AI‑coding assistants (Claude Code, Codex, OpenCode, Hermes, etc.) already write on your machine, stitches those logs together with the actual commands, file edits and tool calls the agents performed, and produces a single Work Receipt for each task. The receipt shows what was done, how much it cost, and how trustworthy the evidence is (agent‑claimed, self‑checked, hook‑observed, CI‑verified). All data stays on your computer; there is no cloud service, telemetry, or API‑key handling.

---

Core concepts

Concept	Meaning
Work Receipt	An audit‑style record per task that lists actions, cost, and an evidence tier for each claim.
Evidence tiers	Four grades – agent claim < self‑reported check < hook‑observed exit code < CI – visualised as pip shapes.
Local JSON API	A loop‑back‑only HTTP server (127.0.0.1:8765) that other scripts can query for receipts.
macOS app / TUI	Two front‑ends (native macOS GUI and a terminal dashboard) that render the same receipts.

---

What you get

• One receipt per task – shows actions (commands, files touched, tools used), cost (real token count + pricing‑table estimate), and a clear decision/evidence split.
• Drill‑down view – expand a receipt to see every session step, its lifecycle, exit‑code checks, and provenance chips (hook, transcript, MCP record).
• Evidence‑first dashboard – the top‑most task that needs review is highlighted, with a Review evidence button and a concise “Shift Brief”.
• Usage & plan cost – live provider quota windows, recorded token usage, and an estimated share of your weekly Claude plan (derived from your own limit history).
• Attribution confidence – each join between usage and work is labelled exact, high, medium or low; missing links are shown explicitly rather than guessed.
• Privacy‑by‑design – all state lives in plain local files (~/.local/state/agentacct/ or a repo‑local .agent-sentinel/), the only network listener is the local JSON API, and no keys are ever stored or transmitted.

---

Installation

Platform	Steps
macOS (GUI)	Download the notarized .dmg from the latest release, drag to Applications, launch. The app bundles the CLI and auto‑onboards your agents.
macOS / Linux (CLI)	```bash
pipx install agentacct # or uv tool install agentacct
agentacct onboard # detects agents, creates global store, starts sync & API
agentacct tui # live terminal dashboard

| **Windows** | Use WSL and follow the macOS/Linux CLI steps. |

*Onboarding* writes zero files into your repos, only creates a global store and registers hooks in the agents’ configuration files so that future sessions are captured.

---
### Typical workflow
1. **Onboard** once per machine (or per‑project with `--scope project`).
2. Run your usual AI‑coding agent (Claude Code, Codex, etc.). The agent’s own logging hooks write session files.
3. `agentacct tui` (or open the macOS app) – the Dashboard shows the highest‑priority task that needs review.
4. Press **Enter** on a receipt to see the full audit record, drill into sessions/steps, and examine the evidence tier for each claim.
5. If you need programmatic access, query `http://127.0.0.1:8765/receipts` (or similar endpoints documented in `docs/reference.md`).
6. When finished, stop the background sync with `agentacct stop`; uninstall with the commands shown in the README.

---
### How it works (high‑level)
- **Usage truth** – pulled directly from each agent’s local session files (token counts are `client_reported`; costs are derived from a built‑in pricing table).
- **Work meaning** – collected from MCP events that agents emit (`agentacct_record_section`, `agentacct_record_machine_check`) plus any independent checks (test runs, CI).
- **Join** – receipts are built by matching client IDs, session IDs and transcript IDs, then labeling each attribution with a confidence level.
- **Evidence tier pip** – visual indicator derived from the independence grade of the underlying check.

---
### Who should use it
- Developers who rely on AI coding assistants and want an **audit trail** for cost control and trust verification.
- Teams that need to **prove** that an AI‑generated change was actually run and passed tests before merging.
- Anyone concerned about **privacy** and wants a completely local view of token usage without sending data to a SaaS dashboard.

---
### Current status
- Early alpha – features may change.
- Supports Claude Code, Codex, OpenCode (full receipts), Hermes (usage + limited capture), OpenClaw (usage only), Cursor (presence only).
- macOS GUI and full‑terminal TUI are functional; Linux users get the TUI.

---
### Links & docs (as listed in the repo)
- **Reference** – `docs/reference.md`
- **Install run‑book** – `INSTALL.md`
- **Usage & cost truth table** – `docs/usage-truth-table.md`
- **Architecture & safety** – `docs/architecture.md`, `docs/safety-boundaries.md`
- **Full demo** – `docs/full-demo.md`

---
### Quick start example
```bash
# Install the CLI
pipx install agentacct

# Set up the global store and start background sync
agentacct onboard

# Open the terminal UI
agentacct tui

Now run a Claude Code session in any repo; the dashboard will immediately list a receipt for the new task.

---

Bottom line: agentacct gives you a transparent, locally stored ledger of what your AI coding agents actually do, how much they cost, and how solid the evidence is—without any cloud‑side components.