local-kanban 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -8,6 +8,47 @@ version it goes out as and opens an empty one again. Released sections are histo
 
 ## [Unreleased]
 
+## [1.14.0]
+
+### Added
+
+- **`kb` shows how tasks are linked, and can make a sub-task.** The board keeps parents, sub-tasks and
+  related tasks, but `kb show` and `kb take` printed none of them, so Claude could not know that two
+  tasks were meant to go together. Both commands now print one line per link: `↑ parent`,
+  `↓ subtask`, `↔ related`, with the key, title and status. `kb link A B child` makes B a sub-task
+  of A, `kb link A B parent` makes it A's parent; without a third word the link is related, as before.
+- **`kb info` prints the project's description and its documents.** The description is where owners
+  keep the context for work, and it never reached Claude. A `docs:` line now lists the documents to
+  read before a task (`CLAUDE.md`, `README.md`, `ARCHITECTURE.md` …) and says so plainly when there is
+  no `CLAUDE.md` or the project folder is not on this machine.
+- **`kb check <key> <n>` / `kb uncheck` tick checklist items from the CLI.** Claude could read the
+  checklist but not tick it, so at acceptance every box was empty and the human could not tell what
+  of the list was done. The item is addressed by its number in the order `kb show` prints it.
+- **`KB_GH_BIN` points the board at `gh` when it lives somewhere unusual.** The board looks for `gh`
+  in the usual install locations (Homebrew, `/usr/bin`, `~/.local/bin`) and then on `PATH`; a copy
+  anywhere else can now be named explicitly.
+
+### Fixed
+
+- **`kb` no longer loses what the human wrote in a card.** `kb take` printed only the latest note
+  from the human, so a send-back followed by a second note lost the first; `kb show` printed the last
+  five comments of any author, and Claude's own notes plus the commit stats pushed the human's note
+  out without a word. Both now print every note the human left since Claude's last report, each
+  comment carries its date and time, and anything left out is counted ("… 3 more comments not
+  printed") instead of dropped silently.
+- **A commit stat is no longer printed as the human speaking.** `kb show` marked everything that was
+  not Claude's with 👤, including the commit stat the board attaches on its own. It is marked ⎇ now.
+- **`kb take` tells a blocked To do from an empty one.** When every card in To do was blocked it
+  answered a bare `empty`, and Claude reported an empty column while the human could see cards in
+  it. It now says `empty (2 blocked)`; `kb next` does the same.
+- **`kb take` and `kb show` print the issue the same way** — `issue: #42 <link>`. One printed the
+  number and the other the link.
+- **The checklist now reaches Claude.** A card's checklist is shown on the board right under the
+  description, but `kb show` and `kb take` printed everything about the task except it — the CLI is
+  the only channel Claude has, so the items simply did not exist for it: a card with three checklist
+  items and an empty description arrived as a bare title. Both commands now print the items as
+  `- [ ]` / `- [x]` lines, in the board's order, right after the description.
+
 ## [1.13.0]
 
 ### Added

package/README.md

@@ -142,6 +142,7 @@ Releases live in `main` (stable, tagged); day-to-day development happens in `dev
 | `KB_PANEL_INFO` | — | optional path to an external panel's info.json for category sync |
 | `KB_SSE_MAX` | `20` | cap on concurrent SSE connections |
 | `KB_SKILLS_EXTRA` | — | extra skill root directories, `:`-separated |
+| `KB_GH_BIN` | — | path to the `gh` binary when it is not in a usual place (Homebrew, `/usr/bin`, `~/.local/bin`) |
 
 The legacy names `PANEL_URL` and `PANEL_INFO` (without the prefix) still work as a fallback.
 

package/README.ru.md

@@ -141,6 +141,7 @@ npm run update   # git pull + npm install + pm2 restart (если примени
 | `KB_PANEL_INFO` | — | опциональный info.json внешней панели для синка категорий |
 | `KB_SSE_MAX` | `20` | потолок одновременных SSE-соединений |
 | `KB_SKILLS_EXTRA` | — | дополнительные корни скиллов через `:` |
+| `KB_GH_BIN` | — | путь к `gh`, если он лежит не в обычном месте (Homebrew, `/usr/bin`, `~/.local/bin`) |
 
 Старые имена `PANEL_URL` и `PANEL_INFO` (без префикса) продолжают работать как запасные.
 

package/bin/kb

@@ -63,8 +63,96 @@ function taskLine(t) {
   return `${t.key} ${t.status}${flags ? ' ' + flags : ''} ${t.title}${labels}`;
 }
 
+// The checklist is part of the task's spec: the board shows it right under the description, and
+// this CLI is the only channel Claude has — an item that is not printed here does not exist for
+// Claude. Markdown task-list lines, `- [ ]` open and `- [x]` done, in the board's order.
+function printChecklist(t) {
+  for (const c of (t.checklist || [])) console.log(`- [${c.done ? 'x' : ' '}] ${c.text}`);
+}
+
+// here, and the skill's rule "related tasks solved together are taken together" cannot be followed
+// without knowing they are related. `rel` is relative to this task: 'parent' — the other task is
+// this one's parent, 'child' — the other task is a sub-task of this one, 'related' — symmetric.
+const REL = { parent: ['↑', 'parent'], child: ['↓', 'subtask'], related: ['↔', 'related'] };
+function printLinks(t) {
+  for (const l of (t.links || [])) {
+    const [arrow, word] = REL[l.rel] || REL.related;
+    console.log(`${arrow} ${word} ${l.key} ${l.title} (${l.status})`);
+  }
+}
+const linksLine = (id, links) => `${id} ${links.map((l) => (REL[l.rel] || REL.related)[0] + l.key).join(' ') || '—'}`;
+
+// the skill had to explain two formats. The number goes into commit messages, the link is for eyes.
+function printIssue(t) {
+  if (t.gh_issue_number) console.log(`issue: #${t.gh_issue_number}${t.gh_issue_url ? ' ' + t.gh_issue_url : ''}`);
+  else if (t.gh_issue_url) console.log(`issue: ${t.gh_issue_url}`);
+}
+
+// sees cards in the column, and a bare "empty" made Claude report that there was nothing there.
+function emptyLine(todo) {
+  const blocked = todo.filter((t) => t.blocked).length;
+  return blocked ? `empty (${blocked} blocked)` : 'empty';
+}
+
+function printAttachments(t) {
+  for (const a of (t.attachments || [])) console.log(`📎 screenshot (open it with Read): ${a.path}`);
+}
+
+// Comments. Three authors: the human ('me'), Claude, and 'git' — the commit stat the board attaches
+// by itself on the move to review. Each gets its own mark: a commit printed as 👤 read as the human
+const WHO = { claude: '🤖', git: '⎇' };
+
+// The database keeps UTC ('YYYY-MM-DD HH:MM:SS'); print local time, to the minute — enough to tell
+function when(c) {
+  const d = new Date(String(c.created_at || '').replace(' ', 'T') + 'Z');
+  if (Number.isNaN(d.getTime())) return '';
+  const p = (n) => String(n).padStart(2, '0');
+  return `[${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}] `;
+}
+
+function printComment(c) {
+  const at = when(c);
+  if (c.body) console.log(`> ${WHO[c.author] || '👤'} ${at}${c.author === 'git' ? 'commit ' : ''}${c.body}`);
+  if (c.image_path) console.log(`📎 image from a comment ${at}(open it with Read): ${c.image_path}`);
+}
+
+// Claude's last report — not just the latest one (a send-back plus a follow-up note lost the first)
+// and not whatever happens to fit a window of the last few (Claude's own notes and commit stats
+// pushed the human out of it). Those are always printed; `window` adds the last N comments of any
+// author on top, and the latest images stay too — they are usually the correction itself. When the
+// human has said nothing since the last report, the last thing they did say is printed, dated, so
+// it can be told apart from a fresh one. Whatever is left out is counted, never dropped silently.
+function printComments(cs, window) {
+  const keep = new Set();
+  let lastReport = -1;
+  cs.forEach((c, i) => { if (c.author === 'claude') lastReport = i; });
+  const human = (c) => c.author !== 'claude' && c.author !== 'git';
+  cs.forEach((c, i) => { if (i > lastReport && human(c)) keep.add(i); });
+  if (!keep.size) {
+    const i = cs.findLastIndex((c) => human(c) && c.body);
+    if (i >= 0) keep.add(i);
+  }
+  for (let i = Math.max(0, cs.length - window); i < cs.length; i++) keep.add(i);
+  cs.map((c, i) => (c.image_path ? i : -1)).filter((i) => i >= 0).slice(-3).forEach((i) => keep.add(i));
+  const hidden = cs.length - keep.size;
+  if (hidden > 0) console.log(`… ${hidden} more comment${hidden === 1 ? '' : 's'} not printed — the board has them all`);
+  cs.forEach((c, i) => { if (keep.has(i)) printComment(c); });
+}
+
 const [cmd, ...args] = process.argv.slice(2);
 
