claude-plugin-nixbuild/skills/nixbuild-usage/SKILL.md

name, description, disable-model-invocation, allowed-tools

name	description	disable-model-invocation	allowed-tools
nixbuild-usage	Report nixbuild.net account usage and cost posture — remaining free build time, billable CPU-seconds over a date range, build history (success/fail/ discarded), output NAR size, and stored size. The account is metered, so this is the cost-visibility skill. Reads come from the HTTP API (nbapi tool, no PTY needed) plus the shell's `usage` command for the live free-time counter. Trigger on "nixbuild usage", "how much build time left", "nixbuild billing", "nixbuild storage", "nixbuild build history", "am I out of free build time", "nixbuild cost".	false	Bash, Read

nixbuild-usage — metered account usage & cost

Owning agent: nixbuild:ops. nixbuild bills CPU-time beyond a monthly free tier; this skill answers "where do I stand" without touching settings. Most of it is the read-only HTTP API via nbapi (${CLAUDE_PLUGIN_ROOT}/bin), which needs no PTY. The live free-time counter comes from the shell banner / usage.

Quick posture

nbapi summary

Returns (example shape):

{
  "build_count": 19, "running_build_count": 0,
  "discarded_build_count": 1, "failed_build_count": 1,
  "successful_build_count": 17,
  "total_cpu_seconds": 27401, "billable_cpu_seconds": 20963,
  "total_duration_seconds": 2708.06, "wall_time_seconds": 48398.44,
  "total_output_nar_size_kilobytes": 786691
}

Key fields: billable_cpu_seconds (what you pay for), successful/failed/ discarded_build_count, total_output_nar_size_kilobytes.

Remaining free build time (live)

The free-tier counter is only in the shell, not the HTTP API:

nbshell 'usage'

The shell login banner also prints it, e.g. Free build time left: 25:00:00 (hh:mm:ss) — it resets at the start of each month. When spent, the banner reads You have no free build time left and further builds are billed.

Billable CPU over a date range

nbapi usage --from 2026-06-01 --to 2026-06-30

Recent build history

nbapi builds --limit 20

Each entry carries id, status, drv path, timing — useful to spot a runaway or repeatedly-failing build burning CPU. For one build's detail (including status_message): nbapi build <id>. For the full build log: nbshell 'builds log <id>'. For a shareable web link: nbapi raw /builds/<id>/url.

Stored size

Storage used: appears in the shell banner (nbshell 'usage'), and total_output_nar_size_kilobytes in nbapi summary approximates output volume.

Reporting

Lead with the two numbers that matter: free time left and billable CPU-seconds (this month). Add fail/discard counts only if non-trivial (a high failed/discarded ratio means wasted spend — flag it). Convert CPU-seconds to hours for readability (/3600). Keep it to a few lines unless asked for the full history.

Token

nbapi reads the bearer token from $NIXBUILD_API_TOKEN, else pass show infra/nixbuild/api-token (override the entry with $NIXBUILD_API_TOKEN_PASS_ENTRY). The read-only API needs only the :read scopes; a broad token works but is more than required.