Repository navigation
How it works
toard turns local AI-tool usage into normalized events, then calculates and presents usage from one server you operate.
flowchart LR
subgraph machine[Developer machine]
tools[AI coding tools]
files[Local session files]
shim[toard shim]
tools --> files
files -. default pull collection .-> shim
end
shim -- authenticated usage events --> api[Event API]
subgraph server[toard server]
api --> trust[Token attribution and validation]
trust --> pricing[Usage normalization and cost calculation]
pricing --> storage[StorageBackend]
end
storage --> postgres[(Postgres: default)]
storage --> clickhouse[(ClickHouse: optional)]
postgres --> dashboard[Personal, team, and organization dashboards]
clickhouse --> dashboard
The shim wraps supported command-line entry points and can also run collection on a schedule. It parses changed local session files into normalized usage events. The scheduled collector is useful for Desktop or IDE activity that may not pass through the command wrapper.
Collection uses cursors so unchanged files are not repeatedly sent. If a file must be parsed again, server-side deduplication protects the stored event set.
The shim sends events with a Bearer ingest token. That token is the basis for user attribution. Client-supplied user and cost fields are not authoritative: the server assigns the user and calculates cost before persistence.
The shim can attach a device label for a user's own device breakdown. A user may set an alias or disable this label; it is display metadata, not a replacement for token authentication.
Postgres is the default storage backend. ClickHouse is optional when event and aggregation scale warrant it; authentication and other account metadata still use Postgres. The dashboard presents the resulting data for individual, team, and organization views.
The flow above is the default: local session-file pull to the event API. It is designed to collect usage without telemetry environment injection or application restarts.
OTLP push is experimental. It is only relevant when the experimental shim setting is enabled and the server-side provider is configured for OTLP collection. Keep one collection method active per provider so the same usage is not recorded twice.
Usage collection does not turn on prompt or response storage. Content collection has a separate endpoint, cursor, user-level setting, and server-side encryption requirement. It is off by default, but an organization can deliberately use CONTENT_COLLECTION_DEFAULT=on to make the installation flow opt-out instead; review and communicate that policy before considering it. See Privacy-and-security.