AgentAcct
A local terminal ledger for coding-agent work, token usage, and estimated cost.
What does this agent do, and when should you use it?
AgentAcct is a local-first observability tool for coding-agent work, primarily reading session logs already written locally by Claude Code and Codex. Its `agentacct tui` command provides a live terminal dashboard for usage windows, provider limit reset bars, recent sessions, tokens, and estimated cost. It also combines agent-recorded work sections and machine-check evidence with usage data using real session or transcript IDs. Every attribution is labeled `exact`, `high`, `medium`, or `low`; when a link cannot be established, the dashboard shows the gap instead of inferring one. It runs from local state files and is documented as requiring no account, cloud sync, telemetry, or provider API key.
After agentacct onboard, AgentAcct detects local coding-agent logs, creates a global store, and performs an initial usage sync. It imports token data from client session files as client_reported and calculates explicitly labeled cost estimates from a local pricing table rather than provider invoices. Agents can record work through the MCP tools agentacct_record_section and agentacct_record_machine_check; machine checks can include command results such as test exit codes. agentacct tui renders the joined usage, cost, limits, and work ledger in the terminal: s opens sessions, u opens usage, and p saves the current view as an SVG snapshot. The local managed runtime is operated with agentacct start, status, stop, and repair.
- A Claude Code or Codex user who wants to inspect tokens, estimated cost, and recorded work for each local coding session.
- An engineer managing subscription limits who needs recent session activity alongside limit bars and reset countdowns.
- A reviewer checking whether an agent actually ran tests, using machine-check records and their exit codes in session detail.
- A privacy-conscious developer who needs coding-agent observability from local logs without creating an account or supplying a provider API key.
- A developer who wants to save a shareable rendering of a dashboard state as an SVG using the `p` shortcut.
What are this agent's strengths and limitations?
- Separates client-reported usage, agent-recorded work, and machine-check evidence before joining them with explicit attribution confidence.
- Labels token data as `client_reported` and costs as local pricing-table estimates instead of presenting estimates as invoices.
- Keeps state local and documents no account, cloud sync, phone-home telemetry, or provider API-key storage.
- Provides a terminal-first live dashboard with session drill-down, usage views, limit countdowns, and SVG snapshot export.
- The project is early alpha and its interfaces may change.
- Documented live-observed usage paths are currently for Claude Code and Codex; Hermes, OpenCode, OpenClaw, and Cursor have narrower capability-specific support.
- Costs are estimates rather than subscription invoices, and the weekly Claude plan percentage appears only after calibration from the user's recorded limit history.
- Adoption requires local session-log access and installation/integration setup; Windows support is limited to WSL.
How do you install or deploy this agent?
Runtime: Python 3.11 or later on macOS or Linux; Windows is supported only through WSL. No account or provider API key is required.
pipx install agentacct
agentacct onboard
agentacct tui
If pipx is not installed, use brew install pipx on macOS or python3 -m pip install --user pipx; uv tool install agentacct is also documented. onboard installs globally by default. For project scope, run agentacct onboard --scope project.
How do you use this agent?
Run agentacct onboard, then start a new agent session before using the dashboard. Launch agentacct tui to inspect local data; press s for sessions and session detail, u for usage, p to save an SVG of the current view, and q to quit. The default global state location is ~/.local/state/agentacct/state; project-scoped installs use .agent-sentinel/ in the repository. For a disposable walkthrough that does not use real data, run agentacct demo.