basis-design 0.1.0 → 0.2.0

package/README.md

@@ -18,12 +18,12 @@ npx basis-design
 
 Or install it once with `npm install -g basis-design` and start it with `basis`. Open http://localhost:5320. Basis starts Claude Code by default (shown as Claude in the picker above the chat); switch to Codex there. Basis needs Node.js 22.12 or later and `git` on the PATH.
 
-- **Claude Code:** log in once with `claude` in a terminal. Basis starts it through `@agentclientprotocol/claude-agent-acp`.
+- **Claude Code:** install it and log in once with `claude` in a terminal. Basis runs your own Claude Code through `@agentclientprotocol/claude-agent-acp`, which npx fetches on first use without a copy of Claude Code of its own. If Basis does not find it, set `CLAUDE_CODE_EXECUTABLE` to its path.
 - **Codex:** log in once with `codex login`. Basis starts it through `npx @agentclientprotocol/codex-acp`, at a fixed version that npx fetches on first use.
 
 Usage counts against your own plan. A turn can take up to three agent runs (the turn and up to two fix-ups), and ×2 or ×3 alternatives multiply that.
 
-The first install is large, about 300 MB, because the Claude adapter brings its own copy of Claude Code. To work on Basis itself, clone the repository and run `npm install` and `npm run dev`.
+To work on Basis itself, clone the repository and run `npm install` and `npm run dev`.
 
 | Variable | Default | Purpose |
 | --- | --- | --- |
@@ -37,11 +37,12 @@ The first install is large, about 300 MB, because the Claude adapter brings its
 
 Each project is a workspace of its own: its own design system, history, chat and review. Switch, create and open projects from the menu with the project's name at the top left.
 
-A project can link the **product repo** it designs for (project menu, **Link product repo…**). The agent reads and searches it without asking, to match the product's look, components and terms, and never writes there: writes outside the workspace are refused. **New project…** can also start from a product repo: the project takes the repo folder's name unless you give one, links the repo and starts by bringing in its design. **Bring in its design** (offered when you link, and in the project menu) starts a guided turn: the agent maps the repo's tokens onto `design-system.json`, restyles the components and patterns to resemble the product's, writes what it learned to `product.md` (where the tokens live, an inventory of the product's components and their Basis counterparts, terms to reuse) and opens a review.
+A project can link the **product repo** it designs for (project menu, **Link product repo…**): pick it from the repos Basis finds in your usual code folders, choose it with **Browse…** in your system's folder dialog, or paste its path. The agent reads and searches it without asking, to match the product's look, components and terms, and never writes there: writes outside the workspace are refused. **New project…** can also start from a product repo: the project takes the repo folder's name unless you give one, links the repo and starts by bringing in its design. **Bring in its design** (offered when you link, and in the project menu) starts a guided turn: the agent maps the repo's tokens onto `design-system.json`, restyles the components and patterns to resemble the product's, writes what it learned to `product.md` (where the tokens live, an inventory of the product's components and their Basis counterparts, terms to reuse) and opens a review.
 
 - **New project** starts from Basis' defaults, or as a copy of the open project's tokens and components (not its history). It lives in `~/.basis/workspaces/`.
 - **Open folder** adds a workspace from anywhere, or an empty or new folder for Basis to set up, inside a product repo for instance. Basis refuses a folder that already has other files, so it never starts a history in someone's project.
 - Switching waits while the agent works. The agent of the project you leave stops, and coming back resumes its conversation, so it remembers where you were. The export remembers its target folder per project.
+- When Basis' starter components improve, the files a project never changed update by themselves. For the ones the agent changed, the project menu offers a guided turn that brings the improvements in, as a review, keeping the project's own look.
 - Removing a project from the list never deletes its folder. Earlier versions kept the project list in the Basis folder; it moves to `~/.basis` on first start, and its projects stay where they are. The `./workspace` of versions before projects becomes the first project.
 
 ## The workspace
@@ -106,6 +107,7 @@ Every `components/*.specimen.tsx` file becomes a gallery section and a sidebar e
   - a README on wiring it up.
 
   The kit needs React 18+ and CSS Modules, nothing else. The other tabs export the token formats one at a time.
