CLI reference

branch-tally <COMMAND>

Global options:

Exit codes

Output streams

The report, JSON and command results go to stdout, written as UTF-8 with LF line endings on every platform. Warnings and notes go to stderr, so you can redirect the report to a file and still see them. Notes and warnings carry counts, model ids, branch names and paths only, never transcript content.

branch-tally report

branch-tally report [OPTIONS] [BRANCH]

Reports the token usage and estimated cost for BRANCH (default: the current branch).

Each flag that has a config file key overrides it for one run. Precedence is flag, then config file, then built-in default.

Conflicting flags

These are command-line errors (exit 2):

• a shorthand together with its long form, even when they agree: --strict or --timeline with --mode, --md or --json with --format;
• --strict with --timeline, and --md with --json;
• both halves of an on/off pair: --cost with --no-cost, --redact with --no-redact, --keep-names with --redact-names;
• --with-live without --from-ledger;
• --work-branch when the effective mode is not timeline. The mode can come from --mode timeline, --timeline or the config file’s mode = "timeline". A work-branch set only in the config file is ignored outside timeline mode rather than being an error.

A few flags are accepted but have no effect in some combinations:

• --dry-run without --pr does nothing.
• --ledger without --from-ledger does nothing.
• --pr with JSON output (--json, --format json or format = "json" in the config file) prints the JSON and does not touch the PR. --pr only works with Markdown.
• --no-cost affects the Markdown table only. JSON output always includes costs.
• --keep-names and --redact-names do nothing unless redaction is on.

Attribution modes

A transcript stamps each API call with the git branch the session was on. That stamp is often not the branch the work was for: a session switches branches, a subagent in a worktree stamps the worktree’s throwaway branch, or a call carries no branch at all. The mode decides how branch-tally assigns calls to branches.

claim (the default). Starts from each call’s stamp, then:

• places a session’s own call that has no stamp, or a worktree-agent-… stamp, on the branch the session’s hook captures name both before and after that call (captured hook data). A call with captures on one side only is not placed this way. This needs the capture plugin, and wins over the worktree and origin recovery below;
• recovers the branch of a subagent call stamped worktree-agent-… from the worktree it ran in (worktree recovery), and of an unstamped call read from a worktree’s transcripts from that worktree (origin recovery), using git worktree list, so the worktree must still exist;
• assigns subagent calls to the branch of the session that dispatched them (dispatcher roll-up);
• counts a whole session toward a branch when that branch is the only work branch the session touched (session claim). A work branch here is one starting with feat/, feature/, fix/, bugfix/, hotfix/, chore/ or release/. So a session that started on main and then moved to feat/x counts entirely toward feat/x.

strict. Keeps only the calls whose stamp is the branch: no session claim, no captured hook data, no worktree recovery and no dispatcher roll-up. This is the most literal filter, and it usually counts less than claim.

timeline. Follows each session’s branch over time instead of giving it one branch. A call stamped with a work branch stays there. A call stamped with something else (the default branch, a worktree-agent-… branch) goes to the work branch the session was last on, or, before the session’s first work-branch call, to the first one it moves to. Subagent calls go to the dispatcher’s branch at the moment of dispatch. A call with no usable timestamp, or two work branches at the same instant, is ambiguous: it keeps its raw stamp and is reported as such. There is no worktree lookup in this mode, and hook captures are not used.

In timeline mode, a work branch is by default every branch except the repository’s default branch and worktree-agent-*. The default branch is read from origin/HEAD, then from git’s init.defaultBranch, and is otherwise assumed to be main; the footnote says which. A worktree-agent-* branch is never a work branch. --work-branch <REGEX> replaces that rule. The regex is matched anywhere in the branch name, as written, so anchor it with ^ and $ to match the whole name:

branch-tally report --timeline --work-branch '^(feat|fix)/'

Every heuristic that assigned calls is listed in the report’s footnote with its call and token counts, and in the JSON heuristics object. When calls were ambiguous, the report says the token total is “at least” the figure shown.

Output formats

Markdown (--format md, the default) is the table shown in Getting Started, wrapped in <!-- token-report:start --> and <!-- token-report:end --> markers. It has, in order:

1. the model table: calls, input, cache write (5-minute and 1-hour combined), cache read, output, thinking and estimated cost per model, then the total;
2. the session table: each session’s id, where it ran (main checkout or worktree), its named agents, its UTC time span, calls and tokens (in millions);
3. a bold “Token total is at least …” line, when some calls were ambiguous;
4. a footnote: the branch and mode, session and subagent counts, the heuristics used, the work-branch rule in timeline mode, whether identifiers were redacted, the price table’s date and source, unpriced models, and a reminder that costs are estimates at list API rates;
5. a Subagent usage section, when subagents did part of the work: one row per subagent and model with its workspace, plus how many subagent calls had no dispatch link;
6. a collapsed Breakdown by skill / agent table.

With --no-cost, the cost columns are left out.

JSON (--format json) is one object on stdout. Its top-level keys:

An abridged example, from a scrubbed test fixture:

{
  "branch": "main",
  "mode": "claim",
  "totalCalls": 7,
  "totalCostUSD": 106.9266,
  "totalCostIsFloor": true,
  "unpricedModels": [
    "claude-mystery-9"
  ],
  "priceTable": {
    "asOf": "2026-11-09",
    "source": "bundled"
  },
  "sessions": [
    {
      "id": "s1",
      "origin": "main",
      "first": "2026-01-01T00:00:01.000Z",
      "last": "2026-01-01T00:00:07.000Z",
      "calls": 7,
      "tokens": 117337218,
      "agents": []
    }
  ],
  "models": {
    "claude-mystery-9": {
      "calls": 1,
      "input": 11111,
      "cacheWrite5m": 444,
      "cacheWrite1h": 55,
      "cacheRead": 3333,
      "output": 2222,
      "thinking": 0,
      "costUSD": null
    }
  }
}

