Pipeline/docs/claude-code-statusline-usage.md

Claude Code Status-Line Usage Ingestion

Pipeline tracks Claude subscription usage most accurately from Claude Code's status-line JSON. This is preferred over API rate-limit headers because Claude Code exposes provider-native subscription windows:

• rate_limits.five_hour.used_percentage -> Current session
• rate_limits.five_hour.resets_at -> Current session reset time
• rate_limits.seven_day.used_percentage -> All models
• rate_limits.seven_day.resets_at -> All models reset time

API rate-limit headers are still useful diagnostics, but they are not subscription remaining usage.

Configure Claude Code

Add a status-line command to ~/.claude/settings.json or ~/.config/claude/settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "PIPELINE_API_URL=http://localhost:8001 PIPELINE_AUTH_TOKEN=$LOCAL_AUTH_TOKEN PIPELINE_GATEWAY_ID=<gateway-id> /home/kaspa/.openclaw/Projects/Pipeline/scripts/claude-statusline-to-pipeline.py",
    "padding": 0
  }
}

Replace <gateway-id> with the Pipeline gateway UUID shown in the dashboard/API. Use the backend URL that is reachable from the shell running Claude Code.

The collector forwards only sanitized fields: session_id, model, workspace, and rate_limits. It ignores network errors so Claude Code is not interrupted if Pipeline is down.

Verification

After Claude Code completes at least one model response, the dashboard Runtime Usage card should show provider-native rows:

• Current session
• All models

Both should display % used and reset time from Claude Code. If rate_limits is absent, Pipeline will not invent a subscription usage percentage.