+- **Verification kit:** proof that a feature was built as its view shows. The **Verification kit** tab photographs every screen of every view at fixed widths (375, 768 and 1440 pixels, full page, unless the view's flow block sets `capture`) and packages the screenshots with a static, clickable copy of the design and two scripts, as a zip or into `basis-verify/` in the product's folder (the linked repo by default). The agent that implements the feature runs `capture.mjs` to photograph the design and its implementation on the same machine with the same settings, and `compare.mjs` to compare them pixel for pixel, aiming at 0% difference. Parts allowed to differ are named exceptions in `exceptions.json`, each with a reason. Basis takes the screenshots with Playwright's Chromium when it is installed (`npx playwright install chromium`), otherwise with Chrome or Edge; each screen is captured twice, and screens that render differently each time are reported, since nothing can match them.
 
 ## Privacy
 

package/capture.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Basis capture</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/capture/main.tsx"></script>
+  </body>
+</html>

package/package.json

@@ -1,68 +1,72 @@
-{
-  "name": "basis-design",
-  "version": "0.1.0",
-  "description": "Prompt a complete design system into existence with your own coding agent over ACP.",
-  "keywords": [
-    "design-system",
-    "design-tokens",
-    "react",
-    "claude-code",
-    "codex",
-    "agent-client-protocol"
-  ],
-  "license": "Apache-2.0",
-  "author": "Lucas Skog",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/sockulags/basis-design.git"
-  },
-  "type": "module",
-  "bin": {
-    "basis": "bin/basis.js"
-  },
-  "files": [
-    "bin",
-    "server",
-    "shared",
-    "src",
-    "template",
-    "index.html",
-    "preview.html",
-    "vite.config.ts",
-    "NOTICE"
-  ],
-  "engines": {
-    "node": ">=22.12.0"
-  },
-  "scripts": {
-    "dev": "tsx server/index.ts",
-    "start": "tsx server/index.ts",
-    "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test \"test/*.test.ts\"",
-    "lint": "oxlint",
-    "format": "prettier --write .",
-    "check": "tsc --noEmit && oxlint && prettier --check . && npm test"
-  },
-  "dependencies": {
-    "@agentclientprotocol/claude-agent-acp": "0.92.0",
-    "@agentclientprotocol/sdk": "^1.9.0",
-    "@types/react": "^19.3.0",
-    "@types/react-dom": "^19.3.0",
-    "@vitejs/plugin-react": "^6.1.2",
-    "axe-core": "^4.14.0",
-    "fflate": "^0.8.3",
-    "react": "^19.3.1",
-    "react-dom": "^19.3.1",
-    "tsx": "^4.23.15",
-    "typescript": "^7.0.2",
-    "vite": "^8.3.4",
-    "ws": "^8.22.0",
-    "zod": "^4.6.7"
-  },
-  "devDependencies": {
-    "@types/node": "^26.6.5",
-    "@types/ws": "^8.18.2",
-    "oxlint": "1.88.0",
-    "prettier": "3.9.10"
-  }
-}
+{
+  "name": "basis-design",
+  "version": "0.2.0",
+  "description": "Prompt a complete design system into existence with your own coding agent over ACP.",
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "react",
+    "claude-code",
+    "codex",
+    "agent-client-protocol"
+  ],
+  "license": "Apache-2.0",
+  "author": "Lucas Skog",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sockulags/basis-design.git"
+  },
+  "type": "module",
+  "bin": {
+    "basis": "bin/basis.js"
+  },
+  "files": [
+    "bin",
+    "server",
+    "shared",
+    "src",
+    "template",
+    "index.html",
+    "preview.html",
+    "capture.html",
+    "vite.config.ts",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "dev": "tsx server/index.ts",
+    "start": "tsx server/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"test/*.test.ts\"",
+    "test:e2e": "playwright test",
+    "template:history": "tsx scripts/template-history.ts",
+    "lint": "oxlint",
+    "format": "prettier --write .",
+    "check": "tsc --noEmit && oxlint && prettier --check . && npm test"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^1.9.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "axe-core": "^4.14.0",
+    "fflate": "^0.8.3",
+    "playwright-core": "1.64.1",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.4",
+    "ws": "^8.22.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.64.1",
+    "@types/node": "^26.6.5",
+    "@types/ws": "^8.18.2",
+    "oxlint": "1.88.0",
+    "prettier": "3.9.10"
+  }
+}

package/server/agent.ts

@@ -2,7 +2,6 @@ import { spawn, spawnSync, type ChildProcess } from "node:child_process";
 import { existsSync } from "node:fs";
 import { EventEmitter } from "node:events";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { createRequire } from "node:module";
 import path from "node:path";
 import { Readable, Writable } from "node:stream";
 import * as acp from "@agentclientprotocol/sdk";
@@ -22,35 +21,52 @@ import { ALTERNATIVE_LABELS, describeTarget, MAX_ALTERNATIVES } from "../shared/
 import { loadChat, saveChat } from "./chatlog.ts";
 import { PRODUCT_FILE, relativeInside } from "./paths.ts";
 import { AGENT_BRIEF, FIRST_PROMPT_PREAMBLE } from "./brief.ts";
+import { CLAUDE_MISSING, findClaude } from "./claude.ts";
 import type { Workspace } from "./workspace.ts";
 
-const require = createRequire(import.meta.url);
-
 interface LaunchSpec {
   command: string;
   args: string[];
   shell: boolean;
   loginHint: string;
+  /** Variables the agent needs on top of Basis' own environment. */
+  env?: Record<string, string>;
+  /** Why the agent cannot start, shown instead of starting it. */
+  missing?: string;
+  /** Added when the agent exits on its own, for the failures an update fixes. */
+  exitHint?: string;
 }
 