Updating a pull request

--pr puts the Markdown report into a pull request’s description. It runs the GitHub CLI, so gh must be installed and signed in.

branch-tally report --pr --dry-run   # print the new PR body, change nothing
branch-tally report --pr             # write it to this branch's open PR
branch-tally report --pr 42          # write it to PR #42

Without a number, it looks up the open PR whose head is the branch. If the PR body already holds the <!-- token-report:start --> and <!-- token-report:end --> markers, the text between them is replaced. Otherwise a ## Token usage section holding the report is appended to the body.

It tells you on stderr what happened: Token usage table written to PR #N., PR #N already up to date., or, with --dry-run, the new body on stdout followed by --- dry run: PR #N not modified ---. With no open PR for the branch it fails with No open PR found for branch '…'. Open the PR first, then re-run with --pr. (exit 1).

To keep a place for the report in your PR template, add the markers where you want it:

## Token usage

<!-- token-report:start -->
_Not yet recorded._
<!-- token-report:end -->

Redaction

--redact hides identifiers in the report, for Markdown and JSON alike:

• session ids become s1, s2, … in order of each session’s first call;
• agent and skill names become agent-1, skill-1, … (main is kept);
• subagent ids become a1, a2, …, and worktree names become worktree-1, …;
• timestamps are reduced to dates, and the session table’s header reads Span (UTC date).

Model ids, branch names, token counts and costs are kept. The output says it was redacted: the footnote includes identifiers redacted, and the JSON has "redacted": true. --no-cost is a separate switch.

--keep-names keeps the real agent and skill names while ids, worktree names and times stay hidden.

Redaction applies to the report only. The ledger stores real identifiers.

What the report says on stderr

Common errors

branch-tally record

branch-tally record [OPTIONS] [BRANCH]

Selects BRANCH’s usage (default: the current branch) exactly as report would and appends it to the ledger. It writes only the ledger file: no git add, no commit. It prints appended N, skipped M, branch B.

The same conflict rules as report apply to the mode flags and --work-branch. From the config file, record uses mode and work-branch and ignores the rest.

branch-tally capture

branch-tally capture

Run by the capture plugin’s hooks (SessionStart, SubagentStop, Stop), not by hand. It takes no options. It reads one hook payload from stdin and appends an id-only event to .tally/captures.jsonl in the main checkout, so a worktree session’s captures land in one place. The event holds the session id, the agent id, the branch, the event kind and a timestamp. No path and no message content is stored or printed. The file and how reports use it are described in Hook captures.

• The branch is the current branch of the payload’s cwd (the process directory when the payload has none). A detached HEAD records nothing.
• For SubagentStop, worktree_branch is the branch of the worktree directory named agent-<agent id> in git worktree list (compared case-insensitively). Failing that, it is the branch of the payload’s own checkout when that is a linked worktree. Otherwise it is absent. It is never guessed.
• SessionEnd and SubagentStart payloads are accepted and ignored.
• It prints nothing on success. On failure (malformed payload, not a git checkout, a detached HEAD, a git or write error) it prints one short fixed line to stderr and exits 1. The hook command ends in ; exit 0, so a failure never blocks the session; that also covers a command-line usage error, which exits 2.

branch-tally prices update

branch-tally prices update

Downloads LiteLLM’s public model_prices_and_context_window.json from GitHub, keeps the Anthropic chat models, and writes them to the per-user price cache. It replaces the cache only when the download and the conversion both succeed, so a failed update leaves a good cache in place. It prints the path written, the table’s date, the model count, and any models skipped for lacking a usable price.

This is the only command that downloads anything. It sends no account or identifying data, only a branch-tally/<version> User-Agent.

The cache file is branch-tally/prices.toml under:

branch-tally prices show

branch-tally prices show [--repo <PATH>]

Prints which price table reports in this repository would use:

source: bundled
as of: 2026-11-09
models: 23
path: (built into the binary)

--repo <PATH> (default .) is the repository whose .tally/prices.toml override is checked.

Which price table is used

The first of these that exists is used whole, with no per-model merging:

1. .tally/prices.toml in the repository’s main checkout (the override, source: override);
2. the per-user cache written by prices update (source: cache);
3. the table built into the binary (source: bundled).

A model id is priced by the longest model key that is a prefix of it, so claude-fable-5-1 also prices claude-fable-5-1[1m]. A model that matches nothing is unpriced, and the report says so. A malformed override or cache stops the report with a message naming the file; it is never skipped silently.

The override and the cache share one TOML format:

A minimal override:

as_of = "2026-11-09"

[models."claude-opus-5"]
input = 5.0   # $ per million tokens
output = 25.0

The bundled table, with the schema in its header, is crates/branch-tally-core/data/prices.toml.

branch-tally config show

branch-tally config show [--config <PATH>]

Prints the config file’s path, whether it was found, and each setting’s effective value with its source (config file or default):

config file: /home/you/.config/branch-tally/config.toml
found: no
mode = claim (default)
work-branch = (not set) (default)
format = md (default)
cost = true (default)
redact = false (default)
redact-names = true (default)

A work-branch that is set while the mode is not timeline carries [inactive: mode is not timeline]. --config <PATH> reads that file instead of the default location; it must exist. See the Config reference.

branch-tally config init

branch-tally config init [--path <PATH>]

Writes a starter config file holding the built-in defaults to --path <PATH>, or to the default location that config show prints. It creates missing directories, prints wrote <path>, and never overwrites an existing file (exit 1). See the Config reference.