+async function tick(done) {
+  const [id, n] = args;
+  const no = Number(n);
+  if (!id || !Number.isInteger(no) || no < 1) die(`kb ${done ? 'check' : 'uncheck'} <key> <n>  (n = the item number, from 1, in the order kb show prints them)`);
+  const t = await api('GET', `/api/tasks/${id}`);
+  const items = t.checklist || [];
+  if (no > items.length) die(`kb: ${t.key} has ${items.length ? `only ${items.length} checklist item${items.length === 1 ? '' : 's'}` : 'no checklist'}`);
+  const item = await api('PATCH', `/api/tasks/${id}/checklist/${items[no - 1].id}`, { done });
+  const open = items.filter((c, i) => (i === no - 1 ? !item.done : !c.done)).length;
+  console.log(`${t.key} - [${item.done ? 'x' : ' '}] ${item.text} (${open} open)`);
+}
+
 const commands = {
   async p() {
     const ps = await api('GET', '/api/projects');
@@ -91,28 +179,27 @@ const commands = {
     if (!proj) die('kb next <project>');
     const ts = await api('GET', `/api/tasks?${new URLSearchParams({ project: proj, status: 'todo' })}`);
     const free = ts.filter((t) => !t.blocked);
-    console.log(free.length ? taskLine(free[0]) : 'empty');
+    console.log(free.length ? taskLine(free[0]) : emptyLine(ts));
   },
 
-  // take the next task and put it straight into prep (study before code); prints the last
-  // comment from the human (notes from a send-back). Writing code → kb mv <key> doing.
+  // take the next task and put it straight into prep (study before code); prints what the human
+  // wrote since Claude's last report (notes from a send-back). Writing code → kb mv <key> doing.
   async take() {
     const [proj] = args;
     if (!proj) die('kb take <project>');
     const ts = await api('GET', `/api/tasks?${new URLSearchParams({ project: proj, status: 'todo' })}`);
     const free = ts.filter((t) => !t.blocked);
-    if (!free.length) return console.log('empty');
+    if (!free.length) return console.log(emptyLine(ts));
     const t = await api('PATCH', `/api/tasks/${free[0].id}`, { status: 'prep' });
     console.log(taskLine({ ...t, labels: t.labels }));
     if (t.description) console.log(t.description);
-    if (t.gh_issue_number) console.log(`issue: ${t.gh_issue_number}`);
-    const atts = await api('GET', `/api/tasks/${t.id}/attachments`);
-    for (const a of atts) console.log(`📎 screenshot (open it with Read): ${a.path}`);
-    const cs = await api('GET', `/api/tasks/${t.id}/comments`);
-    const lastHuman = cs.filter((c) => c.author === 'me' && c.body).pop();
-    if (lastHuman) console.log(`> 👤 ${lastHuman.body}`);
-    // comments often carry corrections — print the paths of the latest images so they get opened
-    for (const c of cs.filter((c) => c.image_path).slice(-3)) console.log(`📎 image from a comment (open it with Read): ${c.image_path}`);
+    // PATCH answers with the bare row; the checklist and the attachments live on the full card
+    const full = await api('GET', `/api/tasks/${t.id}`);
+    printChecklist(full);
+    printLinks(full);
+    printIssue(full);
+    printAttachments(full);
+    printComments(await api('GET', `/api/tasks/${t.id}/comments`), 0);
   },
 
   // leave a note and move to review in one command
@@ -131,13 +218,11 @@ const commands = {
     console.log(`${t.key} ${t.project} ${t.status}${t.blocked ? ` blocked: ${t.blocked_reason || ''}` : ''}${PRI[t.priority] ? ' ' + PRI[t.priority] : ''}${t.labels.length ? ' [' + t.labels.join(',') + ']' : ''}`);
     console.log(t.title);
     if (t.description) console.log(t.description);
-    if (t.gh_issue_url) console.log(`issue: ${t.gh_issue_url}`);
-    for (const a of (t.attachments || [])) console.log(`📎 screenshot (open it with Read): ${a.path}`);
-    const cs = await api('GET', `/api/tasks/${id}/comments`);
-    for (const c of cs.slice(-5)) {
-      if (c.body) console.log(`> ${c.author === 'claude' ? '🤖' : '👤'} ${c.body}`);
-      if (c.image_path) console.log(`📎 image from a comment (open it with Read): ${c.image_path}`);
-    }
+    printChecklist(t);
+    printLinks(t);
+    printIssue(t);
+    printAttachments(t);
+    printComments(await api('GET', `/api/tasks/${id}/comments`), 5);
   },
 
   async add() {
@@ -222,20 +307,28 @@ const commands = {
     console.log(`${t.key} 📝`);
   },
 
+  // kb link A B [child|parent|related] — `child`: B becomes a sub-task of A, `parent`: B becomes
+  // A's parent. Without a third word the link is plain `related`, as it always was. A pair holds
+  // one link, so linking again with another word re-types it.
   async link() {
-    const [id, other] = args;
-    if (!id || !other) die('kb link <key> <key>  (link two tasks)');
-    const links = await api('POST', `/api/tasks/${id}/links`, { key: other });
-    console.log(`${id} ↔ ${links.map((l) => l.key).join(', ') || '—'}`);
+    const [id, other, rel = 'related'] = args;
+    if (!id || !other || !REL[rel]) die('kb link <key> <key> [child|parent|related]  (child: the second task becomes a sub-task of the first)');
+    const links = await api('POST', `/api/tasks/${id}/links`, { key: other, rel });
+    console.log(linksLine(id, links));
   },
 
   async unlink() {
     const [id, other] = args;
     if (!id || !other) die('kb unlink <key> <key>');
     const links = await api('DELETE', `/api/tasks/${id}/links/${other}`);
-    console.log(`${id} ↔ ${links.map((l) => l.key).join(', ') || '—'}`);
+    console.log(linksLine(id, links));
   },
 
+  // empty and could not tell what of the list was done. The item is addressed by its number — the
+  // position in which show/take print it (the board's order), counting from 1.
+  async check() { await tick(true); },
+  async uncheck() { await tick(false); },
+
   async block() {
     const [id, reason] = args;
     if (!id) die('kb block <key> ["reason"]');
@@ -268,6 +361,17 @@ const commands = {
     const services = parsePm2Services(p.pm2_services);
     if (services.length) out.push(`pm2: ${services.join(', ')}`);
     if (p.domain) out.push(`domain: ${p.domain}`);
+    // CLAUDE.md", "deployed by skill X", DNS facts) — info printed everything but it
+    if (p.description) out.push(`description: ${p.description}`);
+    // page; without this line Claude went looking by itself and sometimes missed. A missing
+    // CLAUDE.md is said out loud — it is a signal (the task starts without architecture notes).
+    if (p.path) {
+      const d = await api('GET', `/api/projects/${encodeURIComponent(p.slug)}/docs`);
+      const found = (d.docs || []).filter((x) => x.exists).map((x) => x.name);
+      if (!d.path_exists) out.push('docs: — the project folder does not exist on this machine');
+      else if (!found.includes('CLAUDE.md')) out.push(`docs: no CLAUDE.md${found.length ? ` — read ${found.join(', ')} instead` : ', and no README.md / ARCHITECTURE.md either'}`);
+      else out.push(`docs: ${found.join(', ')}`);
+    }
     console.log(out.join('\n'));
   },
 
@@ -297,7 +401,7 @@ const commands = {
 };
 
 if (!cmd || !commands[cmd]) {
-  die('kb p|ls|next|take|show|add|mv|review|done|cancel|pri|lbl|desc|note|link|unlink|block|unblock|rm|info|svc|sync|retry');
+  die('kb p|ls|next|take|show|add|mv|review|done|cancel|pri|lbl|desc|note|link|unlink|check|uncheck|block|unblock|rm|info|svc|sync|retry');
 }
 commands[cmd]().catch((e) => {
   // die() inside a command already exited the process — only real exceptions reach here.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "local-kanban",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "license": "MIT",
   "author": "Dannylamao",
   "repository": {

package/skills/kanban/SKILL.md

@@ -15,10 +15,14 @@ Statuses: `backlog` → `todo` → `prep` → `doing` → `deploy` → `review`
 
 ```
 kb take <proj>                # take the next task from todo → prep; prints the description,
-                              # the issue number (for commit messages), the last note from the
-                              # human (if the task was sent back, act on it!) and the paths of
-                              # attached screenshots as "📎 <path>" — OPEN those with Read,
-                              # they are context for the task.
+                              # the checklist as "- [ ] item" / "- [x] item" lines (that IS the
+                              # spec — do every open item, and verify them one by one before
+                              # review), the issue as "issue: #N <link>" (#N goes into commit
+                              # messages; kb show prints the same line), EVERY note the
+                              # human left since your last report, dated — "> 👤 [2026-09-02 11:30]
+                              # …" (if the task was sent back, act on them!) and the paths of
+                              # attached screenshots as "📎 <path>" — OPEN those with Read, they
+                              # are context for the task.
                               # started writing code → kb mv <key> doing.
 kb review <key> "note"        # leave a note and move to review. NOT atomic: the note is stored
                               # EVEN IF the move is rejected (backlog and todo cannot go straight
@@ -27,7 +31,11 @@ kb review <key> "note"        # leave a note and move to review. NOT atomic: the
                               # never went through doing.
 kb p                          # projects: slug (PREFIX) b0 t2 pp0 d1 dp0 r1 ✓5 !1  (pp = prep)
 kb ls <proj> [-s st] [-a]     # tasks (without -a, backlog/done/cancelled are hidden)
-kb show <key>                 # details + issue + latest comments
+kb show <key>                 # details + checklist + issue + comments: the last five plus every
+                              # human note since your last report. Marks: 🤖 yours, 👤 the
+                              # human's, ⎇ a commit stat the board attached by itself (not the
+                              # human speaking). "… N more comments not printed" = the rest are
+                              # on the board — nothing is dropped silently.
 kb add <proj> "title" [-d "desc"] [-p high|med|low] [-s todo]   # goes to backlog by default!
 kb mv <key> todo|prep|doing|deploy|review|done|cancelled
 kb done <key> · kb cancel <key> · kb pri <key> high|med|low|none
@@ -40,9 +48,16 @@ kb lbl <key> +bug -ui         # labels: bug docs duplicate enhancement ui featur
                               #    label goes into the LABELS palette first, and into this file.
 kb desc <key> "description"   # set or overwrite a task description (used when grooming the backlog)
 kb note <key> "text"          # a standalone comment (rarely needed — kb review covers it)
-kb link <key> <key>           # link two tasks (the board draws a line) · kb unlink to unlink
+kb check <key> <n>            # tick checklist item n (from 1, in the order show/take print them)
+                              # · kb uncheck <key> <n> clears it. Answers "- [x] item (2 open)"
+kb link <key> <key> [child|parent]   # link two tasks (the board draws a line); `child` makes the
+                              # second task a sub-task of the first, `parent` its parent, no word
+                              # = plain related · kb unlink to unlink
 kb block <key> "why" · kb unblock <key>
-kb info <proj>                # path, deploy_skill, server, pm2, domain
+kb info <proj>                # path, deploy_skill, server, pm2, domain, the project's description
+                              # (the owner's context for work — read it) and "docs: CLAUDE.md,
+                              # README.md" — the documents to read before the task; "docs: no
+                              # CLAUDE.md — read README.md instead" is a signal, not an empty line
 kb svc <proj>                 # live status of the project's services (local pm2 or your own PANEL_URL)
 kb sync                       # state of the sync queue (or "sync is off" in local-only mode)
 ```
@@ -92,15 +107,18 @@ Claude takes a task as far as *review* and stops. Only the user moves anything t
 **When the prompt lists specific keys** (the 📋 button on the "To do" column produces them) those
 are SPECIFIC tasks, not a queue. Take each one with `kb show <key>` (NOT `kb take`, which pulls
 ONE next task from the project's `todo`) and **move it to prep right away: `kb mv <key> prep`** —
-`kb show` does not change the status. If `kb show` printed `> 👤 Send back: …`, the task was
-returned: open the `📎` screenshots with Read and act on that note FIRST. Then follow steps 2–6
+`kb show` does not change the status. If `kb show` printed `> 👤 [date] Send back: …`, the task was
+returned — the date tells a fresh send-back from an old one you already answered: open the `📎` screenshots with Read and act on that note FIRST. Then follow steps 2–6
 for each. Use `kb take X` only when asked to "work through project X" without specific keys.
 
 1. `kb take X` — take a task (lands in prep; description and issue are already in the output).
-   "empty" → report it and stop. `> 👤 …` is a note from a send-back, act on it first.
+   "empty" → report it and stop. "empty (N blocked)" is NOT an empty column: every card in To do
+   is blocked — list them (`kb ls X -s todo`) and report that, not "nothing to do". `> 👤 …` lines are what the human wrote since your last report
+   (a send-back and its follow-ups) — act on all of them first.
    `📎 <path>` — open the screenshot with Read.
 2. **HARD RULE — starting a task (never skip, even for a one-line change).** `kb info X` → go to
-   `path`. Before any code you MUST read: (a) the project's `CLAUDE.md` if it has one — **and if
+   `path`; its `description:` and `docs:` lines say what the owner wants you to know and which
+   documents the project has. Before any code you MUST read: (a) the project's `CLAUDE.md` if it has one — **and if
    it does not, find where the project keeps its architecture or research document (`README.md`,
    `EXPERIMENTS.md`, `docs/`) and read that; apply the "doc in the same commit" rule to it**;
    (b) the deploy skill at `deploy_skill_path` from `kb info`, if one is set. The matching commit
@@ -126,7 +144,9 @@ for each. Use `kb take X` only when asked to "work through project X" without sp
    The generic `deploy` skill ships with the board (`skills/deploy/`) and works purely off
    `kb info` data. Production commands (ssh/rsync) will ask for confirmation — that is expected.
 5. `kb review <key> "<two plain sentences: 1) what the problem was 2) how you solved it>"` → take
-   the next one.
+   the next one. **If the task has a checklist, tick each item as you finish it (`kb check <key>
+   <n>`).** Before review every item is either ticked or named in the note as not done — the human
+   accepts the task by those boxes, and an unticked done item reads as undone.
 6. Stuck, or the decision is the human's → `kb block <key> "reason"` and move on.
 7. At the end, a one-line summary: how many in review, how many blocked.
 
@@ -161,7 +181,9 @@ One line of summary at the end.
 - **You found an unrelated problem along the way** → do not fix it silently. Create a task
   (`kb add <proj> "..." -d "..."`) and ask in chat: do it now, defer it, or is it for the human.
 - **Related tasks solved together** → take both at once (both in doing), fix them in one pass and
-  link them with `kb link`.
+  link them with `kb link`. `kb show`/`kb take` print a task's links as `↑ parent KEY title
+  (status)`, `↓ subtask …`, `↔ related …` — look at them before you start: a linked task in To do
+  is usually meant to go together with this one, and a parent explains why the task exists.
 - **A discussion or question task** (no code): study it in `prep`, put the full answer in
   `kb note <key> "..."`, then `kb mv <key> review`. You write no code and do not move it to done.
 - A "check whether the service is alive" task → `kb svc <proj>` (one line per service, no ssh).

package/src/config.js

@@ -38,3 +38,4 @@ export const allowedHosts = () => env('KB_ALLOWED_HOSTS').split(',').map((s) =>
 export const langOverride = () => env('KB_LANG');
 export const ghOwnerEnv = () => env('KB_GH_OWNER');
 export const ghRepoEnv = () => env('KB_GH_REPO');
+export const ghBinEnv = () => expandPath(env('KB_GH_BIN'));

package/src/sync/github.js

@@ -1,11 +1,13 @@
 import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { db, ghOwner, ghRepo, uiLang } from '../db.js';
+import { ghBinEnv } from '../config.js';
 const GH_CANDIDATES = [
   '/opt/homebrew/bin/gh', '/usr/local/bin/gh', '/usr/bin/gh',
   '/home/linuxbrew/.linuxbrew/bin/gh', `${process.env.HOME}/.local/bin/gh`,
 ];
-const GH = GH_CANDIDATES.find((p) => existsSync(p)) || 'gh';
+const GH_FOUND = GH_CANDIDATES.find((p) => existsSync(p)) || 'gh';
+const ghBin = () => ghBinEnv() || GH_FOUND;
 
 const PERMANENT = [
   /validation failed/i,
@@ -19,7 +21,7 @@ export function isPermanent(stderr) {
 
 export function gh(args, { timeout = 60000 } = {}) {
   return new Promise((resolve, reject) => {
-    execFile(GH, args, { timeout, maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
+    execFile(ghBin(), args, { timeout, maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
       if (err) {
         const e = new Error((stderr || err.message || '').trim().slice(0, 500));
         e.permanent = isPermanent(String(stderr));