Telemetry & budget
Local-only telemetry in a SQLite store on your disk — tokens, cost, steps, tool calls, files, memory, reflections — and how --budget turns metering into a hard spend cap.
Stella meters every run locally. Token usage, cost, and per-step accounting land in a SQLite store on your disk — nothing is sent anywhere.
Local metering
Everything lands in one SQLite file: <workspace>/.stella/store.db. Because the store is
a real SQLite file, you can inspect it with any SQLite client after a run — e.g.
sqlite3 <workspace>/.stella/store.db — and every execution, its model, and its cost are
queryable on your own machine. WAL is enabled, so a read-only reader like
stella stats is never blocked by a live session. Stella never
transmits this data.
What's in the store
Metering is only part of it. The store owns 17 tables — a full record of what each run did, not just what it cost — and the Observatory reads these same tables:
| Table | What it records |
|---|---|
executions | One row per run / goal / chat turn — kind, prompt, provider/model, outcome, cost. The spine every other table keys off |
events | The full, ordered event stream of each execution — replayable, reasoning deltas included |
telemetry | One row per model call: input/output tokens, cache read/write/miss, cost, latency, retries |
files_touched | The per-execution file-touch ledger — CRUD letters, line deltas, JSON audit log (details) |
tool_calls | One row per tool call (native, MCP, skill, or agent) — shape, timing, success, bytes returned |
mcp_usage | Per-call MCP log: server, tool, reason, call time |
skill_usage | One row per skill applied in a turn, with the skill's pinned version |
agent_uses | One row per invocation of an installed agent definition, with its pinned version |
memory_citations | Recall receipts: per memory cited in a turn, its usefulness score and truthfulness verdict |
rules | Promoted workspace rules — the full rule markdown, one row per rule |
reflections | Durable lessons and self-critiques, tagged by domain |
execution_reflection | The post-turn self-review, tied 1:1 to its execution |
tasks | The latest task-board snapshot, one row per task per session |
pull_requests | Tracked pull requests — status and CI verdict, keyed by URL |
file_locks | Cooperative file claims for multi-agent work |
graph_nodes / graph_edges | Reserved schema for a future context-plane seam — the code graph itself lives in .stella/codegraph.db |
Budget: observed vs. enforced
The --budget flag (or the STELLA_BUDGET environment variable) attaches a USD spend
limit to the whole run or session.
- Observed mode (default, no
--budget) — Stella meters spend for the end-of-run cost summary but never blocks. Use it to see what a task costs. - Enforced mode (
--budget <usd>) — a hard cap. Once total spend exceeds the limit, work aborts cleanly — never in the middle of a tool call — so you are never left with a half-applied edit.
# Observed: meter the cost, never block
stella run "summarize the architecture of this repo"
# Enforced: stop cleanly once spend passes $2.00
stella --budget 2.00 goal "all tests pass and clippy is clean"
# Via environment, e.g. in CI
export STELLA_BUDGET=5
stella run "port the utils module to the new API"The budget must be a positive, finite dollar amount. It applies to the entire run or interactive session, not per turn.
Cost summary
Every run ends with a cost summary derived from the same metering that feeds the local SQLite store, so the number you see matches what was recorded locally.
Seeing your usage
Three ways to read the telemetry back, all local:
stella observe— the Observatory, a loopback-only web dashboard (defaulthttp://127.0.0.1:7787/): runs, spend, resolve rates, $/resolved per model, tool and file leaderboards, the memory plane, MCP traffic, and the fleet ledger.stella stats— the same per-provider/model aggregation in the terminal, as a table, JSON, or CSV./export(in the Command Deck) — a portable ZIP with raw JSON dumps and a self-containeddashboard.htmlreport. See the dashboard page.
Every file it reads, creates, updates, or deletes is also recorded per run — see Files touched.
Permissions
How Stella's per-tool permission model separates read-only tools from mutating and shell tools, and how PreToolUse hooks can gate or block tool calls.
The Observatory dashboard
stella observe opens a local, loopback-only web dashboard over your workspace telemetry — runs, spend, models, tools, files, memory, MCP traffic, and the fleet ledger. Plus /export for a portable HTML report.