agentacct: A Local-First Work Receipt for Claude Code, Codex, and OpenCode

The Problem: Agent Output Without an Audit Trail

Coding agents like Claude Code and Codex produce a stream of commands, file edits, and test runs, but the average developer has no structured way to answer two questions: what did the agent actually do, and what did it cost? Terminal scrollback is not an audit record. Agent logs are verbose and inconsistent across tools. agentacct addresses this by reading the session logs that agents already write on disk, joining them with the work each session records as it goes, and turning the result into a per-task Work Receipt. The target user is an individual developer or a small team that wants accountability without sending data to a hosted service. The README is explicit: no login, no telemetry, no account, and the only listener is a loopback-only JSON API on 127.0.0.1. That privacy posture is the product's reason to exist.

How It Works: Reading Local Logs and Joining Them to Work Steps

agentacct does not intercept or modify your agent's behavior. It reads the session logs your agents already write, then joins them with the work each session records as it goes. The architecture is visible in the README: onboarding detects local coding-agent logs, sets up a global store, and runs a first usage sync. A managed background sync then keeps the store current. The local JSON API on http://127.0.0.1:8765 is the machine-readable lane that native shells and scripts poll. The key mechanism is the Work Receipt: each task gets actions (commands run, files touched), cost, evidence, outcome, gaps, and per-field provenance. Every fact is labelled with its source: a client hook, a transcript scan, or the agent's MCP records. The important design choice is that decision and evidence stay separate. An agent reporting 'done' never raises the evidence bar. A task only reads 'Verified' when every live check passes and postdates the newest recorded work. That separation is what makes the receipt an audit record rather than a vibe.

Evidence Tiers: The Heart of the Trust Model

The README defines a clear hierarchy: an agent's own claim is the weakest, then a self-reported check, then a hook-observed exit code, then CI. Each tier has a distinct pip shape: hollow, half, filled, and ringed. Green is reserved for live connections and externally verified evidence. The Sources pane shows per-source import health, the background sync, and a verifier shelf for CI check runs and human review. That shelf stays honestly labelled 'not connected' until independent evidence actually lands in the store. This is a deliberate design choice that rejects the common pattern of letting an agent's own assertions count as verification. The trade-off is that you must set up independent checks to get the higher tiers. Out of the box, you will see mostly hollow pips unless you have hooks and CI configured. The documentation does not claim that agentacct can verify anything by itself; it only grades what evidence exists. That honesty is a strength, but it also means the tool's value depends on the rigor of your existing test setup.

Getting It Running: Onboard, TUI, and the macOS App

Installation is straightforward for a Python CLI. The README gives the primary path: `pipx install agentacct`, then `agentacct onboard` once per machine, then `agentacct tui` for the live terminal dashboard. Python 3.11 or newer is required on macOS or Linux, and Windows is only supported via WSL. If you do not have pipx, you can use `uv tool install agentacct` or a plain venv fallback described in INSTALL.md. The macOS app is a signed, notarized .dmg that bundles everything and requires macOS 14+. On first launch it installs the bundled CLI and instruments the coding agents it finds. A critical operational detail: MCP servers and hooks bind at session start, so the session that runs onboarding cannot become the first recorded task. You must open a new agent session after onboarding for that session to be captured. The README also supports a per-repo install with `agentacct onboard --scope project`, which writes zero files into your repo when using the global default. That is a concrete, testable behaviour you should verify in your own environment.

Cost Tracking: Reported, Estimated, and Calibrated

Cost is a central feature, and agentacct is careful about the basis of every figure. The README states that tokens come from the clients' local session files, and costs keep their reported, estimated, or partial basis. A bare `$` is reserved for reported figures, while `≈` marks an estimate. There is no fabricated zero and no invoice. The beta feature for Claude plan usage is more interesting: agentacct estimates what fraction of your weekly Claude plan each task consumed. It does this by learning the rate from your own recorded limit history, because different models burn the plan at different rates. The tool shows a figure only once it can calibrate to your account; until then it says it is still calibrating. That is a sensible refusal to guess. The limitation is that this calibration depends on your usage history being present and consistent. If you switch accounts or reset your plan, the calibration will be wrong until new history accumulates. The README does not specify how long that takes, so expect a cold-start period.

