AgentAcct
A local terminal ledger for coding-agent work, token usage, and estimated cost.
- Source repo
- mikehasa/agentacct
- Stars
- ★ 755
- Last updated
- 1mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 61/100 · Some gaps
At a glance
- How it runs
- Works with
- Portable with changesCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A Claude Code or Codex user who wants to inspect tokens, estimated cost, and recorded work for each local coding session.
- Not a fit if
- Teams needing native Windows support (WSL only)
- Production users needing stable interfaces (early alpha)
- Teams needing exact subscription invoices, not estimates
- Source review
- 61/100 · Some gaps
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
pshortcut.
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 tuiIf 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.
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_reportedand 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 does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| AgentAcct This agent | 61 · Some gaps | CLIFree | ★ 755 | 1mo ago | Python | Codex · Claude Code |
| Frink — Local AI Workflow Automation for Your Desktop | 50 · Major gaps | Desktop appFree + model costs | ★ 181 | 11d ago | TypeScript | Codex · Claude Code |
| cost-xray | 65 · Some gaps | CLIFree | ★ 5.8k | today | Python | Codex · Claude Code · OpenAI API · Claude API |
| ClawMetry | 81 · Good | CLIFreemium | ★ 436 | 4d ago | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: project emphasizes local-first, no telemetry, no API key storage, and least privilege (e.g., only reads local session files, does not scan unrelated processes). User confirmation: installation and configuration require explicit user actions, and exact commands are shown before modifying global config. Data flow transparency: documentation details data flow and privacy model. Sensitive data handling: clear secret handling guidelines and redaction. Dependency security: common dependencies but no vulnerability scanning or lock files. External effects: explicitly limited to controlling only self-started processes, with safety boundary docs. Rollback: uninstall and cleanup instructions provided. Source attribution: clearly distinguishes client-reported and estimated values. Deductions: dependency security lacks concrete evidence like lock files or vulnerability scanning.
Self-consistency: documentation and code comments consistent, tests comprehensive. Dependency availability: dependencies are common libraries but no version locking or mirrors. Failure messages: tests and docs show clear error messages and recovery suggestions. Deductions: dependency availability lacks concrete safeguards.
Audience and scenarios: clearly for developers, supports multiple coding agents. Capability boundaries: docs clearly list support levels for each client. Trigger precision: records work steps precisely via MCP tools and hooks. Environment fit: supports macOS and Linux, Windows via WSL. Deductions: no major issues.
Information architecture: clear documentation structure with reference and install guides. Install notes: multiple installation methods. Naming stability: project name and commands stable, but legacy names supported. Examples and FAQ: demo and common questions provided. Known limitations: clearly states early alpha. License: MIT. Versioning and changelog: version number but no detailed changelog. Maintenance responsibility: contribution guide and feedback channels. Deductions: naming stability slightly deducted due to legacy name compatibility, changelog not detailed.
Output usability: provides terminal dashboard and SVG snapshots. Marginal value: provides cost estimation and work step recording, unique value. Cost-benefit: runs locally, no extra cost. Deductions: no major issues.
Claim traceability: documentation and tests correspond. Cross-source corroboration: tests cover multiple scenarios but no external verification. Fact-inference separation: clearly distinguishes client-reported and estimated values. Deductions: cross-source corroboration insufficient.
- Dependency security: no lock files or vulnerability scanning, recommend using lock files and regular checks.
- Changelog not detailed, recommend adding.
- Cross-source corroboration insufficient, recommend adding external verification or independent testing.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.12.11 agentacct 0.12.11
Release notes excerpt
Download [Download agentacct 0.12.11 for macOS (Apple Silicon, macOS 14+)](https://github.com/mikehasa/agentacct/releases/download/v0.12.11/agentacct-0.12.11.dmg) What's changed Two Claude accounts on one machine no longer read as one client's contradictory meters: every provider-limit reading is labeled with the account and source it belongs to. (#355) - The macOS Usage page, the TUI, and agentacct limits label each reading — CLI · [email protected], desktop app · org 07c55a50 — so a second account's Weekly meter can no longer be mistaken for the first account's. …View on GitHub ↗ -
v0.12.10 agentacct 0.12.10
Release notes excerpt
macOS app [Download agentacct 0.12.10 for macOS](https://github.com/mikehasa/agentacct/releases/download/v0.12.10/agentacct-0.12.10.dmg) Fixed - Recovery notifications no longer accumulate behind identical banners. A recurring source issue replaces its previous recovery banner, and recovered notices disappear after ten seconds. - Recovery titles identify the affected client and issue. Recent updates keeps the recovery history, while active faults remain visible until dismissed or confirmed recovered. …View on GitHub ↗ -
v0.12.9 agentacct 0.12.9
Release notes excerpt
Codex's gpt-6.1-sol usage rows are priced instead of importing cost-unknown. Nothing else changed. macOS app (no Python, pipx, or terminal needed): [agentacct-0.12.9.dmg](https://github.com/mikehasa/agentacct/releases/download/v0.12.9/agentacct-0.12.9.dmg) — signed, notarized, and stapled, built from this release's own commit. The app embeds the frozen agentacct CLI, so the DMG is rebuilt here even though no Swift file changed: the fix lives in the CLI, and reusing the 0.12.8 DMG would have shipped the old price table and silently dropped it. …View on GitHub ↗
FAQ
Does AgentAcct need a provider API key or billing access?
Does it send my session data to a hosted service?
http://127.0.0.1:8765.