pi-ci-status

Lightweight CI status for the Pi coding agent: keeps you and the model aware of GitHub Actions state on the current branch without burning tokens on per-turn status text. This extension makes zero LLM calls — it only spawns throttled gh/git processes.

The three-layer design

1. Footer badge — zero tokens. ctx.ui.setStatus("ci", "CI: ✓ / ✗ test / ⟳ deploy") shows a compact indicator, refreshed on session start and after each agent run.
2. Tool ci_status. The model pulls full detail on demand (latest run + which of the last 5 runs are failing, with URLs). Guidelines tell it when: before claiming a fix works, after pushing, when CI is red.
3. Edge-triggered delta. ONLY when the CI signature changes (green→red, red→green, none→red…) does the extension append one line to the next turn's system prompt and show one notification. A persisted lastInjectKey per repo|branch ensures /reload never re-injects.

Install

# install from npm
pi install npm:pi-ci-status

# or copy the single file into your global extensions dir
cp src/ci-status.ts ~/.pi/agent/extensions/

Then /reload (or restart).

Requires the GitHub CLI, authenticated:

gh auth login      # once

If gh is missing or unauthenticated, the extension shows a single warning and recovers automatically: it re-probes with capped backoff (default 5s → 5min) until gh is available again, and the ci_status tool and /ci force a fresh probe on demand. Failures are never latched — a transient at startup can't disable the badge for the whole session. It never crashes or prompts.

Usage

• /ci — show the current status (badge + latest workflow)
• /ci refresh — force a fresh check, bypassing the throttle
• /ci badge [on|off|activity|reset] — set the footer badge mode at runtime (persisted); reset returns to the env var
• The ci_status tool (refresh: true to bypass the throttle) is available to the model

Footer badge options

The footer badge can be gated or disabled via env var and/or the /ci badge runtime toggle (which wins and is persisted) — the ci_status tool, /ci command, and context injection are unaffected:

| Value | Behavior | | --- | --- | | always (default) | Show whenever a snapshot exists (current behavior) | | activity | Show only when the branch has CI activity (≥ 1 run); hides the "CI: –" placeholder on repos with no runs yet | | off | Never show the footer badge |

export CI_STATUS_BADGE=activity    # badge only appears once CI has run
# or: export CI_STATUS_BADGE=off   # badge disabled, everything else keeps working

At runtime (no restart needed):

/ci badge              → show current mode (override or env default)
/ci badge activity     → activity mode, persisted
/ci badge on           → always show, persisted
/ci badge off          → badge disabled, persisted
/ci badge reset        → back to the CI_STATUS_BADGE env var

The override is stored in ~/.pi/agent/ci-status/badge-mode.json (override the path with CI_STATUS_BADGE_FILE).

Cost / behavior notes

• Throttle: at most one gh run list per 90 s (CI_STATUS_TTL_MS env override) and per new HEAD — a run completing with no new commits still gets re-checked at the TTL; no redundant spawns otherwise.
• gh gate: gh --version + gh auth status probe, cached in a freshness window (default 60s, CI_STATUS_GH_PROBE_TTL_MS). On failure the extension retries with capped backoff (CI_STATUS_GH_RETRY_BASE_MS → CI_STATUS_GH_RETRY_MAX_MS, defaults 5s → 5min) until gh works again, and the ci_status tool / /ci re-probe on demand. No permanent failure latch — a transient at pi startup can't leave the badge disabled for the whole session.
• State: ~/.pi/agent/ci-status/state.json (override with CI_STATUS_STATE), keyed repo|branch → last fetch time, HEAD sha, snapshot, and inject key.
• All I/O is error-swallowed — the extension can never break the agent loop.
• It reports the latest run (status/conclusion + workflow name) and which of the last 5 runs are failing.

Development / tests

The core logic is exported for testing. Tests use a fake gh shim (tests/gh-shim.mjs) — no network, no auth:

npm ci
npm test
npm run typecheck

Covers: gate ok · initial fetch · HEAD-unchanged skip (no extra spawn) · new-commit refetch · green→red transition fires once · red→active · no re-fire on same signature · badge/line/format derivation · badge visibility modes (CI_STATUS_BADGE: always/activity/off) · badge-mode override persistence (/ci badge) · gh-missing and unauthenticated no-ops · gate-recovery after failure · extension-registration wiring (tool, command, handlers). 78 assertions across the 5 runs.

Requirements

• Pi coding agent (extension API; tested against 1.0.0)
• GitHub CLI (gh) installed and authenticated
• git on PATH

License

MIT — see LICENSE.