Attribution and the Honest Gap

Every join between usage and recorded work carries a confidence label: exact, high, medium, or low. The README states the principle: missing attribution beats wrong attribution. When agentacct cannot prove a link, it shows the gap instead of a guess. Absence is always a named state, never a dash or a fabricated zero. This is a strong design choice for an audit tool, because it prevents the dashboard from looking complete when it is not. The practical consequence is that you will see gaps in your receipts, and you must learn to read them as evidence of missing data rather than as failures. The trade-off is that the interface can feel cluttered with named gaps. A less honest tool would hide them. For an engineer who wants to know whether an agent actually did what it claims, the explicit gap is the more useful behaviour. The README also mentions a checks column with real pass/fail tallies, which suggests that agentacct surfaces the results of machine checks, but the exact mechanism for those checks is not detailed in the material.

Limitations and the Wrong Tool Cases

agentacct is not a universal agent monitor. It supports only Claude Code, Codex, OpenCode, and Hermes, and it depends on those agents writing session logs in a format agentacct can parse. If your agent version changes its log format, the import may break until a new release. The README does not mention any fallback for unsupported agents. Windows users are limited to WSL, which may be a dealbreaker for some. The onboarding flow has a sharp edge: the session that runs onboarding cannot become the first recorded task, so you must remember to open a new session. That is easy to forget and can lead to confusion about why no tasks appear. The evidence tiers are only as good as your hooks and CI; without them, you get mostly hollow pips, which is honest but not very informative. The tool is also local-only, so there is no multi-user collaboration or remote access. If you need a team-wide audit trail or a hosted dashboard, this is the wrong tool. The README does not claim to support those use cases, so this is a boundary, not a flaw.

Alternatives and the Difference in Approach

The obvious alternative is to use the built-in logging and usage reporting that each agent provides. Claude Code has its own session transcripts and cost summaries, and Codex has similar features. The difference is that those are per-agent and per-session, with no unified view across tools and no evidence grading. agentacct aggregates across four agents and adds the evidence tier system, which is its unique contribution. Another alternative is a general-purpose terminal recorder or a custom script that parses logs and computes costs. That gives you full control but requires you to build the join logic, the evidence grading, and the UI yourself. The trade-off is effort versus structure. agentacct gives you a ready-made structure, but you inherit its assumptions about log formats and its evidence model. A custom script can adapt to your exact setup, but it will not have the polish of the TUI or the macOS app. The README also mentions a verifier shelf for CI and human review, which suggests that agentacct can integrate with external checks, but the material does not specify how to connect those. That is a gap you would need to explore in the documentation or source code.

Maintenance, Upgrade, and Licence Considerations

The project is under active development, with three releases in three days around the last push date: v0.10.0, v0.10.1, and v0.10.2. That cadence suggests a fast-moving project, which is good for bug fixes but also means you should expect frequent updates and potential breaking changes. The README does not mention a migration path between versions, so you should check the changelog before upgrading. The licence is MIT, which is permissive and allows commercial use, modification, and redistribution with attribution. There are no obvious copyleft obligations. Since agentacct stores state as plain local files, upgrading should not require a database migration, but the README does not confirm that. The maintenance cost for you is low: the tool runs as a background sync and a local API, and you do not need to host anything. However, you are responsible for keeping the tool updated and for ensuring your agent log formats remain compatible. The lack of a hosted service means no one else is monitoring the health of your store; you are on your own if something breaks. The README does not describe a repair or reset command beyond `agentacct stop` for the API, so you may need to inspect the store manually in case of corruption.

Editorial conclusion

Adopt agentacct if you run Claude Code, Codex, OpenCode, or Hermes on macOS or Linux, want a local-only audit trail of what agents did and spent, and can accept that evidence tiers depend on the hooks and CI you configure. Do not adopt it if you need Windows support outside WSL, if you expect zero-config verification, or if you want a hosted multi-user team view. Before committing, verify that your agent versions write session logs in the formats agentacct expects, and test `agentacct onboard` on a scratch repo, because onboarding instruments agents at session start and the session that runs onboarding cannot become the first recorded task.

Official sources

1. Official README
2. Project repository
3. Release notes