TALLYGRAPHUNIFIED SPEND CONSOLE

How it works

What the CLI reads, what it sends, and how delivery stays safe when the network fails.

The work is split in two. Everything that touches your files runs on your machine. TallyGraph only receives normalized usage records over HTTPS, authenticated with your write token.

YOUR MACHINETALLYGRAPHread-onlyHTTPSAgent history4 local agentstallygraph CLIread, normalize, spoolIngest APIvalidate, dedupeDashboardspend by model
The boundary is the HTTPS call. Prompts, responses and code never cross it.

One collect run

Discoverknown pathsReadv2 usage eventsSpoolSQLite, ~/.tallygraphSendbatches of 100Ingest APIdedupe by external_id
Rows leave the spool only after the API accepts them, so a failed run loses nothing.
  • Discover. Checks the default path of each supported agent.
  • Read. Parses the history and builds one event per model call: model, tokens (input, output, cache read, cache write), time and a stable external_id.
  • Spool. Writes the events to a local SQLite queue in ~/.tallygraph (or TALLYGRAPH_STATE_DIR), capped at 100,000 pending rows.
  • Send. Posts batches with Authorization: Bearer and retries up to five times. Accepted rows are removed. Rows the API rejects as invalid are set aside with the reason, so one bad row cannot block the rest.
  • Ingest. The API validates every field and counts repeated external_id values as duplicates instead of storing them twice. Running collect again is always safe.
  • Report. After a successful delivery the CLI posts a runtime report (install id and versions) so the workspace can flag bad runtimes. A failed report warns but leaves the exit code at 0.

What is sent and what stays local

Sent to TallyGraphStays on your machine
Model name and providerPrompts and responses
Token counts and costSource code and file contents
Timestamp, session and request idsTool inputs and outputs
Names of the tools used (for example Edit, Bash)Full paths and git branch, unless you pass --include-paths
Project folder name (last segment only)API keys and credentials
Runtime versions (this CLI, Node, the agent CLIs) and a random install idYour name and email

This is enforced on the server too. Metadata is limited to 8 KB, and the API rejects any event whose metadata contains keys such as prompt, messages, content, transcript or apikey.

Service mode

at loginHTTPSOS schedulerlaunchd, systemd, schtaskscollect --watchevery 15 minIngest APIsame as a manual run

service install registers collect --watch with the native scheduler: a launchd agent on macOS, a systemd --user unit on Linux, a Task Scheduler task on Windows. It runs as you, not as root. Change the period with --interval (seconds, minimum 30).

Live capture with tap

The history files are enough for most people. If an agent does not keep usage locally, or you want it in real time, tallygraph tap starts a small local proxy and points the client at it.

BASE_URLsame requestYour clientclaude, codex, opencodetallygraph tap127.0.0.1, random portProvider APIAnthropic or OpenAI
The tap forwards each request unchanged and records only the usage counters from the response.
terminal
tallygraph tap -- claude
# or, for any client:
tallygraph tap --provider openai --no-launch
export OPENAI_BASE_URL=http://127.0.0.1:<port>