Your PR's CI
How Narsil Check follows the GitHub Actions steps of the session's pull request with the gh CLI, every 10 seconds while a run goes, and stops when it ends.
What it does
When the session has an open pull request, the Entorno section shows a CI fold under the Remote Control switch. It follows the GitHub Actions run of the pull request’s newest commit, step by step, so you can watch the checks without opening the browser.
The fold’s head says how far the CI is at a glance:
| Head | Meaning |
|---|---|
CI · 2/4 · Typecheck |
Running: two of four steps done, Typecheck running now. |
CI · pasó |
Passed. |
CI · falló |
Failed. |
CI · esperando el CI del último push |
Waiting: your branch has a commit that no run has picked up yet. |
CI · sin ejecuciones |
No runs for this branch. |
CI · sin leer |
Not read: gh could not answer, and the reason shows under it. |
Unfolded, it lists the steps with a mark in Narsil’s colors:
✓green: done.✗red: failed, cancelled, timed out, waiting for an action or failed to start.◐yellow: running.○gray: queued or waiting.–gray: skipped or neutral.
GitHub’s own bookkeeping steps (Set up job, Complete job, Post …) are left out, since they say nothing about the project. With several workflows, each run’s name heads its steps; with several jobs, each job shows with its own mark.
While a run goes, the fold asks again every 10 seconds, and it stops asking as soon as the CI ends. The fold stays as you left it: the session start does not reset it, and the code’s comment says it keeps how you left it across sessions (the first guide explains what the types say about that). While it is folded, nothing is asked.
How it works inside
Which pull request, which repository
The CI fold does not look for a pull request itself. It uses the one the desktop app has bound to the session, read in the previous guides through $.mcp.call('ccd_pr', 'get_status', { session_id: 'self' }). parsePr in hooks/session.ts keeps, for an open pull request, its url, its repository (prRepo, owner and name, such as acme/shop) and its head branch (prHead).
The fold is drawn only when view.prUrl is set. So it exists only in the desktop app, where ccd_pr exists; the README’s table of surfaces says the same.
Asking gh
The pure part lives in hooks/ci.ts: it builds the commands and reads their output. The hooks module runs them in readCi, in hooks/register.tsx.
First, the runs of the branch:
export function runListArgv(repo: string, branch: string): string[] {
return [
'gh',
'run',
'list',
'--repo',
repo,
'--branch',
branch,
'--json',
RUN_FIELDS,
'--limit',
'20',
]
}
RUN_FIELDS is 'databaseId,headSha,workflowName,status,conclusion'. gh lists the newest first, so latestRuns takes the first run’s commit (headSha) as the newest one, keeps only the runs of that commit, and keeps one per workflow name. Older commits’ runs never mix with the current one.
Then, for each of those runs, its jobs and steps:
export function runViewArgv(repo: string, id: number): string[] {
return ['gh', 'run', 'view', String(id), '--repo', repo, '--json', 'jobs']
}
jobsOf reads each job’s name, status, conclusion and steps, and drops the bookkeeping steps with one regular expression, NOISE = /^(Set up job|Complete job|Post .+)$/.
The CI’s states are GitHub’s: a status (queued, in_progress, completed) and, once completed, a conclusion. markOf turns that pair into a mark and a color, and the list of failing conclusions (FAILED) is the same everywhere: in a step’s mark, in the head (ciLabel) and in the fold’s own mark (ciMark).
$.process.run, as the code uses it
The 2.1.325 types describe $.process.run(argv, init) as running “a command on the host by its argument vector (no shell)”, resolving { exitCode, stdout, stderr } “once it exits, any exit code”. The timeout is 30 seconds by default and ten minutes at most; Narsil Check passes GH_MS, 30 seconds. It rejects when the command cannot start or is still running at the timeout. The types also mark the whole process noun “CLI only”.
Two things follow, and the code handles both:
- A non-zero exit is an answer, not an exception.
readCicheckslist.exitCode !== 0and keepsgh’s stderr as the error, or “gh terminó con el código N” (“gh ended with code N”) when stderr is empty. - A missing
ghis an exception. The call rejects, thecatcharoundreadCikeeps the message, and the fold says it.
Because the argument vector has no shell, the repository and branch names go to gh as plain arguments: there is nothing to quote or escape.
There is a reason to run gh instead of calling GitHub’s HTTP API from the mod: gh brings the person’s own sign-in, so the mod never holds a GitHub token. A comment in hooks/register.tsx gives a related reason for running git itself in “Actualizar rama”: “The mod runs git itself, so the app asks no permission.”
Waiting for a push
Right after git push, GitHub may not have started a run for the new commit, and the list still shows the previous commit’s run, perhaps already green. Showing “passed” then would be wrong.
So when the checked-out branch is the pull request’s head branch, readCi also runs git rev-parse @{upstream}. If the upstream commit is not the commit of the runs listed, a newer push has no run yet, and the view is marked isWaiting: the head says “esperando el CI del último push” and the mark is yellow.
Every 10 seconds, and then no more
The polling is watchCi, a loop:
let ciWatch = 0
async function watchCi($: EngineInterface): Promise<void> {
const id = ++ciWatch
let waits = 0
for (;;) {
const view = await read($, session)
if (!view.prUrl || !(await read($, isCiOpen))) return
await update($, ci, (current) =>
current.status === 'ready' ? current : { ...current, status: 'loading' },
)
let next = await readCi($, view)
if (id !== ciWatch) return
// A push no workflow answers (a repository with no CI for it) stops waiting.
if (next.isWaiting && ++waits > CI_WAIT_POLLS) next = { ...next, isWaiting: false }
await update($, ci, () => next)
if (next.error || !(next.isWaiting || isGoing(next.runs))) return
await $.clock.sleep(CI_POLL_MS)
if (id !== ciWatch) return
}
}
It is quoted from narsil-check (GPL-3.0-or-later). Each line is a rule:
- No pull request, or the fold closed: stop. Nothing is asked while you are not looking.
- Keep the last answer while reloading. A view that is already
readystays as it is during the next read, so the steps do not flicker. - One watch at a time. Each call takes a new
id. A newer watch (from the next session read, a pull request found late, or the fold opening) makes the old one stop at its next check. - A push that nobody answers ends the wait.
CI_WAIT_POLLSis 12, so after about two minutes a repository with no workflow for that push stops waiting. - Stop on an error, or when nothing is running and nothing is waited for.
isGoingis true while any run’s status is notcompleted. - Otherwise wait
CI_POLL_MS, 10 seconds, with$.clock.sleep. The types describe it as resolving “aftermsmilliseconds”.
The types also offer $.clock.every(ms, fn), which calls fn every period until it is cancelled. The loop with sleep has a property that fits this case: the next read starts only after the previous one ended, so slow gh calls never overlap, and the loop ends by itself on the condition it just read.
The watch is started with void watchCi($) after a full session read, after a pull request found late, and when you unfold the fold. It is never awaited by a hook.
When gh is missing or not signed in
Both cases end the same way. The view gets an error, the head says CI · sin leer, the mark is gray ○, and the unfolded fold shows in red “No pude leer el CI con gh: …” (“I could not read the CI with gh: …”) followed by the reason: the engine’s message when gh could not start, or gh’s own stderr when it ran and refused, as it does when it is not signed in. The loop stops on the error; the next session read or unfolding the fold tries again.
On permissions, the README says only that gh must be installed and signed in (“con gh instalado y con sesión iniciada”). Neither the README nor the code lists scopes for reading the CI. The README’s note about the workflow permission is about pushing changes to .github/workflows over HTTPS, a different feature.
How it was asked of the AI
The original request for the CI fold was not recorded. None of narsil-check’s public task logs (odd/tasks/*.md) covers it.
Reconstruction from the commit history
From git log -- hooks/ci.ts, with the related commits to hooks/register.tsx and hooks/session.ts:
7d91264(2026-11-07) “feat: add an Auto-fix switch to Entorno for the session’s open pull request”. The session first learns about its pull request here, throughccd_pr.8af1f0e(2026-11-07) “feat: show the PR’s CI step by step in a collapsible fold under Remote Control”. The whole ofhooks/ci.tsarrives in this one commit. Its message: it “Reads the newest commit’s GitHub Actions runs on the PR’s head branch with gh, lists each job’s steps without GitHub’s bookkeeping ones, and polls every 10 seconds while a run goes or a push waits for one. The fold keeps its open state across sessions.” It also bumps the session atom’sshapefor the new pull request fields.90c40f9(2026-11-07) “fix: read the session’s pull request again when the app binds it after the turn ends”. Without it, a pull request opened in a turn showed no CI until the next read.f091e0b(2026-11-07) “fix: retry only the pull request read and stop the retries when the session ends”.
The pattern differs from the earlier guides: the CI fold landed complete in one commit, on top of the pull request plumbing of the day before, and the fixes that followed were about finding the pull request, not about the CI itself.
A prompt you can use
The following prompt was written for this guide as a suggestion. It is not the author’s prompt.
In my Claude Code mod
my-panel, add a “CI” fold for the session’s open pull request, whose repository (acme/shop) and head branch I already have. Rungh run list --repo <repo> --branch <branch> --json databaseId,headSha,workflowName,status,conclusion --limit 20with$.process.run(30 s timeout), keep only the runs of the first row’sheadSha, one per workflow, thengh run view <id> --repo <repo> --json jobsfor each. Hide the stepsSet up job,Complete jobandPost …. Show each step with ✓ green, ✗ red, ◐ yellow for in progress, ○ gray for queued and – gray for skipped. Treat a non-zero exit as an error with gh’s stderr, and a rejection (gh missing) as an error too; show it in the fold. Poll in a loop with$.clock.sleep(10_000)only while the fold is open and a run is not completed, and stop otherwise; give each watch an id so a newer one replaces it. Test the parsers as pure functions with synthetic gh JSON, and the loop withmock.clock.
The minimal code
This is a reduced version of the idea, written for this guide and checked against the Claude Code 2.1.325 types. It is adapted from hooks/ci.ts and hooks/register.tsx in narsil-check (GPL-3.0-or-later). It follows one workflow and leaves out the wait for a push.
The state’s type, in types/index.d.ts:
export type Step = { name: string; status: string; conclusion: string }
export type Ci = { steps: Step[]; isGoing: boolean; error?: string }
declare module 'claude-code' {
interface PluginState {
'my-panel': { ci: Ci }
}
}
The hooks module’s part, hooks/register.tsx:
import { atom, read, update } from 'claude-code'
import type { EngineInterface } from 'claude-code'
import type { Ci, Step } from '../types'
const ci = atom({ plugin: 'my-panel', key: 'ci' } as const, { steps: [], isGoing: false } as Ci)
const NOISE = /^(Set up job|Complete job|Post .+)$/
async function gh($: EngineInterface, argv: string[]): Promise<string> {
const ran = await $.process.run(['gh', ...argv], { timeoutMs: 30_000 })
if (ran.exitCode !== 0) throw new Error(ran.stderr.trim() || `gh ended with code ${ran.exitCode}`)
return ran.stdout
}
async function readCi($: EngineInterface, repo: string, branch: string): Promise<Ci> {
try {
const fields = 'databaseId,headSha,status,conclusion'
const runs = JSON.parse(
await gh($, [
'run',
'list',
'--repo',
repo,
'--branch',
branch,
'--json',
fields,
'--limit',
'1',
]),
)
if (!Array.isArray(runs) || runs.length === 0) return { steps: [], isGoing: false }
const run = runs[0] as { databaseId: number; status: string }
const viewed = JSON.parse(
await gh($, ['run', 'view', String(run.databaseId), '--repo', repo, '--json', 'jobs']),
)
const steps: Step[] = (viewed.jobs ?? [])
.flatMap((job: { steps?: Step[] }) => job.steps ?? [])
.filter((step: Step) => !NOISE.test(step.name))
return { steps, isGoing: run.status !== 'completed' }
} catch (err) {
return { steps: [], isGoing: false, error: err instanceof Error ? err.message : String(err) }
}
}
let watch = 0
export async function watchCi($: EngineInterface, repo: string, branch: string): Promise<void> {
const id = ++watch
for (;;) {
const next = await readCi($, repo, branch)
if (id !== watch) return
await update($, ci, () => next)
if (next.error || !next.isGoing) return
await $.clock.sleep(10_000)
if (id !== watch) return
}
}
export const MARK = (s: Step) =>
s.status !== 'completed'
? s.status === 'in_progress'
? { mark: '◐', color: '#F5B400' }
: { mark: '○', color: '#8A90A6' }
: s.conclusion === 'success'
? { mark: '✓', color: '#22B573' }
: s.conclusion === 'skipped'
? { mark: '–', color: '#8A90A6' }
: { mark: '✗', color: '#F0435A' }
Start it with void watchCi($, 'acme/shop', 'feat/login').catch(() => undefined) from a hook, never awaited, and draw the steps in the pane’s ui.render hook with read($, ci), one Text per step in its MARK color, and the error in red when there is one. The reduced MARK treats any completed conclusion other than success or skipped as a failure; Narsil Check’s markOf names the failing ones (FAILED) and shows neutral as gray too.
Common mistakes and how to test it
These come from Narsil Check’s code and commits:
- Mixing commits.
gh run listreturns runs of several commits. Keep only the newest commit’s runs, one per workflow, aslatestRunsdoes. - Announcing a pass right after a push. The list may still show the previous commit’s green run. Compare the upstream commit with the runs’
headSha, and give up waiting after a bound (CI_WAIT_POLLS), or a repository with no CI for that push waits forever. - Treating the exit code as an exception.
$.process.runresolves on any exit code. CheckexitCode, and keep stderr as the reason. - Polling forever. Stop when nothing runs, when the fold is closed and on an error. Narsil Check’s loop returns on each of these.
- Two watches at once. Every read of the session may start a watch. Give each an id and let the newest win.
- Awaiting the watch in a hook. A hook’s
$.clock.sleepspends that hook’s budget, as the types say; start the watch withvoid. - Showing GitHub’s bookkeeping.
Set up jobandPost …steps hide the ones that matter.
To test, tests/ci.test.tsx checks the pure functions with synthetic gh JSON: “the newest commit’s runs, one per workflow, newest first”, “a run’s steps leave out GitHub’s own bookkeeping”, “each step shows as done, failed, going, waiting or skipped” and “the fold’s line says how far the CI is”. tests/session.test.tsx tests the fold in the pane: it answers gh through an on('process.run', ...) hook keyed on the joined argument vector, and moves time with mock.clock and clock.advance(10_000) in “the CI fold, under Remote Control, shows the PR’s run step by step and follows it until it ends”. “a CI gh cannot read says why in its fold” answers every command with exit code 1 and expects CI · sin leer and the red line.
Going further
- The Auto-fix switch right under the fold (previous guides) turns on the desktop app’s own CI monitor for the same pull request, which wakes the session when the CI fails; the fold shows the CI, the switch acts on it.
ciLabelcounts done steps across every job and run, and names the step running now, so the head alone is often enough while the fold stays folded.- The fold reads
gh’s JSON fields, not its text output, so a change ingh’s wording does not break it.
Going further: how the real mod does it
These files are part of the original mods, published under the GPL v3. Code quoted on this page comes from them and keeps that license.
Did this guide help?
Every guide is free. If this one saved you time, you can buy me a coffee.
Buy me a coffee