claude-review-hub 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 goldynlabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,244 @@
+<div align="center">
+
+<img src="logo.svg" alt="" width="96" height="96" />
+
+# Claude Review Hub
+
+**Pull request review that actually reads the code, in a dashboard you control.**
+
+[![npm](https://img.shields.io/npm/v/claude-review-hub?color=d77757)](https://www.npmjs.com/package/claude-review-hub)
+[![license](https://img.shields.io/badge/license-MIT-d77757)](LICENSE)
+[![node](https://img.shields.io/badge/node-%3E%3D20-d77757)](https://nodejs.org)
+
+</div>
+
+Point it at a repo, paste a PR number, and Claude Code reviews it the way a
+senior engineer would: it clones the branch into a worktree, reads the diff
+against the real codebase, and comes back with findings that cite evidence.
+You decide what gets posted.
+
+```console
+$ npx claude-review-hub "C:/Source code/your-repo"
+
+  ✳️  Claude Review Hub
+  project : C:/Source code/your-repo
+  skill   : azure-pr-master installed
+  skill   : github-pr-master installed
+  host    : Azure DevOps
+  org     : your-org
+  url     : http://localhost:4319
+
+  Keep this terminal open. Press Ctrl+C to stop the dashboard.
+```
+
+---
+
+## 😵 The problem
+
+Reviewing a pull request properly is expensive, so it mostly does not happen.
+
+- **The diff lies.** A three-line change is safe or catastrophic depending on
+  who calls it, and the PR page will not tell you which. Finding out means
+  checking out the branch and grepping the repo.
+- **Bot reviewers are noise.** They read the diff and nothing else, so they
+  flag style and miss the tenant id that stopped being filtered. After a week
+  of that, nobody reads their comments.
+- **The terminal is not a record.** You can ask an agent to review a PR in a
+  chat window today, but tomorrow the session is gone, the reasoning is gone,
+  and nothing connects what it said to what you posted.
+- **You cannot trust what you cannot see.** An agent with write access to your
+  pull requests is a liability unless you know the exact words it is about to
+  send, before it sends them.
+
+## ✨ What Claude Review Hub does about it
+
+**It reads the repository, not just the patch.** Every PR gets a detached git
+worktree of the actual branch. Claude opens the files, follows the call sites,
+and reads your `CLAUDE.md` and conventions, because the tool installs into your
+project and runs from its root.
+
+**Findings come with evidence and a confidence score.** Not "consider
+refactoring this". A finding names the file and line, states the input or state
+that produces the wrong result, and cites what it checked.
+
+**You can argue with it.** Disagree with a finding? Hit **Challenge**, type
+your counter-argument, and an adversarial re-check runs against it. The new
+verdict is appended, never overwritten, so the disagreement stays on the
+record.
+
+**Nothing is sent unseen.** Every control that sends a prompt to the agent
+opens one confirmation showing the exact prompt, with a note box to aim it and
+an Edit control to rewrite it for that one request. Anything that writes to the
+pull request is marked before you click.
+
+**It stays yours.** Sessions, findings, verdicts and the full event log live in
+the repo you reviewed. Nothing to host, no extra account, no analytics: the
+dashboard runs on localhost for as long as your terminal is open, and the only
+thing that leaves the machine is what Claude Code and your own CLIs already
+send.
+
+---
+
+## ⚡ Quick start
+
+```bash
+# From inside the repo you want to review
+cd your-repo
+npx claude-review-hub
+
+# Or point it at one
+npx claude-review-hub "C:/Source code/your-repo"
+```
+
+That single command installs the review skills into the project, hides the
+tool's own files from git through `.git/info/exclude` (your `.gitignore` is
+never touched, so the repo shows no modified file), and opens the dashboard on
+<http://localhost:4319>.
+
+It is idempotent. Run it again after an update and it refreshes the skills in
+place. Running it in a second repo does not clash: a port already in use is
+skipped and the banner names the one it took.
+
+### 🧰 Requirements
+
+| | |
+|---|---|
+| Node | 20 or newer |
+| Claude Code | Signed in on this machine, with a plan that allows Sonnet and Opus |
+| Azure DevOps | `az login`, plus `az extension add --name azure-devops` |
+| GitHub | `gh auth login` |
+| Repos | A local checkout of every repository whose PRs you review |
+
+Install only the CLI for the host you use. Which host a repo is on is read from
+its git remote, so having both CLIs is never ambiguous: the sidebar names the
+host in play, and every button about a pull request drives that host's CLI.
+With one CLI installed the dashboard shows one account and the agent is told
+about one host; the other is listed as not installed rather than as broken.
+
+---
+
+## 🔁 The loop
+
+```
+  paste PR ids  →  worktree + diff  →  findings
+                                      ↓
+  post / reply / approve   ←   challenge
+
+  the chat box reaches every one of those steps
+```
+
+**1. Start a session.** The PR box is free text. Ids, full URLs, or a sentence:
+`4821 4830 focus on the migration path`. Anything that is not a PR id
+becomes context for the run. One session can span several PRs and several
+repositories.
+
+**2. Pick what "review" means.** Criteria are configured in the tool, not
+buried in a prompt file. A **profile** holds review dimensions (correctness,
+security, blast radius, project rules, or your own), extra context, include and
+exclude globs, and a severity floor. The shipped profiles are a starting point;
+Settings is where you make them yours.
+
+**3. Read the findings.** Each one carries severity, confidence, file and line,
+and the evidence behind it. Dismiss what you do not want. Challenge what you
+doubt.
+
+**4. Act on the PR.** Post a single finding or all of them, reply to a thread,
+set a thread's state, approve, reject, wait for the author, or merge. Every one
+of those opens the confirmation first.
+
+**5. Ask for anything else.** The chat box drives the same operations the
+buttons do, in the same session, landing in the same event log. The buttons are
+the shortcuts; the chat box is the whole surface.
+
+Existing PR comments are deliberately **not** fed into the review pass, so the
+first read is unbiased. They enter Claude's context only when you reply to a
+thread or ask about one.
+
+---
+
+## 🔧 Under the hood
+
+The dashboard is not a wrapper around a chatbot. The server keeps the record;
+the agent does the work with your own CLIs.
+
+- **A detached worktree per PR**, built from the local checkout you already
+  have. Nothing is downloaded twice, and your working tree is never touched.
+- **The server produces the diff**, splits it per file, and hands it over.
+  Claude spends its context reading code, not reconstructing patches.
+- **One definition of every operation.** A reply typed in chat and one clicked
+  on a thread card are the same function call, and both land in the append-only
+  event log that the UI is drawn from. Close the browser mid-review and reopen
+  it: the session is exactly where you left it.
+- **Prompt templates are editable for good.** Settings > Prompts lists every
+  action and lets its wording be replaced, which reaches the hover preview, the
+  confirmation, the docs tab and the agent together. The built-in wording can
+  always be restored.
+
+### 📁 What it writes to your project
+
+```
+<project>/
+  .claude/skills/azure-pr-master/     the Azure DevOps procedure, refreshed on start
+  .claude/skills/github-pr-master/    the GitHub procedure, refreshed on start
+  .review-tool/                       hidden from git, never committed
+    config/settings.json
+    config/profiles.json              your review criteria
+    config/prompts.json               your prompt overrides
+    data/review.db                    sessions, PRs, findings, evidence, verdicts
+    data/sessions/<id>/events.jsonl   append-only log, the UI's source of truth
+    temp/worktrees/<repo>-pr<id>/
+    temp/diffs/<repo>-pr<id>/
+```
+
+Everything lives in the repo it reviewed, so nothing is lost when npm clears
+its npx cache.
+
+---
+
+## ⚙️ Settings worth knowing
+
+| Setting | Default | Why |
+|---|---|---|
+| `allowCodeEdits` | off | Review is read-only. Turn it on for auto-fix or opening a PR |
+| `permissionMode` | auto | `ask` confirms every write and shell command the agent attempts. Separate from your own clicks, which are always confirmed |
+| `models` | Sonnet to review, Opus to challenge and chat | The broad sweep is wide, the adversarial pass is hard |
+| `worktreeTtlHours` | 72 | Worktrees stay browsable, then are pruned on start |
+| `sessionLanguage` | en | What Claude writes into the dashboard. The prompts it is sent stay English |
+| `pullRequestLanguage` | en | What Claude writes into the pull request |
+
+## ⌨️ Commands
+
+| Command | What it does |
+|---|---|
+| `npx claude-review-hub` | Install what the repo needs, then open the dashboard |
+| `npx claude-review-hub <repo>` | Same, for a repo other than the current directory |
+| `npx claude-review-hub install` | Only install the skills and the git exclude entries |
+| `npx claude-review-hub --port 4320` | Prefer a specific port |
+| `npx claude-review-hub uninstall` | Remove the skills and the git exclude entries |
+| `npx claude-review-hub uninstall --purge` | Also delete `.review-tool/`: sessions, findings and worktrees |
+
+`Ctrl+C` stops the dashboard, and closing the terminal stops it too.
+
+---
+
+## 🛠️ Working on the tool
+
+`npx` runs the built output, so a source change only reaches it after a
+rebuild. To run the sources instead, against a real repo:
+
+```bash
+git clone https://github.com/goldynlabs/claude-review-hub
+cd claude-review-hub
+npm install
+npm run dev -- "C:/Source code/your-repo"   # the repo is remembered
+npm run dev                                 # later runs reuse it
+```
+
+`server/` and `web/` reload on save. `skill/` needs a restart, because a
+project gets its copy of the skills at start-up. Ports are chosen at start-up
+and printed, so several instances can run at once. `npm run typecheck` before
+opening a PR.
+
+## 📄 License
+
+MIT. See [LICENSE](LICENSE).

package/bin/claude-review-hub.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { installSkill, isGitRepo } from "../scripts/install-skill.mjs";
+import { uninstallTool } from "../scripts/uninstall.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const serverEntry = path.join(here, "..", "server", "dist", "index.js");
+
+const args = process.argv.slice(2);
+const COMMANDS = ["install", "uninstall", "version"];
+const command = COMMANDS.includes(args[0]) ? args[0] : "start";
+
+if (args.includes("-h") || args.includes("--help")) {
+  console.log(`
+  claude-review-hub [command] [repo path] [options]
+
+  The repo path is where the review happens. It defaults to the current
+  directory, so inside a repo 'claude-review-hub' on its own is enough.
+
+  (no command)   Open the dashboard for that repo
+  install        Only install the skill and the git exclude entries
+  uninstall      Remove them again (add --purge to delete .review-tool/ as
+                 well: sessions, findings and review worktrees)
+  version        Print the tool version
+
+  --port <n>     Preferred port (default 4319). If it is taken, the next
+                 free one is used.
+
+  Examples:
+    npx claude-review-hub "C:\\Source code\\your-repo"
+    cd your-repo && npx claude-review-hub
+`);
+  process.exit(0);
+}
+
+function flag(name) {
+  const index = args.indexOf(name);
+  return index === -1 ? undefined : args[index + 1];
+}
+
+/** The repo to review: the first bare argument that is not a flag's value. */
+const positional = args.find(
+  (arg, index) => !arg.startsWith("-") && !COMMANDS.includes(arg) && !args[index - 1]?.startsWith("-"),
+);
+const target = path.resolve(flag("--project") ?? positional ?? process.cwd());
+
+if (command === "version") {
+  const pkg = JSON.parse(fs.readFileSync(path.join(here, "..", "package.json"), "utf8"));
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (!isGitRepo(target)) {
+  console.error(`\n  ${target} is not a git repository.\n  Pass the repo to review: npx claude-review-hub <path>\n`);
+  process.exit(1);
+}
+
+console.log(`\n  ${path.basename(target)}`);
+
+if (command === "uninstall") {
+  uninstallTool(target, { purge: args.includes("--purge") });
+  console.log("");
+  process.exit(0);
+}
+
+// One command does the whole thing: the skill is (re)installed on every start,
+// so an updated tool never leaves a stale skill behind in a project.
+installSkill(target);
+
+if (command === "install") {
+  console.log(`\n  Ready. Run 'npx claude-review-hub' in that repo to open the dashboard.\n`);
+  process.exit(0);
+}
+
+if (!fs.existsSync(serverEntry)) {
+  console.error(`\n  The tool has not been built yet.\n  Run 'npm run build' in ${path.join(here, "..")}\n`);
+  process.exit(1);
+}
+
+const port = flag("--port");
+if (port) process.env.PORT = port;
+process.env.REVIEW_TOOL_PROJECT = target;
+
+await import(new URL(`file://${serverEntry.replace(/\\/g, "/")}`));

package/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg"  viewBox="0 0 48 48" width="480px" height="480px" baseProfile="basic"><rect width="36" height="24" x="6" y="18" fill="#d77757"/><rect width="3" height="9" x="9" y="39" fill="#d77757"/><rect width="3" height="9" x="15" y="39" fill="#d77757"/><rect width="3" height="9" x="30" y="39" fill="#d77757"/><rect width="3" height="9" x="36" y="39" fill="#d77757"/><rect width="7.5" height="6" y="33" fill="#d77757"/><rect width="7.5" height="6" x="40.5" y="33" fill="#d77757"/><rect width="9" height="9" x="12" y="24"/><rect width="9" height="9" x="27" y="24"/><rect width="3" height="6" x="22.5" y="22.5" transform="rotate(90 24 25.5)"/><rect width="3" height="7" x="37" y="22" transform="rotate(90 38.5 25.5)"/><rect width="3" height="7" x="8" y="22" transform="rotate(90 9.5 25.5)"/></svg>

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "claude-review-hub",
+  "version": "0.1.0",
+  "description": "A local dashboard that reviews pull requests with Claude Code",
+  "license": "MIT",
+  "author": "goldynlabs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/goldynlabs/claude-review-hub.git"
+  },
+  "bugs": {
+    "url": "https://github.com/goldynlabs/claude-review-hub/issues"
+  },
+  "homepage": "https://github.com/goldynlabs/claude-review-hub#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "claude",
+    "code-review",
+    "pull-request",
+    "azure-devops",
+    "github",
+    "dashboard"
+  ],
+  "workspaces": [
+    "server",
+    "web"
+  ],
+  "bin": {
+    "claude-review-hub": "bin/claude-review-hub.mjs"
+  },
+  "files": [
+    "LICENSE",
+    "logo.svg",
+    "bin",
+    "scripts",
+    "skill",
+    "server/dist",
+    "web/dist"
+  ],
+  "scripts": {
+    "dev": "node scripts/dev.mjs",
+    "dev:server": "tsx watch server/src/index.ts",
+    "dev:web": "npm -w web run dev",
+    "build": "npm -w server run build && npm -w web run build",
+    "typecheck": "npm -w server run typecheck && npm -w web run typecheck",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.272",
+    "better-sqlite3": "^11.7.0",
+    "cors": "^2.8.5",
+    "express": "^4.21.2",
+    "nanoid": "^5.0.9",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2"
+  }
+}

package/scripts/dev.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+/**
+ * Development launcher.
+ *
+ * `claude-review-hub` runs the built output, so every source change would need a
+ * build and a restart. This runs the sources instead: the server under
+ * `tsx watch`, the dashboard under Vite, both pointed at a real repo to
+ * review. Ports are chosen at start-up and handed to Vite, so a claude-review-hub
+ * already running on 4319 cannot silently steal the proxy target.
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { installSkill, isGitRepo } from "./install-skill.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.join(here, "..");
+// Whatever repo was last developed against; plain `npm run dev` reuses it.
+const lastFile = path.join(root, ".dev-project");
+
+const args = process.argv.slice(2);
+
+if (args.includes("-h") || args.includes("--help")) {
+  console.log(`
+  npm run dev [-- <repo path>] [--api-port <n>] [--web-port <n>]
+
+  Runs the tool from source, with hot reload, against a repo to review.
+  The repo is remembered, so later runs can be just 'npm run dev'.
+
+  Examples:
+    npm run dev -- "C:\\Source code\\your-repo"
+    npm run dev
+`);
+  process.exit(0);
+}
+
+function flag(name) {
+  const index = args.indexOf(name);
+  return index === -1 ? undefined : args[index + 1];
+}
+
+/** The repo path, given bare: anything that is not a flag or a flag's value. */
+const positional = args.find((arg, index) => !arg.startsWith("-") && !args[index - 1]?.startsWith("-"));
+const remembered = fs.existsSync(lastFile) ? fs.readFileSync(lastFile, "utf8").trim() : "";
+const chosen = flag("--project") ?? positional ?? remembered;
+const target = chosen ? path.resolve(chosen) : "";
+
+if (!chosen) {
+  console.error(`
+  Say which repo to review, once:
+
+      npm run dev -- "C:\\Source code\\your-repo"
+
+  It is remembered after that, so later runs are just 'npm run dev'.
+`);
+  process.exit(1);
+}
+
+if (!isGitRepo(target)) {
+  console.error(`\n  ${target} is not a git repository.\n`);
+  process.exit(1);
+}
+
+fs.writeFileSync(lastFile, target);
+
+/**
+ * Asked by connecting, not by binding: Windows lets a wildcard bind succeed
+ * while another process holds the same port on a specific address, so a bind
+ * probe calls ports free that Express or Vite then fails to take.
+ */
+function answers(port, host) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ port, host });
+    const done = (result) => {
+      socket.destroy();
+      resolve(result);
+    };
+    socket.setTimeout(500);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+  });
+}
+
+/** The dev server must own the port Vite proxies to, so it is picked up front. */
+async function free(from, { skip = [], attempts = 20 } = {}) {
+  for (let candidate = from; candidate < from + attempts; candidate += 1) {
+    // `skip` holds ports already handed to a child that has not bound yet;
+    // without it both halves can be told to use the same one.
+    if (skip.includes(candidate)) continue;
+    // Both families: Express listens on IPv4 and IPv6, Vite resolves localhost
+    // to ::1 first on Windows.
+    if (!(await answers(candidate, "127.0.0.1")) && !(await answers(candidate, "::1"))) return candidate;
+  }
+  throw new Error(`No free port from ${from}.`);
+}
+
+const apiPort = Number(flag("--api-port")) || (await free(4319));
+const webPort = Number(flag("--web-port")) || (await free(4318, { skip: [apiPort] }));
+
+// Same as a real start: the repo gets the current skill before anything runs.
+installSkill(target, { quiet: true });
+
+console.log(`
+  Claude Review Hub (dev, hot reload)
+  project : ${target}
+  api     : http://localhost:${apiPort}
+  open    : http://localhost:${webPort}
+
+  Editing server/ or web/ reloads by itself. Editing skill/ needs a restart.
+  Ctrl+C stops both.
+`);
+
+const env = {
+  ...process.env,
+  REVIEW_TOOL_PROJECT: target,
+  PORT: String(apiPort),
+  // Read by web/vite.config.ts, so the proxy always finds the server above.
+  API_PORT: String(apiPort),
+  // The proxy target is fixed now, so the server must not drift off this port.
+  REVIEW_TOOL_STRICT_PORT: "1",
+};
+
+// The local entry points are run by node directly. Going through npx and a
+// shell would leave the real processes as grandchildren, and on Windows those
+// survive a kill and keep holding the ports.
+const bin = (...parts) => path.join(root, "node_modules", ...parts);
+const children = [
+  spawn(process.execPath, [bin("tsx", "dist", "cli.mjs"), "watch", "server/src/index.ts"], {
+    cwd: root,
+    env,
+    stdio: "inherit",
+  }),
+  spawn(process.execPath, [bin("vite", "bin", "vite.js"), "--port", String(webPort), "--strictPort"], {
+    cwd: path.join(root, "web"),
+    env,
+    stdio: "inherit",
+  }),
+];
+
+let stopping = false;
+const stopAll = () => {
+  if (stopping) return;
+  stopping = true;
+  for (const child of children) {
+    if (!child.pid) continue;
+    // tsx runs the server in a child of its own, so the whole tree has to go;
+    // a survivor would hold the port and quietly serve stale code later.
+    if (process.platform === "win32") {
+      spawn("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", shell: true });
+    } else {
+      child.kill();
+    }
+  }
+  setTimeout(() => process.exit(0), 1500).unref();
+};
+
+process.on("SIGINT", stopAll);
+process.on("SIGTERM", stopAll);
+// One half dying is not a working dashboard, so the other goes with it.
+for (const child of children) child.on("exit", stopAll);