-/** The Codex adapter Basis was tested with; npx fetches it on first use. */
+/**
+ * The adapters Basis was tested with, at fixed versions: an unpinned one would fetch whatever was published last.
+ * npx fetches each on first use and reuses it after (--prefer-offline, so Basis also starts offline).
+ */
+const CLAUDE_ACP = "@agentclientprotocol/claude-agent-acp@0.92.0";
 const CODEX_ACP = "@agentclientprotocol/codex-acp@2.2.2";
 
 /** How each supported agent is started. Both reuse the user's own CLI login, so no API keys are needed. */
 function launchSpec(id: AgentId): LaunchSpec {
+  // The end-to-end tests run a stand-in agent (test/e2e/fake-agent.mjs), since no CLI is logged in on CI.
+  if (process.env.BASIS_AGENT_SCRIPT) {
+    const script = path.resolve(process.env.BASIS_AGENT_SCRIPT);
+    return { command: process.execPath, args: [script], shell: false, loginHint: "" };
+  }
   if (id === "claude") {
-    const pkg = require.resolve("@agentclientprotocol/claude-agent-acp/package.json");
+    // Without --omit=optional the adapter's SDK brings its own copy of Claude Code; Basis runs the user's instead.
+    const claude = findClaude();
     return {
-      command: process.execPath,
-      args: [path.join(path.dirname(pkg), "dist", "index.js")],
-      shell: false,
+      command: "npx",
+      args: ["-y", "--prefer-offline", "--omit=optional", CLAUDE_ACP],
+      shell: true,
+      env: claude ? { CLAUDE_CODE_EXECUTABLE: claude } : undefined,
+      missing: claude ? undefined : CLAUDE_MISSING,
       loginHint: "Run `claude` in a terminal and log in, then restart the agent.",
+      exitHint: "If it keeps happening, update Claude Code with `claude update`.",
     };
   }
   return {
     command: "npx",
-    // A fixed version: an unpinned one would fetch whatever was published last on every start.
-    args: ["-y", CODEX_ACP],
+    args: ["-y", "--prefer-offline", CODEX_ACP],
     shell: true,
     loginHint: "Run `codex login` in a terminal, then restart the agent.",
   };
@@ -180,13 +196,17 @@ export class AgentHost extends EventEmitter<Events> {
     await this.stop();
     this.setState({ id: agentId, status: "starting", detail: "Starting agent…" });
     const spec = launchSpec(agentId);
+    if (spec.missing) {
+      this.fail(spec.missing);
+      return;
+    }
     // Through a shell, the command goes as one line: Node no longer accepts separate arguments there.
     const [command, args] = spec.shell ? [[spec.command, ...spec.args].join(" "), []] : [spec.command, spec.args];
     const proc = spawn(command, args, {
       cwd: this.workspace.dir,
       shell: spec.shell,
       stdio: ["pipe", "pipe", "pipe"],
-      env: agentEnv(),
+      env: { ...agentEnv(), ...spec.env },
       windowsHide: true,
     });
     this.proc = proc;
@@ -204,7 +224,8 @@ export class AgentHost extends EventEmitter<Events> {
       this.connection = undefined;
       this.sessionId = undefined;
       const tail = this.stderrTail.slice(-3).join(" ");
-      this.fail(`The agent exited (code ${code ?? "?"}).${tail ? ` ${tail}` : ""}`);
+      const hint = spec.exitHint ? ` ${spec.exitHint}` : "";
+      this.fail(`The agent exited (code ${code ?? "?"}).${tail ? ` ${tail}` : ""}${hint}`);
     });
 
     const stream = acp.ndJsonStream(

package/server/brief.ts

@@ -160,9 +160,20 @@ The rules that always apply:
   restyle or copy them inside a view: if a screen needs something they lack, extend the component or pattern,
   or add a pattern. A view's own code is layout and wiring; a small layout style inline or in a
   \`.module.css\` next to it is fine.
-- Fill views with realistic made-up data, consistent across the screens (the row you open is the one the
-  detail shows), in the product's language when a product repo is linked. Keep sample data in the view file or
-  a \`views/*-data.ts\` file.
+- A screen is the whole page as the product shows it at that size: its shell, navigation and page padding
+  included, filling the window. The verification kit photographs each screen alone at fixed widths, and the
+  implementation of the feature must match those images pixel for pixel.
+- Fill views with realistic data, consistent across the screens (the row you open is the one the detail
+  shows). When a product repo is linked, use the product's own data where you can find it (fixtures, seeds,
+  example responses, its wording), so the implementation can show exactly the same records. Otherwise make it
+  up in the product's language. Keep data in the view file or a \`views/*-data.ts\` file.
+- Screens must render the same every time: no \`Date.now()\`, \`new Date()\` without a fixed date, random
+  values, or animations and loading states that never settle. Basis captures each screen twice and reports
+  the ones that differ.
+- A flow block may say how its screens are captured: \`capture: { widths: [375, 768, 1440], height: "full",
+  themes: ["light"] }\` (those are the defaults). \`height\` is \`"full"\` for the whole page or a number for
+  exactly one viewport; add \`"dark"\` to \`themes\` when the product has a dark theme. Set widths to the
+  product's breakpoints when you know them.
 - Views are not exported with the design system and need no contract or index.
 - To review a view, show its specimen; \`rows\` picks screens by label or id (\`"rows": ["Shipment"]\`). The panes
   of a review move through the flow together, so before and after always show the same screen.
@@ -350,6 +361,24 @@ export function importInstruction(repo: string): string {
   ].join("\n");
 }
 
+/**
+ * The guided turn that brings a newer starter template into a workspace whose agent changed the starter files.
+ * `changes` is the part of template/CHANGES.md the workspace has not caught up with.
+ */
+export function templateInstruction(changes: string, files: string[]): string {
+  return [
+    "Basis has improved its starter template since this design system started from it. Bring the improvements below into this workspace's own components, patterns and views, in this turn.",
+    "",
+    changes,
+    "",
+    `1. The current template is in .basis/template/ (components/, patterns/, views/). These files here differ from it because they were changed: ${files.join(", ")}. Read each and its template version with your read tool; the list above says what changed, so you need no shell commands or diffs.`,
+    "2. Bring in each improvement where the workspace's file still has the part it concerns. Keep this design system's own look, tokens, variants and additions, and every contract. If the workspace already solves it another way, leave it.",
+    "3. Edit the files with your tools; never copy a template file over the workspace's own.",
+    "4. Write review.json showing the specimens that changed most (up to four), so the user compares before and after.",
+    "Finish with a short summary: which improvements you brought in and where, and what you left out and why.",
+  ].join("\n");
+}
+
 /** Prepended to the first prompt when the agent cannot take an appended system prompt. */
 export const FIRST_PROMPT_PREAMBLE =
   "You are working inside Basis. Read AGENTS.md in the current folder first and follow it: you edit only design-system.json, review.json, product.md and files under components/, patterns/ and views/.";

package/server/capture.ts

@@ -0,0 +1,128 @@
+import { chromium, type Browser, type LaunchOptions } from "playwright-core";
+import { READY_ATTRIBUTE, shotFile, type CaptureShot, type CaptureView } from "../shared/capture.ts";
+
+/*
+ * Taking the verification kit's screenshots: a headless browser opens each screen of each view on the capture
+ * page (capture.html) at the size its shots ask for. Everything that could make two runs differ is fixed: the
+ * device scale, the colour profile, text antialiasing, reduced motion. Each shot is taken twice, and a screen
+ * whose two images differ is reported as unstable, since nothing could ever match it pixel for pixel.
+ */
+
+/** Chromium flags that keep rendering the same between runs and machines of one platform. */
+export const CAPTURE_ARGS = [
+  "--force-color-profile=srgb",
+  "--font-render-hinting=none",
+  "--disable-lcd-text",
+  "--hide-scrollbars",
+];
+
+export interface CaptureBrowser {
+  browser: Browser;
+  name: string;
+  version: string;
+}
+
+/**
+ * Playwright's own Chromium when it is installed (`npx playwright install chromium`): the same build on every
+ * machine, which is what comparing screenshots wants. Otherwise the Chrome or Edge already on this computer.
+ */
+export async function launchCaptureBrowser(): Promise<CaptureBrowser> {
+  const candidates: { name: string; options: LaunchOptions }[] = [
+    { name: "Playwright Chromium", options: {} },
+    { name: "Google Chrome", options: { channel: "chrome" } },
+    { name: "Microsoft Edge", options: { channel: "msedge" } },
+  ];
+  for (const { name, options } of candidates) {
+    try {
+      const browser = await chromium.launch({ ...options, headless: true, args: CAPTURE_ARGS });
+      return { browser, name, version: browser.version() };
+    } catch {
+      // Not installed; try the next one.
+    }
+  }
+  throw new Error(
+    "No browser to take the screenshots with. Install Google Chrome or Microsoft Edge, or run `npx playwright install chromium`.",
+  );
+}
+
+export interface Shot extends CaptureShot {
+  view: string;
+  screen: string;
+  file: string;
+  png: Buffer;
+  /** The image's height in pixels: the page's height for full-page shots. */
+  imageHeight: number;
+  /** False when two captures of the shot differed, so the screen does not render the same every time. */
+  stable: boolean;
+  /** Set when the screen threw while rendering. */
+  failed: boolean;
+}
+
+export interface CaptureResult {
+  views: CaptureView[];
+  problems: string[];
+  shots: Shot[];
+}
+
+/** The height stored in a PNG's IHDR chunk. */
+function pngHeight(png: Buffer): number {
+  return png.length >= 24 ? png.readUInt32BE(20) : 0;
+}
+
+/**
+ * Captures every shot of every view the capture page at `pageUrl` lists. `pageUrl` is the page without a query
+ * (".../capture.html" on the preview server, ".../index.html" in the kit's copy of the design).
+ */
+export async function captureViews(
+  pageUrl: string,
+  browser: Browser,
+  onProgress?: (done: number, total: number) => void,
+): Promise<CaptureResult> {
+  const context = await browser.newContext({
+    deviceScaleFactor: 1,
+    reducedMotion: "reduce",
+    colorScheme: "light",
+    viewport: { width: 1440, height: 900 },
+  });
+  try {
+    const page = await context.newPage();
+    await page.goto(`${pageUrl}?list`);
+    await page.waitForSelector(`html[${READY_ATTRIBUTE}]`, { state: "attached", timeout: 60_000 });
+    const listed = await page.evaluate(() => window.__basisViews);
+    const views = listed?.views ?? [];
+    const problems = listed?.problems ?? [];
+    const total = views.reduce((sum, view) => sum + view.screens.reduce((count, s) => count + s.shots.length, 0), 0);
+    const shots: Shot[] = [];
+    for (const view of views) {
+      for (const screen of view.screens) {
+        for (const shot of screen.shots) {
+          const url = `${pageUrl}?view=${encodeURIComponent(view.id)}&screen=${encodeURIComponent(screen.id)}&theme=${shot.theme}`;
+          await page.setViewportSize({ width: shot.width, height: shot.viewportHeight });
+          const take = async () => {
+            await page.goto(url);
+            await page.waitForSelector(`html[${READY_ATTRIBUTE}]`, { state: "attached", timeout: 60_000 });
+            const failed = await page.evaluate(() => document.documentElement.hasAttribute("data-basis-error"));
+            const png = await page.screenshot({ fullPage: shot.fullPage, animations: "disabled", caret: "hide" });
+            return { png, failed };
+          };
+          const first = await take();
+          const second = await take();
+          shots.push({
+            ...shot,
+            view: view.id,
+            screen: screen.id,
+            file: shotFile(view.id, screen.id, shot),
+            png: first.png,
+            imageHeight: pngHeight(first.png),
+            stable: first.png.equals(second.png),
+            failed: first.failed,
+          });
+          onProgress?.(shots.length, total);
+        }
+      }
+    }
+    return { views, problems, shots };
+  } finally {
+    await context.close();
+  }
+}

package/server/claude.ts

@@ -0,0 +1,72 @@
+import { realpathSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+/*
+ * Basis runs the user's own Claude Code rather than a copy of its own: the Claude adapter is fetched without the
+ * native binary its SDK would otherwise bring (about 260 MB), and is pointed at the user's executable through
+ * CLAUDE_CODE_EXECUTABLE. The user already has it, logged in, since that is how they sign in to Claude.
+ */
+
+interface Where {
+  env: NodeJS.ProcessEnv;
+  platform: NodeJS.Platform;
+  home: string;
+}
+
+const isFile = (file: string) => {
+  try {
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * The user's Claude Code executable, or null when it is not installed. In order: CLAUDE_CODE_EXECUTABLE when it
+ * names a file, `claude` on the PATH, then the native installer's folders. On Windows the npm install puts a
+ * `claude.cmd` shim on the PATH, which cannot be started without a shell, so the executable behind it is used.
+ */
+export function findClaude(
+  { env, platform, home }: Where = { env: process.env, platform: process.platform, home: os.homedir() },
+): string | null {
+  const explicit = env.CLAUDE_CODE_EXECUTABLE;
+  if (explicit && isFile(explicit)) return explicit;
+
+  const windows = platform === "win32";
+  // Paths are on this machine's file system; `platform` only decides the names and the PATH separator.
+  const join = path.join;
+  const pathVar = env.PATH ?? env.Path ?? "";
+  const dirs = pathVar.split(windows ? ";" : ":").filter(Boolean);
+  for (const dir of dirs) {
+    if (windows) {
+      const exe = join(dir, "claude.exe");
+      if (isFile(exe)) return exe;
+      // The npm shims (claude, claude.cmd) start this executable.
+      const npm = join(dir, "node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe");
+      if ((isFile(join(dir, "claude.cmd")) || isFile(join(dir, "claude"))) && isFile(npm)) return npm;
+    } else {
+      const bin = join(dir, "claude");
+      if (isFile(bin)) return realpath(bin);
+    }
+  }
+
+  const installed = windows
+    ? [join(home, ".local", "bin", "claude.exe")]
+    : [join(home, ".local", "bin", "claude"), join(home, ".claude", "local", "claude")];
+  for (const file of installed) if (isFile(file)) return windows ? file : realpath(file);
+  return null;
+}
+
+/** Symlinks (the native installer links to a versioned binary) resolved, so the agent starts the binary itself. */
+function realpath(file: string): string {
+  try {
+    return realpathSync(file);
+  } catch {
+    return file;
+  }
+}
+
+/** What the user is told when Basis cannot find Claude Code. */
+export const CLAUDE_MISSING =
+  "Basis runs your own Claude Code, and it is not installed. Install it (https://claude.com/claude-code), log in once with `claude` in a terminal, then pick Claude again. If it is installed, set CLAUDE_CODE_EXECUTABLE to its path.";