record-usage

Optional: status-line integration (no OAuth API calls)

record-usage is now an opt-in alternative to the default hook-based integration installed by cctally setup. Use it if you specifically want to avoid OAuth API roundtrips and prefer your usage data to come from the status-line stdin Claude Code already provides.

To wire it up, add this snippet to your ~/.claude/statusline-command.sh (after parsing week_pct/week_resets/five_pct/five_resets from the status-line JSON):

if [ -n "$week_pct" ] && [ -n "$week_resets" ]; then
    record_args="--percent $week_pct --resets-at ${week_resets%.*}"
    if [ -n "$five_pct" ] && [ -n "$five_resets" ]; then
        record_args="$record_args --five-hour-percent $five_pct --five-hour-resets-at ${five_resets%.*}"
    fi
    cctally record-usage $record_args &
fi

Trailing & matters — record-usage runs in the background so it never blocks the status-line render.

Both paths (status-line snippet and the default hook integration) can run simultaneously; the record-usage funnel dedupes correctly.

---

record-usage

Record a usage-percent snapshot from the Claude Code status-line rate_limits data. Writes to weekly_usage_snapshots and, if the snapshot crosses a new integer percent, also to percent_milestones.

Cost coverage: Cumulative Claude costs stored on percent and five-hour milestones are transcript-derived lower bounds, not exact /usage billing totals.

Synopsis

cctally record-usage
    --percent PERCENT
    --resets-at RESETS_AT
    [--five-hour-percent FIVE_HOUR_PERCENT]
    [--five-hour-resets-at FIVE_HOUR_RESETS_AT]

Purpose

This is the ingestion end of the data pipeline. It is not meant to be called interactively — your status-line script calls it after every status render so the SQLite snapshot history stays fresh.

When to use it

• Wired into ~/.claude/statusline-command.sh. See installation.md.
• Manually replaying a missed snapshot if your status-line script crashed (rare; the cost is one missing data point).