---
name: okstra-usage
description: >-
  Show project-wide okstra resource usage over a recent day window. Use when the
  user asks for okstra usage, token usage, estimated spend, CPU/wall time, usage
  coverage, or which lifecycle task types consumed resources. Defaults to the
  whole current project for the last 30 days. For one task's elapsed/context
  detail use okstra-inspect; for status/report digests use okstra-rollup.
---

# OKSTRA Usage

Read-only project usage snapshot. The CLI owns every sum; never re-add rows.

## Step 0: Preflight

Run one literal Bash call:

```bash
okstra preflight --runtime claude-code
```

On `Okstra preflight: ready`, carry the fixed `Project root` line. On
`Okstra preflight: failed`, show `Reason` and `Recovery`, then stop.

<!-- BEGIN FRAGMENT: preflight-outdated-cli -->
If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
<!-- END FRAGMENT: preflight-outdated-cli -->

## Step 1: Resolve the day window

- No period stated: `30`.
- “last N days”: use N only when it is a positive integer.
- A calendar range, task/group/model/worker breakdown, forecast, or budget is
  outside this MVP; state that limitation instead of inventing flags.

## Step 2: Fetch once

```bash
okstra usage-report --days 30 --project-root <projectRoot> --text
```

Replace `30` only with the resolved positive integer. Do not wrap the command in
`if`, `eval`, command substitution, variable assignment, `&&`, `||`, or `npx`.

## Step 3: Render

If `Status` is `error`, report `Failure stage` and `Failure reason`, then stop. If `Runs total` is `0`, say
`No okstra usage found in the last N days.`, omit the table, and continue to Step 4.

Otherwise, render the numbered `Task type N ...` fixed fields in returned order:

| Task type | Runs | Coverage | Raw tokens | Billable | Cost | CPU | Wall |
|---|---:|---:|---:|---:|---:|---:|---:|

- `Coverage` = returned `Task type N collection rate`; never divide or calculate a new aggregate.
- Format tokens with K/M suffixes, milliseconds as zero-padded `HH:MM:SS`, and
  USD to two decimals. For tokens, use one decimal at `>= 1,000` (`K`) and
  `>= 1,000,000` (`M`), trimming a trailing `.0`; below 1,000 render the integer.
- Render the fixed total labels as the final bold row.
- Never treat unavailable usage as collected zero usage.

## Step 4: Diagnostics

- Render non-zero numbered `Unavailable N` and `Warning N` fields after the Step 3 output.
- If numbered `Unmatched model N name` fields exist, mark Cost with `*` when the table exists and
  always say known-price cost excludes those exact model names.