zolks 0.3.0

Cost observability for AI agents

Zolks

Local-first cost observability for AI tools. Open source, Python.

Two ways to capture AI API spend.

Fastest first run

pip install 'zolks[proxy]'
export ANTHROPIC_API_KEY=sk-ant-...
zolks try

Option 1 — The proxy (for CLI tools: Claude Code, Aider, Cursor, etc.)

pip install 'zolks[proxy]'
zolks proxy start

In another terminal:

export ANTHROPIC_BASE_URL=http://127.0.0.1:9191
claude-code "refactor this file"
aider

Then:

$ zolks top
agent               runs   tokens    cost     trend
claude-code         14     284K      $2.18    new
aider               3      42K       $0.31    new
python-sdk          21     119K      $0.94    new

Option 2 — The SDK (for Python apps you own)

pip install zolks

import zolks

zolks.init()

from anthropic import Anthropic

client = Anthropic()

with zolks.tag(agent="refund-bot", user_id="user_123"):
    client.messages.create(model="claude-opus-4-7", messages=[...])

The same zolks top command shows SDK and proxy events side by side.

How it works

The proxy is a local HTTP server that forwards Anthropic API calls and captures tokens, latency, and cost per request. Tools are identified by User-Agent. All data stays on your machine in ~/.zolks/events.db.

The SDK monkey-patches anthropic.Anthropic and tags calls with whatever zolks.tag(...) context is active.

Commands

• zolks proxy start — run the local proxy
• zolks try — one-command proxy + real Anthropic smoke test
• zolks top — top agents/users/features by cost
• zolks stats — totals for a time window
• zolks tail — live stream of new events

Status

0.3.0 — First release with a stable schema. Captures Anthropic API calls through either the local proxy or the Python SDK. Local SQLite storage with exact-precision cost tracking (nanodollars). Cloud sync planned for 0.4.

Streaming calls are captured as events without token counts (coming in 0.4). OpenAI support coming.

Roadmap: OpenAI -> streaming token capture -> anomaly detection -> hosted team dashboard.

License

MIT