watchfire metrics

Manage the per-task metrics records that feed Insights and the weekly digest. The parent command groups metrics-related subcommands; today the only subcommand is backfill.

Usage

watchfire metrics <subcommand>

Subcommands

metrics backfill

Walk every registered project and write <n>.metrics.yaml for any completed task that doesn't already have one.

watchfire metrics backfill

What It Does

1. Loads the projects index from ~/.watchfire/projects.yaml
2. For each registered project, iterates tasks with status: done
3. Writes a duration-only <n>.metrics.yaml next to each task YAML
4. Skips tasks that already have a metrics file (idempotent)

A line per project is printed during the run, and a summary at the end:

my-project       12 written, 3 skipped
another-project  4 written, 0 skipped

Backfill complete: 2 projects, 16 metrics written, 3 skipped

When To Run It

• After upgrading from a pre-Beacon version (v3.x and earlier), so historical tasks show up in Insights and digests
• After switching agent backends, so the new backend has a baseline to chart against

The command is idempotent — re-running is safe and only touches tasks that don't yet have metrics. Use --force only when you want to overwrite existing records (for example, after correcting a bug in a metrics parser).

Caveat — Backfilled Records Are Duration-Only

Backfilled records are duration-only: tokens_in, tokens_out, and cost_usd remain nil because the original session logs may already be rotated by the time you run the backfill. Live captures (post-upgrade) populate those fields.

This is the same partial-data signal the cross-project rollup tracks via tasks_missing_cost — Insights surfaces a banner when a meaningful slice of records is missing cost so the rollup is never misread as a complete total.

Flags

Flag	Default	Description
--force	false	Overwrite existing <n>.metrics.yaml files

Examples

Backfill after upgrading

watchfire metrics backfill

Sample output:

my-project       12 written, 3 skipped
another-project   4 written, 0 skipped

Backfill complete: 2 projects, 16 metrics written, 3 skipped

Run once after upgrading from a pre-Beacon version so historical tasks show up in Insights and the weekly digest. The "skipped" count is tasks that already had a metrics file — backfill is idempotent.

Re-write every metrics file

watchfire metrics backfill --force

--force overwrites existing <n>.metrics.yaml files. Reach for it only after a metrics-parser bug fix, when the existing records are known-bad.

Common pitfalls

• Backfilled records are duration-only — tokens_in, tokens_out, and cost_usd stay nil because the original session logs may be rotated by the time you backfill. Fix: nothing to do — Insights surfaces a banner when too many records lack cost; live captures going forward populate the missing fields.
• No projects in the index — backfill prints nothing because ~/.watchfire/projects.yaml is empty. Fix: run watchfire init inside each project so it registers with the daemon, then re-run backfill.
• --force discards good data — re-writing a metrics file that had live token/cost data replaces it with a duration-only record. Fix: only use --force when you actually want the existing records overwritten — for routine backfills, leave it off.