gates-usage

CLI for analyzing atomic-gates run data. Like ccusage but for gates.

Reads .gates/runs/*.yaml and shows a live dashboard of skill runs, state transitions, sub-run delegation, and gate failures.

Install

npx gates-usage

Or install globally:

npm install -g gates-usage

Usage

By default, gates-usage starts in watch mode — it monitors .gates/runs/ and refreshes the dashboard when runs change.

# Live dashboard (default) — watches for changes
gates-usage

# Single-shot — print and exit
gates-usage --once

# Specify project directory
gates-usage -d /path/to/project

# List all runs as a table
gates-usage list

# Show a specific run with pipeline visualization
gates-usage show a7e5

# Breakdown by skill
gates-usage skills

Output

Dashboard (default)

  gates-usage

  Runs: 3  3 completed
  Sub-runs: 2  Gate failures: 1  Avg duration: 45s
  Skills: solve-issue (2)  validate-issue (1)

┌──────────────┬──────────────┬────────────┬────────┬──────────┬──────────┐
│ run_id       │ skill        │ status     │ states │ duration │ parent   │
│ a7e545389c54 │ solve-issue  │ ✓ terminal │ 4/5    │ 1m11s    │          │
│ 1d2c20db5c6c │ backend-dev  │ ✓ terminal │ 2/3    │ 20s      │ a7e54538 │
└──────────────┴──────────────┴────────────┴────────┴──────────┴──────────┘

  watching .gates/runs/ — press ctrl+c to stop

Show (pipeline view)

  ✓ solve-issue  a7e545389c54  1m11s
  inputs: issue_number=42

   ├─ ✓ fetch_issue          27s
   ├─ ✓ classify             8s
   ├─ ✓ delegate_backend     28s
   │  ↳ backend-dev  (terminal)
   │    ├─ ✓ understand       10s
   │    ├─ ✓ implement        10s
   │    └─ ▸ done             ...
   ├─ ✓ review               8s
   └─ ▸ done                 ...

How it works

gates-usage reads the YAML run-state files that the atomic-gates runner writes to .gates/runs/ during skill execution. These files follow the run-state schema and contain:

• Run metadata (skill ID, status, timestamps)
• State history with enter/exit times
• Gate failure records
• Sub-run delegation links (parent/child)

The CLI auto-detects the project directory by walking up from cwd looking for a .gates/ directory.

Companion projects

• atomic-gates — the runtime that generates the run data
• claude-dev-pipeline — skill corpus (solve-issue, review-pr, validate-issue, etc.)

License

MIT