Site

# tu — agent usage bundle

`tu` is a command-line tool that reports AI coding-assistant token cost and usage
on the machine it runs on. It reads local usage data (via a vendored `ccusage`)
and, in multi mode, aggregates across machines through a shared git repo.

This is a usage briefing for an agent operating an installed `tu`: when to reach
for it, what each command does, how it composes, and how to read its output.

## When to use

Reach for `tu` to answer cost/usage questions about AI coding assistants on
**this machine**:

- "How much did Claude Code / Codex / OpenCode / Gemini / Copilot / Kimi cost today?"
- Daily, weekly, or monthly spend, as a snapshot or as history.
- Per-machine breakdowns (multi mode) and per-user views.

Do NOT reach for `tu` for:

- Billing management or payment — it only reports usage, it changes nothing.
- Tools it does not track (only the six sources below).
- Per-request granularity beyond what `ccusage` emits — `tu` aggregates by day.

## Capabilities map

### Data grammar: `tu [source] [period] [display]`

- **source** — `cc` (Claude Code), `codex`/`co` (Codex), `oc` (OpenCode),
  `gemini`/`gem` (Gemini), `copilot`/`cop` (Copilot), `kimi`/`ki` (Kimi);
  omit for `all` (default).
- **period** — `d`/`daily` (default), `w`/`weekly`, `m`/`monthly`.
- **display** — bare = snapshot (current period); `h`/`history` = time series;
  `lb` = leaderboard (users ranked by cost/tokens, multi mode); `lbh` =
  leaderboard history (period rows x user columns, multi mode).
- **combined shorthands** — `dh` (daily history), `wh` (weekly history),
  `mh` (monthly history).

Examples: `tu` (today, all), `tu cc` (today, Claude Code), `tu h` (daily history
pivot), `tu cc mh` (Claude Code monthly history), `tu wh` (weekly history),
`tu m lb` (this month's leaderboard), `tu lbh` (daily leaderboard history).

### Non-data commands

- `tu init-conf` — scaffold `~/.config/tu/tu.conf`.
- `tu init-metrics [url]` — clone the metrics repo (multi mode); with `url`, also
  writes `metrics_repo` into `~/.config/tu/tu.conf` first.
- `tu sync` — push/pull metrics manually (multi mode).
- `tu status` — show config and sync state (reports single vs multi mode).
- `tu update` — update `tu` via Homebrew.
- `tu shell-init <bash|zsh|fish>` — emit a shell completion script for `eval`.
- `tu help` (or `-h`/`--help`) — full help text.
- `tu help-dump` — emit a machine-readable help contract (JSON) for tooling.
- `tu skill` — print this bundle (agent usage briefing) to stdout.

## Composition patterns

- **Shells out to `ccusage`** (vendored) to read local usage data — no separate
  install needed; a single `ccusage` binary serves all six sources.
- **Shells out to `git`** in multi mode to sync per-machine metrics through a
  shared repo, so cost aggregates across machines.
- **Shells out to `brew`** for `tu update` (Homebrew-installed builds only).
- **Is shelled out to** by shll.ai's pull cron, which runs `tu help-dump`
  against the installed binary to render tu's command reference on shll.ai.
- **`tu skill`** (this bundle) also renders at `/tu/skill` on shll.ai and is the
  surface a future `shll agent-setup` will aggregate into agent context.

## Output & exit-code contract

- **stdout is data; stderr is diagnostics.** Parse stdout; treat stderr as
  warnings/errors. Success writes results to stdout with nothing on stderr.
- **Exit codes:** `0` on success; `1` on operational failure (network, git,
  Homebrew, missing/misconfigured metrics repo — retry or fix the
  environment); `2` on usage error (bad grammar, unknown tool/shell,
  incompatible flags, bad flag values — fix the command line).
- **Graceful degradation:** when a data source is unavailable, `tu` warns on
  stderr and falls back to the best available data (cached, local-only, or
  zero) rather than crashing — so a non-empty stderr can accompany exit 0.
- **Machine-readable formats** (data commands only, mutually exclusive):
  - `--json` / `-j` — JSON.
  - `--csv` — CSV.
  - `--md` — Markdown table.
  Prefer `--json` for programmatic parsing. Bare output is a formatted table.

## Gotchas

- **Cached data.** Fetches are cached (~60s TTL). Pass `--fresh` / `-f` to bypass
  the cache and refetch.
- **Single vs multi mode.** Behavior depends on `~/.config/tu/tu.conf` (legacy
  `~/.tu.conf` is read as a fallback with a stderr deprecation warning; an
  optional `~/.config/tu/org.conf` supplies org-wide defaults under it): single
  mode reads
  only local data; multi mode aggregates across machines via the metrics repo.
  Run `tu status` to see which mode is active. `--user` / `-u` (including
  `-u all`, which sums every user in the metrics repo from synced data) and
  multi-machine views apply in multi mode only (warned-and-ignored in single mode).
- **`--watch` / `-w` is an interactive TUI** (live-refreshing display). Do not
  invoke it from an agent — it does not terminate on its own and produces no
  parseable single-shot output.
- **Use `--no-color`** for clean, parseable output (disables ANSI color codes).
- **Implicit 3-month cap.** Daily and weekly history default to the last ~3
  calendar months. Pass `--full` for the complete history. Monthly history
  (`mh`) is never capped.
- **History-only flags.** `--since` / `-s` and `--until` bound a history window
  (`YYYY-MM-DD` or `YYYYMMDD`); on a snapshot display they warn and are ignored.
  On `lb` they replace the period window silently (the Δ column then compares
  against the equal-length preceding window).
- **Token mode.** `--metric tokens` / `-t` renders history and pivot tables in
  tokens instead of cost (all displays); the snapshot table keeps its Cost
  column in dollars — only the watch delta indicator follows the metric.
- **Leaderboard (`lb` / `lbh`).** Multi mode only (exits 1 in single mode) —
  reads the metrics repo, so today lags until `tu sync` (the table footer says
  so). `--top <n>` keeps the top N rows (`lb`, rest collapse into `… +k
  others`) or the top N user columns (`lbh`, rest fold into one `others`
  column); `-u <name>` pins/highlights a user rather than filtering; `-u all`
  is a no-op; `--by-machine` ranks `user/machine` pairs (`lb` only — on `lbh`
  it warns and is ignored).