@litterthanlit/hypher-cli 0.1.0

package/src/commands/ack.mjs

@@ -0,0 +1,38 @@
+/**
+ * `hypher ack`: acknowledge the handoff this session read. It records that
+ * the agent reports reading it, not that it used it correctly.
+ */
+import { createClient, HypherRejected, HypherUnavailable } from "../api.mjs";
+import { readWorktreeState } from "../state.mjs";
+import { repoIdentity } from "../../vendor/hypher-git.mjs";
+
+/** @returns {Promise<{ ok: boolean, message: string }>} */
+export async function acknowledgeHere({ env, cwd }) {
+  const root = repoIdentity(cwd).root;
+  const state = readWorktreeState(env, root);
+  const revision = state?.receiptRevision ?? state?.baseRevision;
+  if (!state?.receiptId || !revision) {
+    return { ok: false, message: "Nothing to acknowledge: no handoff was loaded in this repository. Run `hypher resume`." };
+  }
+  try {
+    const client = createClient({ env });
+    const { structured } = await client.tool("acknowledge_handoff", {
+      projectId: state.projectId,
+      receiptId: state.receiptId,
+      revision,
+      destination: state.destination ?? "agent",
+    });
+    if (!structured.ok) return { ok: false, message: `Hypher did not accept the acknowledgment: ${structured.error ?? "unknown error"}` };
+    return { ok: true, message: `Acknowledged handoff revision ${structured.revision}.` };
+  } catch (error) {
+    if (error instanceof HypherUnavailable) return { ok: false, message: "Hypher unavailable. Run `hypher doctor`." };
+    if (error instanceof HypherRejected) return { ok: false, message: error.message };
+    throw error;
+  }
+}
+
+export async function run({ io }) {
+  const result = await acknowledgeHere({ env: io.env, cwd: io.cwd });
+  io.out(result.message);
+  return result.ok ? 0 : 1;
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,130 @@
+/**
+ * `hypher doctor`: one line per piece, each with the fix when it is red.
+ * ✓ green, ✗ broken (exit 1), ! worth knowing, – not applicable.
+ */
+import { existsSync } from "node:fs";
+import { CLI_VERSION, INTEGRATIONS_URL, paths } from "../env.mjs";
+import { linkFor, readConfig } from "../config.mjs";
+import { loadCredential } from "../credentials.mjs";
+import { createClient, HypherRejected, HypherUnavailable } from "../api.mjs";
+import { installedHookEvents, CLAUDE_HOOKS } from "../claude.mjs";
+import { claudeHypherServer, detectTools, isSignInEntry, projectLevelHypherEntry } from "../tools.mjs";
+import { listOutbox } from "../outbox.mjs";
+import { readBytes, readJson } from "../fsutil.mjs";
+import { CODEX_HOOKS, codexHookTrust, codexHypherEntry, codexSupportsHooks, installedCodexHookEvents, readCodexHooks } from "../codex.mjs";
+import { hasBlock } from "../agentsBlock.mjs";
+import { remotesExposingHypherRefs, repoIdentity } from "../../vendor/hypher-git.mjs";
+
+function pad(text, width = 22) {
+  return text.length >= width ? `${text} ` : text + " ".repeat(width - text.length);
+}
+
+export async function run({ io }) {
+  const env = io.env;
+  const p = paths(env);
+  const lines = [];
+  const add = (mark, label, detail, fix) => {
+    lines.push({ mark, text: `  ${mark} ${pad(label)}${detail}` });
+    if (fix) lines.push({ mark: " ", text: `      Fix: ${fix}` });
+  };
+
+  const config = readConfig(env);
+  if (config?.installedVersion && existsSync(p.shim)) add("✓", `Hypher CLI ${config.installedVersion}`, p.shim);
+  else add("✗", `Hypher CLI ${CLI_VERSION}`, "not installed on this computer", "run `npx @litterthanlit/hypher-cli init` in a git repository.");
+
+  const credential = loadCredential(env);
+  if (credential.apiKey) add("✓", "Credential", `key "${config?.keyName ?? "Hypher CLI"}" (${credential.source})`);
+  else add("✗", "Credential", "no key for the hooks", "run `hypher init` and click Approve in the browser.");
+
+  const tools = detectTools(env);
+  if (tools.claude.found) {
+    const events = installedHookEvents(readJson(p.claudeSettings, {}) ?? {});
+    const entry = claudeHypherServer(env);
+    const mcp = entry ? (isSignInEntry(entry) ? "MCP hypher (sign-in)" : "MCP hypher (bridge)") : "no hypher MCP entry";
+    if (events.length === CLAUDE_HOOKS.length) add("✓", `Claude Code ${tools.claude.version}`, `hooks ${events.join(", ")} · ${mcp}`);
+    else add("✗", `Claude Code ${tools.claude.version}`, `hooks missing: ${CLAUDE_HOOKS.map((hook) => hook.event).filter((event) => !events.includes(event)).join(", ")}`, "run `hypher init`.");
+  } else {
+    add("–", "Claude Code", "not found");
+  }
+  if (tools.codex.found) {
+    const label = `Codex ${tools.codex.version}`;
+    const entry = codexHypherEntry(readBytes(p.codexConfig)?.toString("utf8") ?? "");
+    const mcp = entry ? `MCP hypher (${entry.kind === "sign-in" ? "sign-in" : entry.kind === "bridge" ? "bridge" : "custom"})` : "no hypher MCP entry";
+    const fallback = hasBlock(readBytes(p.codexAgents)?.toString("utf8") ?? "") ? " · AGENTS.md fallback" : "";
+    const events = installedCodexHookEvents(readCodexHooks(env));
+    if (events.length === CODEX_HOOKS.length) {
+      const trust = await codexHookTrust(env, io.cwd);
+      if (trust.known && trust.trusted) add("✓", label, `hooks ${events.join(", ")} (trusted) · ${mcp}${fallback}`);
+      else if (trust.known) {
+        add("!", label, `hooks ${events.join(", ")} are not trusted yet, so Codex skips them · ${mcp}${fallback}`,
+          "run /hooks in Codex and approve Hypher (once).");
+      } else {
+        add("!", label, `hooks ${events.join(", ")} · Codex did not say whether it trusts them · ${mcp}${fallback}`,
+          "run /hooks in Codex and check that Hypher's hooks are approved.");
+      }
+    } else if (codexSupportsHooks(env)) {
+      add("✗", label, `hooks missing: ${CODEX_HOOKS.map((hook) => hook.event).filter((event) => !events.includes(event)).join(", ")} · ${mcp}`, "run `hypher init`.");
+    } else if (entry && fallback) {
+      add("✓", label, `this version has no hooks; resume and seal through ${mcp}${fallback}`);
+    } else {
+      add("✗", label, `not set up (${mcp})`, "run `hypher init`.");
+    }
+  } else {
+    add("–", "Codex", "not found");
+  }
+
+  const identity = repoIdentity(io.cwd);
+  if (!identity.root) {
+    add("–", "Repository", "not in a git repository");
+  } else if (!identity.repository) {
+    add("–", "Repository", "no GitHub remote, so Hypher has no note for it");
+  } else {
+    const link = linkFor(identity.repository, env);
+    if (link) add("✓", "Repository", `${identity.repository} → project "${link.projectName ?? link.projectId}"`);
+    else add("✗", "Repository", `${identity.repository} is not linked; hooks send nothing here`, "run `hypher link` here, or link it in Settings → Integrations.");
+    const projectLevel = projectLevelHypherEntry(identity.root);
+    if (projectLevel) {
+      add("!", "Project-level MCP", `${projectLevel.file.slice(identity.root.length + 1)} has its own hypher entry, which overrides your user-level one in this repository (hooks still work)`,
+        "remove the hypher entry from .mcp.json if you want the user-level one here.");
+    }
+    const exposed = remotesExposingHypherRefs(identity.root);
+    if (exposed.length) {
+      add("!", "refs/hypher", `remote ${exposed.join(", ")} would push refs/hypher, which can hold untracked files`,
+        "drop the mirror setting or narrow the push refspec to refs/heads/*.");
+    } else {
+      add("✓", "refs/hypher", "stay local (no remote pushes them)");
+    }
+  }
+
+  const client = createClient({ env, timeoutMs: 5_000 });
+  if (credential.apiKey) {
+    const started = Date.now();
+    try {
+      const { structured } = await client.tool("list_projects", {});
+      const count = Array.isArray(structured.projects) ? structured.projects.length : 0;
+      add("✓", "Hypher reachable", `${client.base} · ${Date.now() - started} ms · ${count} project${count === 1 ? "" : "s"}`);
+    } catch (error) {
+      if (error instanceof HypherUnavailable) {
+        add("✗", "Hypher unavailable", `${client.base} (${error.causeText || "no answer"})`,
+          "check your network, VPN, or proxy, then run `hypher doctor` again. Sessions start without Hypher until then.");
+      } else if (error instanceof HypherRejected) {
+        add("✗", "Hypher reachable", error.message, "run `hypher init` to connect this computer again.");
+      } else {
+        throw error;
+      }
+    }
+  } else {
+    add("–", "Hypher reachable", `not checked without a key (${client.base})`);
+  }
+
+  const waiting = listOutbox(env);
+  const oldest = waiting[0] ? Math.round((Date.now() - waiting[0].item.queuedAt) / 60_000) : 0;
+  if (waiting.length === 0 || oldest < 30) add("✓", "Outbox", `${waiting.length} checkpoint${waiting.length === 1 ? "" : "s"} waiting`);
+  else add("!", "Outbox", `${waiting.length} checkpoints waiting, oldest ${oldest} min`, "run `hypher doctor` once Hypher is reachable; they upload on the next session start.");
+
+  io.out(`Hypher doctor · ${CLI_VERSION} · Pilot · not yet recorded`);
+  for (const line of lines) io.out(line.text);
+  const broken = lines.filter((line) => line.mark === "✗").length;
+  io.out(broken ? `${broken} problem${broken === 1 ? "" : "s"}. See the fix under each ✗.` : `All green. Integrations: ${INTEGRATIONS_URL}`);
+  return broken ? 1 : 0;
+}

package/src/commands/hook.mjs

@@ -0,0 +1,57 @@
+/**
+ * `hypher hook <agent> <event>`: the command every hook runs. It reads the
+ * payload on stdin, prints hook JSON when it has something to say, and always
+ * exits 0: a hook never breaks a session. Errors go to a local log.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { paths } from "../env.mjs";
+import { HOOK_AGENTS, handleAgentHook } from "../hooks/index.mjs";
+import { HYPHER_UNAVAILABLE_LINE } from "../../vendor/handoffNote.mjs";
+
+const STDIN_TIMEOUT_MS = 2_000;
+
+async function readPayload(stream) {
+  const chunks = [];
+  const read = (async () => {
+    for await (const chunk of stream) chunks.push(Buffer.from(chunk));
+  })();
+  let timer;
+  await Promise.race([read, new Promise((resolve) => { timer = setTimeout(resolve, STDIN_TIMEOUT_MS); })]);
+  clearTimeout(timer);
+  try {
+    const parsed = JSON.parse(Buffer.concat(chunks).toString("utf8") || "{}");
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function logError(env, event, error) {
+  try {
+    const file = path.join(paths(env).stateDir, "hook-errors.log");
+    mkdirSync(path.dirname(file), { recursive: true });
+    appendFileSync(file, `${new Date().toISOString()} ${event} ${error instanceof Error ? error.stack : String(error)}\n`);
+  } catch {
+    // Nothing else to do; the session must go on.
+  }
+}
+
+export async function run({ args, io }) {
+  const [agent, event] = args;
+  const payload = await readPayload(io.stdin);
+  try {
+    if (!HOOK_AGENTS.includes(agent)) return 0;
+    const output = await handleAgentHook(agent, event, payload, io.env);
+    if (output) io.stdout.write(`${JSON.stringify(output)}\n`);
+  } catch (error) {
+    logError(io.env, event, error);
+    if (event === "SessionStart") {
+      io.stdout.write(`${JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: HYPHER_UNAVAILABLE_LINE } })}\n`);
+    }
+  } finally {
+    // A client that keeps stdin open must not keep this hook alive.
+    io.stdin.destroy?.();
+  }
+  return 0;
+}

package/src/commands/init.mjs

@@ -0,0 +1,252 @@
+/**
+ * `hypher init`: one command and at most one browser approval.
+ * Installs a pinned copy under ~/.hypher, connects this computer, links this
+ * repository when a human picks its project, and adds Claude Code and Codex
+ * hooks.
+ * Every change goes into the manifest so `uninstall` can undo exactly it.
+ */
+import { chmodSync, cpSync, existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CLI_VERSION, API_KEYS_URL, apiBase, machineName, paths } from "../env.mjs";
+import { readConfig, writeConfig, linkFor, saveLink } from "../config.mjs";
+import { credentialPromptLine, credentialStore, loadCredential, saveCredential } from "../credentials.mjs";
+import { createClient, HypherUnavailable } from "../api.mjs";
+import { runDeviceFlow } from "../device.mjs";
+import { readManifest, recordEntry, writeManifest, writeTrackedFile } from "../manifest.mjs";
+import { mergeClaudeHooks, renderSettings, CLAUDE_HOOKS } from "../claude.mjs";
+import { claudeHypherServer, claudeMcpAdd, detectTools, isSignInEntry } from "../tools.mjs";
+import { readBytes, readJson } from "../fsutil.mjs";
+import { CODEX_HOOKS, CODEX_TRUST_LINE, addBridge, codexHookTrust, codexHypherEntry, codexSupportsHooks, mergeCodexHooks, readCodexHooks } from "../codex.mjs";
+import { renderJson } from "../hookConfig.mjs";
+import { addBlock, agentsBlock, alreadyUsesHypher } from "../agentsBlock.mjs";
+import { addRepositoryBlock, displayPath } from "../repoBlock.mjs";
+import { repoIdentity } from "../../vendor/hypher-git.mjs";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+function pad(text, width) {
+  return text.length >= width - 1 ? `${text}  ` : text + " ".repeat(width - text.length);
+}
+
+/** Copy this package to ~/.hypher/lib and point ~/.hypher/bin/hypher at it. */
+export function installPinnedCopy(env, manifest) {
+  const p = paths(env);
+  const target = path.join(p.libDir, `cli-${CLI_VERSION}`);
+  if (path.resolve(PACKAGE_ROOT) !== path.resolve(target)) {
+    mkdirSync(p.libDir, { recursive: true });
+    cpSync(PACKAGE_ROOT, target, {
+      recursive: true,
+      filter: (source) => !/\/(node_modules|test)(\/|$)/.test(source.slice(PACKAGE_ROOT.length)),
+    });
+  }
+  const shim = [
+    "#!/bin/sh",
+    "# Hypher CLI. Installed by `hypher init`; removed by `hypher uninstall`.",
+    `exec "${process.execPath}" "${path.join(target, "bin", "hypher.mjs")}" "$@"`,
+    "",
+  ].join("\n");
+  const change = writeTrackedFile(manifest, p.shim, shim, "shim");
+  chmodSync(p.shim, 0o755);
+  return change;
+}
+
+/**
+ * `--yes` never asks in the terminal (today init asks nothing there; the one
+ * approval is in the browser). `--json` prints one JSON summary on stdout.
+ * @param {{ args: string[], flags: Record<string, any>, io: any }} input
+ */
+export async function run({ flags, io }) {
+  const env = io.env;
+  const started = Date.now();
+  let approvalMs = 0;
+  // --json: the human lines go to stderr, and stdout carries one JSON summary.
+  const say = flags.json ? (line = "") => io.err(line) : (line = "") => io.out(line);
+  const human = { ...io, out: say };
+  const p = paths(env);
+  const home = p.home;
+  const hypherHomeExisted = existsSync(p.hypherHome);
+  mkdirSync(p.hypherHome, { recursive: true });
+  const manifest = readManifest(env);
+  recordEntry(manifest, { kind: "hypher-home", id: "hypher-home", path: p.hypherHome,
+    createdByInit: manifest.entries.find((entry) => entry.id === "hypher-home")?.createdByInit ?? !hypherHomeExisted });
+  const changed = [];
+  const summary = { ok: true, tools: {}, changed, link: null, key: null };
+
+  say("Hypher · Baton  (Pilot · not yet recorded)");
+  say("");
+
+  const tools = detectTools(env);
+  summary.tools = tools;
+  const claudeEntry = tools.claude.found ? claudeHypherServer(env) : null;
+  const codexText = readBytes(p.codexConfig)?.toString("utf8") ?? "";
+  const codexEntry = tools.codex.found ? codexHypherEntry(codexText) : null;
+  say(`  ${tools.claude.found ? "✓" : "–"} ${pad(`Claude Code${tools.claude.version ? ` ${tools.claude.version}` : ""}`, 24)}${
+    tools.claude.found ? `found${isSignInEntry(claudeEntry) ? " · Hypher sign-in kept" : ""}` : "not found"}`);
+  say(`  ${tools.codex.found ? "✓" : "–"} ${pad(`Codex${tools.codex.version ? ` ${tools.codex.version}` : ""}`, 24)}${
+    tools.codex.found ? `found${codexEntry?.kind === "sign-in" ? " · Hypher sign-in kept" : ""}` : "not found"}`);
+  say(`  ${tools.cursor.found ? "✓" : "–"} ${pad("Cursor", 24)}${tools.cursor.found ? "found (use the Cursor plugin)" : "not found"}`);
+  say("");
+
+  // 1. Pinned copy, so nothing calls npx at session start.
+  const shimChange = installPinnedCopy(env, manifest);
+  if (shimChange !== "unchanged") changed.push([p.shim, `installed ${CLI_VERSION} (Hypher's own files stay in ~/.hypher)`]);
+  const config = { ...(readConfig(env) ?? {}) };
+  config.apiBase = apiBase(env, config);
+  config.machineName = config.machineName ?? machineName(env);
+  config.nodePath = process.execPath;
+  config.installedVersion = CLI_VERSION;
+  writeConfig(config, env);
+  writeManifest(manifest, env);
+
+  // 2. The hook credential.
+  const client = createClient({ env });
+  const identity = repoIdentity(io.cwd);
+  const repository = identity.repository;
+  let credential = loadCredential(env);
+  let approved = null;
+  if (credential.apiKey) {
+    say(`  ✓ Connected · key "${config.keyName ?? "Hypher CLI"}" (${credential.source})`);
+  } else {
+    const store = credentialStore(env);
+    try {
+      const waitStarted = Date.now();
+      const flow = await runDeviceFlow(client, {
+        purpose: "connect",
+        repository: repository && !linkFor(repository, env) ? repository : null,
+        io: human,
+        noBrowser: flags["no-browser"],
+      });
+      approvalMs = Date.now() - waitStarted;
+      if (!flow.ok) {
+        say(`  ✗ ${flow.error}`);
+        summary.ok = false;
+      } else {
+        approved = flow.result;
+        const promptLine = credentialPromptLine(store);
+        if (promptLine) say(`  ${promptLine}`);
+        if (promptLine) summary.keychain = promptLine;
+        const saved = saveCredential(approved.apiKey, env);
+        if (!saved.ok) {
+          say(`  ✗ ${saved.error}`);
+          summary.ok = false;
+        } else {
+          config.keyId = approved.keyId;
+          config.keyName = approved.keyName;
+          config.credentialStore = saved.store;
+          writeConfig(config, env);
+          recordEntry(manifest, { kind: "credential", id: "credential", store: saved.store });
+          recordEntry(manifest, { kind: "api-key", id: "api-key", keyId: approved.keyId, keyName: approved.keyName });
+          writeManifest(manifest, env);
+          summary.key = approved.keyName;
+          credential = loadCredential(env);
+          say(`  ✓ Approved · key "${approved.keyName}" (revoke in Settings → API keys: ${API_KEYS_URL})`);
+        }
+      }
+    } catch (error) {
+      if (!(error instanceof HypherUnavailable)) throw error;
+      say(`  ✗ Hypher unavailable at ${client.base}. Check your connection, then run \`hypher init\` again.`);
+      summary.ok = false;
+    }
+  }
+
+  // 3. This repository's project, picked by a human on the same page.
+  if (repository) {
+    const known = linkFor(repository, env);
+    if (known) {
+      say(`  ✓ ${repository} → project "${known.projectName ?? known.projectId}"`);
+      summary.link = known;
+    } else if (approved?.link?.projectId) {
+      saveLink(repository, { projectId: approved.link.projectId, projectName: approved.link.projectName }, env);
+      say(`  ✓ ${repository} → project "${approved.link.projectName ?? approved.link.projectId}"`);
+      summary.link = approved.link;
+    } else if (credential.apiKey) {
+      say(`  – ${repository} is not linked. Run \`hypher link\` here to pick its project.`);
+    }
+  } else if (identity.root) {
+    say("  – This repository has no GitHub remote, so Hypher cannot link it.");
+  }
+  // The repository's AGENTS.md tells any agent to resume first and save at the end.
+  if (summary.link && identity.root) {
+    const block = addRepositoryBlock(manifest, identity.root);
+    writeManifest(manifest, env);
+    if (block.change === "skipped") say("  ✓ AGENTS.md already tells agents to use Hypher; left as is");
+    else if (block.change !== "unchanged") changed.push([block.file, "+ Hypher block (resume first, save at the end)"]);
+  }
+
+  // 4. Claude Code: hooks, and the bridge only when M0a's sign-in is absent.
+  if (tools.claude.found) {
+    const settings = readJson(p.claudeSettings, {}) ?? {};
+    const merged = mergeClaudeHooks(settings && typeof settings === "object" ? settings : {}, p.shim);
+    const change = writeTrackedFile(manifest, p.claudeSettings, renderSettings(merged), "claude-settings");
+    if (change !== "unchanged") changed.push([p.claudeSettings, `+ hooks ${CLAUDE_HOOKS.map((hook) => hook.event).join(", ")}`]);
+    writeManifest(manifest, env);
+    if (!claudeEntry) {
+      const added = claudeMcpAdd(env, p.shim);
+      if (added.status === 0) {
+        recordEntry(manifest, { kind: "claude-mcp", id: "claude-mcp", name: "hypher", command: p.shim });
+        writeManifest(manifest, env);
+        changed.push([p.claudeJson, "+ MCP server hypher (local bridge)"]);
+      } else {
+        say("  ✗ Could not add the Hypher MCP server to Claude Code. Run `hypher doctor`.");
+      }
+    }
+  }
+
+  // 5. Codex: the bridge unless a hypher entry is there, hooks where this version has them,
+  //    and the ~/.codex/AGENTS.md fallback for when the hooks are not trusted yet.
+  let codexHooks = false;
+  if (tools.codex.found) {
+    if (!codexEntry) {
+      const change = writeTrackedFile(manifest, p.codexConfig, addBridge(codexText, p.shim), "codex-config");
+      if (change !== "unchanged") changed.push([p.codexConfig, "+ MCP server hypher (bridge; resume, seal, acknowledge never prompt)"]);
+    }
+    if (codexSupportsHooks(env)) {
+      codexHooks = true;
+      const change = writeTrackedFile(manifest, p.codexHooks, renderJson(mergeCodexHooks(readCodexHooks(env), p.shim)), "codex-hooks");
+      if (change !== "unchanged") changed.push([p.codexHooks, `+ hooks ${CODEX_HOOKS.map((hook) => hook.event).join(", ")}`]);
+    }
+    const agentsText = readBytes(p.codexAgents)?.toString("utf8") ?? "";
+    if (!alreadyUsesHypher(agentsText)) {
+      const change = writeTrackedFile(manifest, p.codexAgents, addBlock(agentsText, agentsBlock("codex")), "codex-agents");
+      if (change !== "unchanged") changed.push([p.codexAgents, `+ Hypher block (${codexHooks ? "fallback until the hooks are trusted" : "this Codex has no hooks"})`]);
+    }
+    writeManifest(manifest, env);
+  }
+
+  say("");
+  if (changed.length) {
+    say("  Changed");
+    for (const [file, what] of changed) say(`    ${pad(displayPath(file, { cwd: io.cwd, home }), 28)}${what}`);
+  } else {
+    say("  Already set up. Nothing changed.");
+  }
+  say("");
+  say("  Any other agent: add this MCP server, or run `hypher resume` in its terminal.");
+  say(`    "hypher": { "command": "${p.shim}", "args": ["mcp"] }`);
+  say("");
+  const humanSteps = [];
+  if (codexHooks) {
+    const trust = await codexHookTrust(env, io.cwd);
+    if (trust.known && trust.trusted) say("  ✓ Codex trusts Hypher's hooks.");
+    else {
+      say(`  ${CODEX_TRUST_LINE}`);
+      humanSteps.push(CODEX_TRUST_LINE);
+    }
+  }
+  say("  Undo everything: hypher uninstall");
+  const ms = Date.now() - started;
+  say(`  Done in ${(ms / 1000).toFixed(1)} s${approvalMs ? ` (${((ms - approvalMs) / 1000).toFixed(1)} s without the wait for your approval)` : ""}.`);
+  if (flags.json) {
+    io.out(JSON.stringify({
+      ...summary,
+      alreadySetUp: changed.length === 0,
+      changed: changed.map(([file, what]) => ({ file, what })),
+      mcpEntry: { hypher: { command: p.shim, args: ["mcp"] } },
+      humanSteps,
+      ms,
+      approvalMs,
+    }));
+  }
+  return summary.ok ? 0 : 1;
+}

package/src/commands/link.mjs

@@ -0,0 +1,65 @@
+/**
+ * `hypher link`: bind this repository to a Hypher project. A human picks the
+ * project in the browser; Hypher never creates one on its own.
+ */
+import { createClient, HypherUnavailable } from "../api.mjs";
+import { linkFor, saveLink } from "../config.mjs";
+import { runDeviceFlow } from "../device.mjs";
+import { repoIdentity } from "../../vendor/hypher-git.mjs";
+import { readManifest, writeManifest } from "../manifest.mjs";
+import { addRepositoryBlock, displayPath } from "../repoBlock.mjs";
+import { paths } from "../env.mjs";
+
+/** Link saved: add the AGENTS.md block and say what changed. */
+function linked(io, identity, link) {
+  saveLink(identity.repository, link, io.env);
+  io.out(`✓ ${identity.repository} → project "${link.projectName}"`);
+  const manifest = readManifest(io.env);
+  const block = addRepositoryBlock(manifest, identity.root);
+  writeManifest(manifest, io.env);
+  const shown = displayPath(block.file, { cwd: io.cwd, home: paths(io.env).home });
+  if (block.change === "skipped") io.out(`  ${shown} already tells agents to use Hypher; left as is`);
+  else if (block.change !== "unchanged") io.out(`  ${shown}: + Hypher block (resume first, save at the end). Commit it so teammates' agents see it; \`hypher uninstall\` removes it.`);
+  return 0;
+}
+
+export async function run({ flags, io }) {
+  const identity = repoIdentity(io.cwd);
+  if (!identity.root) {
+    io.err("hypher link: run this inside a git repository.");
+    return 2;
+  }
+  if (!identity.repository) {
+    io.err("hypher link: this repository has no GitHub remote, so Hypher cannot link it.");
+    return 2;
+  }
+  const client = createClient({ env: io.env });
+  if (!client.apiKey) {
+    io.err("hypher link: this computer is not connected. Run `hypher init` first.");
+    return 1;
+  }
+  try {
+    // Already linked in Hypher (for example in Settings → Integrations)? Then no click is needed.
+    const resolved = await client.tool("resolve_project_for_repo", { repo: identity.repository });
+    if (resolved.structured.matched && resolved.structured.projectId) {
+      return linked(io, identity, { projectId: resolved.structured.projectId, projectName: resolved.structured.projectName });
+    }
+    const known = linkFor(identity.repository, io.env);
+    if (known) io.out(`${identity.repository} was linked to "${known.projectName}" on this computer, but Hypher no longer has that link.`);
+    const flow = await runDeviceFlow(client, { purpose: "link", repository: identity.repository, io, noBrowser: flags["no-browser"] });
+    if (!flow.ok) {
+      io.out(`✗ ${flow.error}`);
+      return 1;
+    }
+    const link = flow.result.link;
+    if (!link?.projectId) {
+      io.out("✗ No project was picked.");
+      return 1;
+    }
+    return linked(io, identity, { projectId: link.projectId, projectName: link.projectName });
+  } catch (error) {
+    if (!(error instanceof HypherUnavailable)) throw error;
+    io.out("Hypher unavailable. Run `hypher doctor`.");
+    return 1;
+  }
+}