AgentObs
Open source · MIT
Most Claude Code tools only report what you already spent, and the few that enforce stop at a dollar figure. AgentObs enforces before the call runs — on tokens, on a rolling rate-limit window, on dangerous commands.
npm install -g @klars/agentobs
Requires Node 22.5+. Runs entirely on your machine — no account, no signup.
npm install -g @klars/agentobs
agentobs init
init writes the Claude Code hooks for you (backing up your
settings first), adds starter guardrails, and imports your existing
history — so the dashboard has data immediately.
Nothing to copy or paste.
agentobs budget set --daily 5 --block
agentobs budget set --block5h 200000 --tokens
--block refuses further tool calls at the limit. On a
subscription the constraint is not dollars but your rolling 5-hour
window, so a budget can be denominated in tokens instead.
agentobs forecast“At $4.14/hour you hit the limit in 44 min.” A forecast needs the limit as well as the usage — which is why a tool that only reports usage cannot tell you this.
agentobs dashboardRuns at 127.0.0.1:4300. Nothing leaves your machine.
A needs_approval rule holds the call and notifies you.
Approve it and the agent's retry succeeds — scoped to that exact call,
so approving rm -rf ./build never authorises
rm -rf /.
claude mcp add agentobs -- agentobs mcp — then ask Claude
“am I close to my limit?” and it answers from your real local data.
5h 78% · $2.00/$5.00 → 44 min · ctx 43%
Your real rate limit, the tightest budget, and a countdown.
A statusline render is 0.6ms through the optional warm daemon. Everything works without it — the daemon is a pure optimisation.
agentobs agents --import reads Copilot CLI, Codex, Gemini
CLI and OpenCode logs. Add one we have never heard of with a JSON
definition — no code.
agentobs notify set <url> sends a breach to Slack, Discord or
your own endpoint. Opt-in, no default destination, and the payload carries
numbers — never your tool inputs.
The dashboard surfaces hints from your own data — a tool failing often, a call repeated with identical input, a session large enough that re-sent context dominates the bill. Each names the number behind it.
An unpriced model shows —, never $0.00. An
unverified log format says so rather than silently recording nothing.
The tooling space is well served for reporting, and a couple of tools now block on a dollar figure. Nothing else enforces the other four things that actually stop a run going wrong.
| Capability | Cost trackers |
Claude Code built-in |
Budget blockers |
Security hooks |
Team gateways |
AgentObs |
|---|---|---|---|---|---|---|
| Seeing what happened | ||||||
| Cost & token reporting | Yes | Yes | Yes | No | Yes | Yes |
| Agents supported | 16+ | 1 | 1 | 1 | – | 5 |
| Web dashboard | No | No | No | Partlysome | Yes | Yes |
| Status-bar integration | Partlysome | Yes | Partlysome | No | No | Yes |
| Stopping it before it runs | ||||||
| Blocks on a dollar limit | No | Partlyone run | Yes | No | Yes | Yes |
| Blocks dangerous commands | No | No | No | Yes | No | Yes |
| Blocks on a token budget | No | No | No | No | No | Yes |
| Limits that outlive the session | No | No | Yes | No | Yes | Yes |
| Blocks on your 5-hour window | No | No | No | No | No | Yes |
| Approvals scoped to the exact input | No | Partlyprompt only | No | No | No | Yes |
| Knowing before it happens | ||||||
| Forecasts when you’ll run out | Partlysome | No | No | No | No | Yes |
| Alerts to Slack or Discord | No | No | No | No | Yes | Yes |
| The agent can query its own usage | No | No | No | No | No | Yes |
| Practicalities | ||||||
| Useful on a subscription plan | Yes | Yes | Partlyinert | Yes | No | Yes |
| Team-wide limits | No | No | No | No | Yes | No |
| No proxy or API-key change | Yes | Yes | Yes | Yes | No | Yes |
| Secret redaction, unit-tested | No | No | No | No | Partlyvaries | Yes |
Who each column is. Cost trackers:
ccusage,
Claude Code
Usage Monitor. Built-in: /usage and
--max-budget-usd. Budget blockers:
cost-guardian. Security
hooks: claude-code-hooks.
Gateways: LiteLLM, Portkey, Bifrost.
Use something else when it fits better. If you only want reporting,
ccusage is excellent and reads 16+ agents to our 5. If you need one limit across a
team, a gateway does that and we do not. If a single scripted run is all you cap,
Claude Code’s own --max-budget-usd is free and already installed
— though it is print-mode only, one session, and gone when the process exits.
AgentObs is for the rest: a limit that survives the session, denominated in tokens when your plan has no dollar cost, plus the command policy and approvals that a spend cap cannot express and a gateway never sees.
Guardrails are evaluated inside the same hook that does the logging, so a blocked call never executes. Check exactly what a rule will do before it fires mid-task:
A model missing from your pricing table shows —, never
$0.00. One wrong number and you stop trusting all of them.
Process-wrapped sessions are labelled coarse. The UI never implies
detail it doesn't have.
A malformed policy degrades to allow-everything and says so. A guardrail that wedges your agent is worse than none — but it does mean that in that state, nothing is blocked.
Rules match tool inputs textually, budgets are checked between calls, and nothing is enforced where hooks do not run. Set a small limit and confirm it blocks on your machine — see the limits.
AgentObs sits in the middle of everything your agent does. That only works if it is trustworthy by construction, not by promise.
KEY=value pairs, Authorization: headers and URL
credentials.
rm -rf ~/.agentobs. That is the entire
footprint.
agentobs budget set --daily 5 --block. Once the limit is reached,
AgentObs refuses further tool calls rather than reporting the overspend after the
fact. Periods are daily, weekly, monthly, or the rolling 5-hour block that matches
Anthropic’s own rate-limit window.
ccusage is read-only, and good at it — it parses the same local transcripts and reports what you already spent. AgentObs asks for your limit, which is what makes refusing a call and forecasting possible; both need the limit, not just the usage. A couple of tools do block, but on cumulative dollars alone — AgentObs also enforces token budgets, rolling 5-hour windows, command policy and approvals.
Yes, and this is the case dollar-denominated tools cannot serve. Budgets can be
set in tokens:
agentobs budget set --block5h 200000 --tokens. On a subscription your
real constraint is the rate-limit window, not a bill.
Because that figure is what your usage would cost on the API, not what
you were charged. AgentObs detects your plan and labels it
“API-equivalent usage” on a subscription, keeping “Spend”
for API keys where it is real money. The number looks large because cache reads
dominate — every turn re-sends the whole conversation, and on one measured
session 99.3% of all tokens were cache reads. On a subscription, cap the thing
that actually binds you:
agentobs budget set --block5h 200000 --tokens.
No. One SQLite database under ~/.agentobs. No account, no API key, no
telemetry. Optional alerts are the one outbound path and are off until you
set one. Secrets are redacted before anything is written, and
those rules are unit-tested.
Claude Code is verified against real transcripts. Copilot CLI, Codex CLI, Gemini CLI and OpenCode ship as declarative log-source definitions marked unverified until someone confirms them against real files — claiming support that silently records nothing is the worst thing an observability tool can do. You can add an agent we have never heard of with a JSON definition and no code.
Yes. Glob rules match tool inputs and deny before execution — rm -rf /,
reads of .env, whatever you add. A needs_approval rule
holds the call for you instead, scoped to a fingerprint of the tool name and its
exact input, so approving rm -rf ./build never authorises
rm -rf /.