package/scripts/install-skill.mjs

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.join(here, "..", "skill");
+
+/** One skill per host the tool supports, discovered rather than listed twice. */
+export const SKILL_NAMES = fs
+  .readdirSync(skillRoot, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(skillRoot, entry.name, "SKILL.md")))
+  .map((entry) => entry.name);
+
+/** What the tool adds to a repo, and what it must therefore keep out of git. */
+export const EXCLUDED_PATHS = [".review-tool/", ...SKILL_NAMES.map((name) => `.claude/skills/${name}/`)];
+
+/**
+ * Puts the forked per-host skills in the target repo and keeps the tool's own
+ * state out of that repo's history. Idempotent: safe to run on every start.
+ */
+export function installSkill(target, { quiet = false } = {}) {
+  const log = (message) => !quiet && console.log(message);
+  const done = { skill: false, excluded: false };
+
+  for (const name of SKILL_NAMES) {
+    const skillTarget = path.join(target, ".claude", "skills", name);
+    const sourceFile = path.join(skillRoot, name, "SKILL.md");
+    const targetFile = path.join(skillTarget, "SKILL.md");
+    const current = fs.existsSync(targetFile) ? fs.readFileSync(targetFile, "utf8") : null;
+    const latest = fs.readFileSync(sourceFile, "utf8");
+
+    if (current !== latest) {
+      fs.mkdirSync(path.dirname(skillTarget), { recursive: true });
+      fs.cpSync(path.join(skillRoot, name), skillTarget, { recursive: true });
+      log(`  skill     ${current === null ? "installed" : "updated"} -> .claude/skills/${name}`);
+      done.skill = true;
+    }
+  }
+
+  // .git/info/exclude, not .gitignore: that file is tracked, and a work repo
+  // must not show a modified file just because the tool was started in it.
+  const exclude = excludeFile(target);
+  if (exclude) {
+    const existing = fs.existsSync(exclude) ? fs.readFileSync(exclude, "utf8") : "";
+    const present = new Set(existing.split(/\r?\n/).map((line) => line.trim()));
+    const missing = EXCLUDED_PATHS.filter((line) => !present.has(line));
+    if (missing.length) {
+      fs.mkdirSync(path.dirname(exclude), { recursive: true });
+      const prefix = !existing || existing.endsWith("\n") ? "" : "\n";
+      fs.appendFileSync(exclude, `${prefix}${missing.join("\n")}\n`);
+      log("  ignored   locally, in .git/info/exclude (your .gitignore is untouched)");
+      done.excluded = true;
+    }
+  }
+
+  return done;
+}
+
+export function isGitRepo(target) {
+  return fs.existsSync(path.join(target, ".git"));
+}
+
+/**
+ * Resolves .git/info/exclude, following the gitdir pointer when the repo is
+ * itself a worktree (there .git is a file, not a directory).
+ */
+export function excludeFile(target) {
+  const dotGit = path.join(target, ".git");
+  if (!fs.existsSync(dotGit)) return null;
+  if (fs.statSync(dotGit).isDirectory()) return path.join(dotGit, "info", "exclude");
+  const pointer = fs.readFileSync(dotGit, "utf8").match(/^gitdir:\s*(.+)$/m);
+  if (!pointer) return null;
+  return path.join(path.resolve(target, pointer[1].trim()), "info", "exclude");
+}