gsc-axi 0.1.0

package/src/cli.js

@@ -0,0 +1,137 @@
+import { runAxiCli } from "axi-sdk-js";
+// The SDK renders command output itself but does not re-export its encoder,
+// so the static top-level help encodes through the same official TOON library.
+import { encode } from "@toon-format/toon";
+import { CREDENTIAL_HELP, hasCredentials, listSites, resolveSite } from "./api.js";
+import { BIN } from "./args.js";
+import { inspectCommand, sitemapsCommand, sitesCommand } from "./commands/index-tools.js";
+import {
+  compareCommand,
+  opportunitiesCommand,
+  performanceCommand,
+  query,
+  totals,
+} from "./commands/performance.js";
+import { setupCommand } from "./commands/setup.js";
+import { previous, window } from "./range.js";
+import { VERSION } from "./version.js";
+
+export const DESCRIPTION =
+  "Read Google Search Console — search performance, indexing status, and sitemaps";
+
+const HOME_ROWS = 5;
+
+export const TOP_HELP = `${encode({
+  usage: `${BIN} [command] [args] [flags]`,
+  commands: {
+    "(none)": "dashboard — this month's search traffic and top queries",
+    sites: "properties this account can reach",
+    performance: "clicks, impressions, CTR, position by query, page, country, device",
+    compare: "this window against the one before it",
+    opportunities: "queries ranking 4-20 with real volume",
+    inspect: "whether Google indexed a URL, and what it saw",
+    sitemaps: "list, submit",
+    setup: "hooks, status, uninstall",
+  },
+  globals: { "--site": "Target property (or GSC_SITE)" },
+  auth: "GOOGLE_APPLICATION_CREDENTIALS (service account), or GSC_CLIENT_ID/SECRET/REFRESH_TOKEN",
+  note: "Search Console finalises data on a 2-3 day delay; windows end there, not today",
+  examples: [
+    BIN,
+    `${BIN} performance --by page --range 90d`,
+    `${BIN} opportunities`,
+    `${BIN} compare --by query`,
+    `${BIN} inspect https://example.com/post`,
+  ],
+  help: [`Run \`${BIN} <command> --help\` for a command reference`],
+})}\n`;
+
+/**
+ * AXI §8: no-args shows live state. Missing credentials are reported as data
+ * with a fix, not as a failure — this view is what a SessionStart hook runs.
+ */
+async function home() {
+  if (!hasCredentials()) {
+    return { search: "no Google credentials in the environment", help: CREDENTIAL_HELP };
+  }
+
+  const sites = await listSites({});
+  if (sites.length === 0) {
+    return {
+      search: "0 Search Console properties visible to this account",
+      help: [
+        "Add the account as a user on the property: Settings -> Users and permissions",
+        "A service account needs its `client_email` added there",
+      ],
+    };
+  }
+  if (sites.length > 1 && !process.env.GSC_SITE) {
+    return {
+      count: `${sites.length} properties`,
+      sites: sites.slice(0, HOME_ROWS).map((entry) => entry.siteUrl),
+      help: [
+        `Run \`${BIN} performance --site <property>\` for one of them`,
+        "Export GSC_SITE to make one the default",
+      ],
+    };
+  }
+
+  const site = await resolveSite(undefined);
+  const dates = window({});
+  const before = previous(dates);
+  const [current, prior, queries] = await Promise.all([
+    totals(site, dates),
+    totals(site, before),
+    query(site, dates, { dimensions: ["query"], rowLimit: HOME_ROWS }),
+  ]);
+
+  if (current.impressions === 0) {
+    return {
+      site,
+      window: `${dates.startDate}..${dates.endDate}`,
+      search: "0 impressions in this window",
+      help: [
+        `Run \`${BIN} performance --range 90d\` for a wider window`,
+        `Run \`${BIN} sitemaps\` to check Google has read a sitemap`,
+      ],
+    };
+  }
+
+  const change = prior.clicks ? Math.round(((current.clicks - prior.clicks) / prior.clicks) * 100) : null;
+  return {
+    site,
+    window: `${dates.startDate}..${dates.endDate}`,
+    clicks: change === null ? current.clicks : `${current.clicks} (${change >= 0 ? "+" : ""}${change}% vs previous)`,
+    impressions: current.impressions,
+    ctr: `${(current.ctr * 100).toFixed(1)}%`,
+    position: Number(current.position.toFixed(1)),
+    top_queries: queries.map((entry) => ({
+      query: entry.keys?.[0] ?? "-",
+      clicks: entry.clicks,
+      position: Number((entry.position ?? 0).toFixed(1)),
+    })),
+    help: [
+      `Run \`${BIN} opportunities\` for queries ranking 4-20`,
+      `Run \`${BIN} performance --by page\` for the pages earning this`,
+      `Run \`${BIN} compare --by query\` for what moved`,
+    ],
+  };
+}
+
+export async function main() {
+  await runAxiCli({
+    description: DESCRIPTION,
+    version: VERSION,
+    topLevelHelp: TOP_HELP,
+    home,
+    commands: {
+      sites: sitesCommand,
+      performance: performanceCommand,
+      compare: compareCommand,
+      opportunities: opportunitiesCommand,
+      inspect: inspectCommand,
+      sitemaps: sitemapsCommand,
+      setup: setupCommand,
+    },
+  });
+}

package/src/commands/index-tools.js

@@ -0,0 +1,169 @@
+import { AxiError } from "axi-sdk-js";
+import { gsc, inspectionBase, listSites, resolveSite, sitePath } from "../api.js";
+import { BIN, helpFor, makeDispatcher, parse, required, wantsHelp } from "../args.js";
+
+const HELP = {
+  sites: helpFor({
+    command: "sites",
+    description: "Properties this account can reach, and its permission on each",
+    usage: `${BIN} sites`,
+    examples: [`${BIN} sites`],
+  }),
+  inspect: helpFor({
+    command: "inspect",
+    description: "Whether Google has indexed a URL, and what it saw",
+    usage: `${BIN} inspect <url> [--site <property>]`,
+    examples: [`${BIN} inspect https://example.com/blog/post`],
+  }),
+  list: helpFor({
+    command: "sitemaps list",
+    description: "Submitted sitemaps, when they were last read, and any errors",
+    usage: `${BIN} sitemaps [list] [--site <property>]`,
+    examples: [`${BIN} sitemaps`],
+  }),
+  submit: helpFor({
+    command: "sitemaps submit",
+    description: "Submit a sitemap (idempotent — resubmitting an existing one is a no-op)",
+    usage: `${BIN} sitemaps submit <url> [--site <property>]`,
+    examples: [`${BIN} sitemaps submit https://example.com/sitemap.xml`],
+  }),
+};
+
+export async function sitesCommand(argv) {
+  if (wantsHelp(argv)) return HELP.sites;
+  parse(argv, { command: "sites" });
+  const sites = await listSites({});
+
+  if (sites.length === 0) {
+    return {
+      sites: "0 properties visible to this account",
+      help: [
+        "Add the account as a user on the property in Search Console: Settings -> Users and permissions",
+        "A service account needs its `client_email` added there, not your own address",
+      ],
+    };
+  }
+  return {
+    count: `${sites.length} total`,
+    sites: sites.map((entry) => ({ property: entry.siteUrl, permission: entry.permissionLevel })),
+    help: [
+      `Run \`${BIN} performance --site <property>\` for its search traffic`,
+      "Export GSC_SITE to make one the default",
+    ],
+  };
+}
+
+/** The inspection payload nests three verdicts an agent has to act on. */
+function inspection(result) {
+  const index = result?.indexStatusResult ?? {};
+  return {
+    verdict: index.verdict ?? "UNKNOWN",
+    coverage: index.coverageState ?? "-",
+    indexed: index.verdict === "PASS",
+    ...(index.lastCrawlTime ? { last_crawled: String(index.lastCrawlTime).slice(0, 19).replace("T", " ") } : {}),
+    ...(index.googleCanonical ? { google_canonical: index.googleCanonical } : {}),
+    ...(index.userCanonical && index.userCanonical !== index.googleCanonical
+      ? { your_canonical: index.userCanonical }
+      : {}),
+    ...(index.robotsTxtState ? { robots: index.robotsTxtState } : {}),
+    ...(result?.mobileUsabilityResult?.verdict ? { mobile: result.mobileUsabilityResult.verdict } : {}),
+    ...(result?.richResultsResult?.verdict ? { rich_results: result.richResultsResult.verdict } : {}),
+  };
+}
+
+export async function inspectCommand(argv) {
+  if (wantsHelp(argv)) return HELP.inspect;
+  const { values, positionals } = parse(argv, { command: "inspect" });
+  const url = required(positionals[0], "<url>", "inspect", `${BIN} inspect https://example.com/page`);
+  const site = await resolveSite(values.site);
+
+  const payload = await gsc("/urlInspection/index:inspect", {
+    base: inspectionBase,
+    method: "POST",
+    body: { inspectionUrl: url, siteUrl: site },
+  });
+  const result = inspection(payload?.inspectionResult);
+
+  return {
+    url,
+    site,
+    ...result,
+    help: result.indexed
+      ? []
+      : [
+          "A NEUTRAL or FAIL verdict means Google has not indexed this URL",
+          `Run \`${BIN} sitemaps\` to check the sitemap covering it was read`,
+        ],
+  };
+}
+
+async function sitemapsList(argv) {
+  if (wantsHelp(argv)) return HELP.list;
+  const { values } = parse(argv, { command: "sitemaps list" });
+  const site = await resolveSite(values.site);
+  const payload = await gsc(sitePath(site, "/sitemaps"), {});
+  const sitemaps = payload.sitemap ?? [];
+
+  if (sitemaps.length === 0) {
+    return {
+      site,
+      sitemaps: "0 sitemaps submitted for this property",
+      help: [`Run \`${BIN} sitemaps submit <url>\` to add one`],
+    };
+  }
+  return {
+    site,
+    count: `${sitemaps.length} total`,
+    sitemaps: sitemaps.map((entry) => ({
+      path: entry.path,
+      type: entry.type ?? "-",
+      submitted: String(entry.lastSubmitted ?? "").slice(0, 10),
+      last_read: String(entry.lastDownloaded ?? "").slice(0, 10) || "never",
+      errors: entry.errors ?? 0,
+      warnings: entry.warnings ?? 0,
+      pending: Boolean(entry.isPending),
+    })),
+  };
+}
+
+async function sitemapsSubmit(argv) {
+  if (wantsHelp(argv)) return HELP.submit;
+  const { values, positionals } = parse(argv, { command: "sitemaps submit" });
+  const url = required(
+    positionals[0],
+    "<url>",
+    "sitemaps submit",
+    `${BIN} sitemaps submit https://example.com/sitemap.xml`,
+  );
+  if (!/^https?:\/\//.test(url)) {
+    throw new AxiError("a sitemap must be submitted as a full URL", "VALIDATION_ERROR", [
+      `Example: ${BIN} sitemaps submit https://example.com/sitemap.xml`,
+    ]);
+  }
+  const site = await resolveSite(values.site);
+
+  const existing = await gsc(sitePath(site, "/sitemaps"), {});
+  const already = (existing.sitemap ?? []).some((entry) => entry.path === url);
+
+  // PUT is idempotent upstream, but saying so beats a second identical call
+  // looking like it changed something.
+  await gsc(sitePath(site, `/sitemaps/${encodeURIComponent(url)}`), { method: "PUT", write: true });
+  return {
+    site,
+    sitemap: url,
+    ...(already ? { unchanged: true, note: "already submitted (no-op)" } : { submitted: true }),
+    help: [`Run \`${BIN} sitemaps\` in a few hours to see when Google read it`],
+  };
+}
+
+export const sitemapsCommand = makeDispatcher(
+  "sitemaps",
+  { list: sitemapsList, submit: sitemapsSubmit },
+  {
+    fallback: "list",
+    summary: {
+      list: "Submitted sitemaps and their read status (default)",
+      submit: "Submit a sitemap (idempotent)",
+    },
+  },
+);

package/src/commands/performance.js

@@ -0,0 +1,271 @@
+import { AxiError } from "axi-sdk-js";
+import { gsc, resolveSite, sitePath } from "../api.js";
+import { DATE_FLAGS, dateFlagHelp, previous, window } from "../range.js";
+import { BIN, helpFor, parse, positiveInt, wantsHelp } from "../args.js";
+
+const DEFAULT_LIMIT = 20;
+
+// Search Console's dimension names, plus the plurals an agent is likely to type.
+export const DIMENSIONS = ["query", "page", "country", "device", "date", "searchAppearance"];
+const PLURALS = new Map([
+  ["queries", "query"],
+  ["pages", "page"],
+  ["countries", "country"],
+  ["devices", "device"],
+  ["dates", "date"],
+]);
+
+const TYPES = ["web", "image", "video", "news", "discover", "googleNews"];
+
+const HELP = {
+  performance: helpFor({
+    command: "performance",
+    description: "Clicks, impressions, CTR, and average position, broken down by a dimension",
+    usage: `${BIN} performance [--by query|page|country|device|date] [--range <window>] [--limit <n>] [--type web|discover|...]`,
+    flags: {
+      ...dateFlagHelp(),
+      "--by": `Dimension to group by (default query): ${DIMENSIONS.join(", ")}`,
+      "--limit": `Rows to show (default ${DEFAULT_LIMIT})`,
+      "--type": `Search type (default web): ${TYPES.join(", ")}`,
+      "--country": "Only this country, as a 3-letter code (e.g. nld)",
+      "--device": "Only this device: desktop, mobile, tablet",
+      "--contains": "Only rows whose dimension value contains this text",
+    },
+    examples: [
+      `${BIN} performance`,
+      `${BIN} performance --by page --range 90d`,
+      `${BIN} performance --by query --contains openpanel`,
+    ],
+  }),
+  compare: helpFor({
+    command: "compare",
+    description: "This window against the one immediately before it",
+    usage: `${BIN} compare [--range <window>] [--by query|page]`,
+    flags: {
+      ...dateFlagHelp(),
+      "--by": "Also break the change down by this dimension",
+      "--limit": `Rows when --by is given (default ${DEFAULT_LIMIT})`,
+    },
+    examples: [`${BIN} compare`, `${BIN} compare --range 90d --by query`],
+  }),
+  opportunities: helpFor({
+    command: "opportunities",
+    description: "Queries ranking 4-20 with real volume — the cheapest positions to improve",
+    usage: `${BIN} opportunities [--min-impressions <n>] [--range <window>] [--limit <n>]`,
+    flags: {
+      ...dateFlagHelp(),
+      "--min-impressions": "Volume floor (default 50)",
+      "--limit": `Rows to show (default ${DEFAULT_LIMIT})`,
+    },
+    examples: [`${BIN} opportunities`, `${BIN} opportunities --min-impressions 200 --range 90d`],
+  }),
+};
+
+export function resolveDimension(input) {
+  const wanted = String(input);
+  if (DIMENSIONS.includes(wanted)) return wanted;
+  const lower = wanted.toLowerCase();
+  const exact = DIMENSIONS.find((dimension) => dimension.toLowerCase() === lower);
+  if (exact) return exact;
+  const singular = PLURALS.get(lower);
+  if (singular) return singular;
+  throw new AxiError(`unknown dimension ${input}`, "VALIDATION_ERROR", [
+    `valid dimensions: ${DIMENSIONS.join(", ")}`,
+  ]);
+}
+
+function filters(values) {
+  const built = [];
+  if (values.country) built.push({ dimension: "country", operator: "equals", expression: values.country });
+  if (values.device) {
+    built.push({ dimension: "device", operator: "equals", expression: String(values.device).toUpperCase() });
+  }
+  if (values.contains) {
+    built.push({ dimension: values.by ?? "query", operator: "contains", expression: values.contains });
+  }
+  return built.length ? [{ filters: built }] : undefined;
+}
+
+/** ctr arrives as a fraction and position with float noise. */
+function row(entry, dimensions) {
+  const projected = {};
+  dimensions.forEach((dimension, index) => {
+    projected[dimension] = entry.keys?.[index] ?? "-";
+  });
+  return {
+    ...projected,
+    clicks: entry.clicks ?? 0,
+    impressions: entry.impressions ?? 0,
+    ctr: `${((entry.ctr ?? 0) * 100).toFixed(1)}%`,
+    position: Number((entry.position ?? 0).toFixed(1)),
+  };
+}
+
+export async function query(site, { startDate, endDate }, body, options = {}) {
+  const payload = await gsc(sitePath(site, "/searchAnalytics/query"), {
+    ...options,
+    method: "POST",
+    body: { startDate, endDate, dataState: "final", ...body },
+  });
+  return payload.rows ?? [];
+}
+
+/** Totals for a window: one query with no dimensions. */
+export async function totals(site, dates, extra = {}, options = {}) {
+  const [row_] = await query(site, dates, { ...extra }, options);
+  return {
+    clicks: row_?.clicks ?? 0,
+    impressions: row_?.impressions ?? 0,
+    ctr: row_?.ctr ?? 0,
+    position: row_?.position ?? 0,
+  };
+}
+
+export async function performanceCommand(argv) {
+  if (wantsHelp(argv)) return HELP.performance;
+  const { values } = parse(argv, {
+    command: "performance",
+    flags: {
+      ...DATE_FLAGS,
+      by: { type: "string" },
+      limit: { type: "string" },
+      type: { type: "string" },
+      country: { type: "string" },
+      device: { type: "string" },
+      contains: { type: "string" },
+    },
+  });
+  const dimension = resolveDimension(values.by ?? "query");
+  const limit = positiveInt(values.limit, "--limit", DEFAULT_LIMIT);
+  const type = values.type ?? "web";
+  if (!TYPES.includes(type)) {
+    throw new AxiError(`unknown --type ${type}`, "VALIDATION_ERROR", [`valid types: ${TYPES.join(", ")}`]);
+  }
+  const dates = window(values);
+  const site = await resolveSite(values.site);
+
+  const rows = await query(site, dates, {
+    dimensions: [dimension],
+    rowLimit: limit,
+    type,
+    dimensionFilterGroups: filters({ ...values, by: dimension }),
+  });
+
+  if (rows.length === 0) {
+    return {
+      site,
+      window: `${dates.startDate}..${dates.endDate}`,
+      [dimension]: `0 rows in this window`,
+      help: [
+        `Run \`${BIN} performance --range 90d\` for a wider window`,
+        "Search Console finalises data on a 2-3 day delay",
+      ],
+    };
+  }
+  return {
+    site,
+    window: `${dates.startDate}..${dates.endDate}`,
+    count: `${rows.length} shown`,
+    [`by_${dimension}`]: rows.map((entry) => row(entry, [dimension])),
+    help: [
+      `Run \`${BIN} performance --by page\` for the pages behind these`,
+      `Run \`${BIN} opportunities\` for queries ranking 4-20`,
+    ],
+  };
+}
+
+function delta(now, before) {
+  if (!before) return now ? "+100%" : "0%";
+  const change = ((now - before) / before) * 100;
+  return `${change >= 0 ? "+" : ""}${change.toFixed(1)}%`;
+}
+
+export async function compareCommand(argv) {
+  if (wantsHelp(argv)) return HELP.compare;
+  const { values } = parse(argv, {
+    command: "compare",
+    flags: { ...DATE_FLAGS, by: { type: "string" }, limit: { type: "string" } },
+  });
+  const dates = window(values);
+  const before = previous(dates);
+  const site = await resolveSite(values.site);
+
+  const [current, prior] = await Promise.all([totals(site, dates), totals(site, before)]);
+  const summary = {
+    clicks: `${current.clicks} (${delta(current.clicks, prior.clicks)})`,
+    impressions: `${current.impressions} (${delta(current.impressions, prior.impressions)})`,
+    ctr: `${(current.ctr * 100).toFixed(1)}% (was ${(prior.ctr * 100).toFixed(1)}%)`,
+    position: `${current.position.toFixed(1)} (was ${prior.position.toFixed(1)})`,
+  };
+
+  if (!values.by) {
+    return {
+      site,
+      window: `${dates.startDate}..${dates.endDate}`,
+      against: `${before.startDate}..${before.endDate}`,
+      change: summary,
+      help: [`Run \`${BIN} compare --by query\` to see which queries moved`],
+    };
+  }
+
+  const dimension = resolveDimension(values.by);
+  const limit = positiveInt(values.limit, "--limit", DEFAULT_LIMIT);
+  const [nowRows, beforeRows] = await Promise.all([
+    query(site, dates, { dimensions: [dimension], rowLimit: 200 }),
+    query(site, before, { dimensions: [dimension], rowLimit: 200 }),
+  ]);
+  const priorClicks = new Map(beforeRows.map((entry) => [entry.keys?.[0], entry.clicks ?? 0]));
+
+  const moved = nowRows
+    .map((entry) => {
+      const key = entry.keys?.[0];
+      const was = priorClicks.get(key) ?? 0;
+      return { [dimension]: key, clicks: entry.clicks, was, change: (entry.clicks ?? 0) - was };
+    })
+    .sort((a, b) => Math.abs(b.change) - Math.abs(a.change))
+    .slice(0, limit);
+
+  return {
+    site,
+    window: `${dates.startDate}..${dates.endDate}`,
+    against: `${before.startDate}..${before.endDate}`,
+    change: summary,
+    moved,
+  };
+}
+
+export async function opportunitiesCommand(argv) {
+  if (wantsHelp(argv)) return HELP.opportunities;
+  const { values } = parse(argv, {
+    command: "opportunities",
+    flags: { ...DATE_FLAGS, "min-impressions": { type: "string" }, limit: { type: "string" } },
+  });
+  const floor = positiveInt(values["min-impressions"], "--min-impressions", 50);
+  const limit = positiveInt(values.limit, "--limit", DEFAULT_LIMIT);
+  const dates = window(values);
+  const site = await resolveSite(values.site);
+
+  // The API cannot filter on position, so pull a wide page and rank locally.
+  const rows = await query(site, dates, { dimensions: ["query"], rowLimit: 1000 });
+  const found = rows
+    .filter((entry) => (entry.position ?? 0) >= 4 && (entry.position ?? 0) <= 20)
+    .filter((entry) => (entry.impressions ?? 0) >= floor)
+    .sort((a, b) => b.impressions - a.impressions)
+    .slice(0, limit);
+
+  if (found.length === 0) {
+    return {
+      site,
+      window: `${dates.startDate}..${dates.endDate}`,
+      opportunities: `0 queries rank 4-20 with at least ${floor} impressions`,
+      help: [`Run \`${BIN} opportunities --min-impressions 10\` to lower the floor`],
+    };
+  }
+  return {
+    site,
+    window: `${dates.startDate}..${dates.endDate}`,
+    count: `${found.length} of ${rows.length} queries`,
+    note: "ranking 4-20 — a page of one already, so position gains convert fastest",
+    opportunities: found.map((entry) => row(entry, ["query"])),
+  };
+}

package/src/commands/setup.js

@@ -0,0 +1,103 @@
+import { AxiError } from "axi-sdk-js";
+import {
+  installSessionStartHooks,
+  sessionStartHookStatus,
+  uninstallSessionStartHooks,
+} from "axi-sdk-js";
+import { BIN, helpFor, makeDispatcher, parse, wantsHelp } from "../args.js";
+
+const MARKER = "gsc-axi";
+
+const HELP = {
+  hooks: helpFor({
+    command: "setup hooks",
+    description: "Install SessionStart hooks so agents see your deployments before acting",
+    usage: `${BIN} setup hooks [--repo]`,
+    flags: { "--repo": "Install into this repository instead of the user config" },
+    examples: [`${BIN} setup hooks`, `${BIN} setup hooks --repo`],
+  }),
+  status: helpFor({
+    command: "setup status",
+    description: "Report which agent session hooks are installed",
+    usage: `${BIN} setup status [--repo]`,
+    examples: [`${BIN} setup status`],
+  }),
+  uninstall: helpFor({
+    command: "setup uninstall",
+    description: "Remove the session hooks this tool installed",
+    usage: `${BIN} setup uninstall [--repo]`,
+    examples: [`${BIN} setup uninstall`],
+  }),
+};
+
+function scopeOf(values) {
+  return values.repo ? { scope: "project", projectDir: process.cwd() } : { scope: "user" };
+}
+
+const SCOPE_FLAG = { repo: { type: "boolean" } };
+
+function statusRows(status) {
+  return [
+    { agent: "claude", installed: status.claude.installed, path: status.claude.path },
+    { agent: "codex", installed: status.codex.installed, path: status.codex.path },
+    { agent: "opencode", installed: status.opencode.installed, path: status.opencode.path },
+  ];
+}
+
+async function hooks(argv) {
+  if (wantsHelp(argv)) return HELP.hooks;
+  const { values } = parse(argv, { command: "setup hooks", flags: SCOPE_FLAG });
+  const scope = scopeOf(values);
+  const problems = [];
+  installSessionStartHooks({ marker: MARKER, ...scope, onError: (m) => problems.push(m) });
+  const status = sessionStartHookStatus({ marker: MARKER, ...scope });
+  return {
+    scope: status.scope,
+    hooks: statusRows(status),
+    ...(status.codex.installed && !status.codex.userFeatureEnabled
+      ? { note: `Codex needs [features].hooks = true in ${status.codex.userFeaturePath}` }
+      : {}),
+    ...(problems.length ? { warning: problems.join("; ") } : {}),
+    help: ["Restart your agent session so the new hook takes effect"],
+  };
+}
+
+async function status(argv) {
+  if (wantsHelp(argv)) return HELP.status;
+  const { values } = parse(argv, { command: "setup status", flags: SCOPE_FLAG });
+  const result = sessionStartHookStatus({ marker: MARKER, ...scopeOf(values) });
+  const installed = statusRows(result).filter((row) => row.installed);
+  return {
+    scope: result.scope,
+    hooks: statusRows(result),
+    ...(installed.length === 0
+      ? { help: [`Run \`${BIN} setup hooks\` to install them`] }
+      : { help: [`Run \`${BIN} setup uninstall\` to remove them`] }),
+  };
+}
+
+async function uninstall(argv) {
+  if (wantsHelp(argv)) return HELP.uninstall;
+  const { values } = parse(argv, { command: "setup uninstall", flags: SCOPE_FLAG });
+  const scope = scopeOf(values);
+  const problems = [];
+  uninstallSessionStartHooks({ marker: MARKER, ...scope, onError: (m) => problems.push(m) });
+  const result = sessionStartHookStatus({ marker: MARKER, ...scope });
+  return {
+    scope: result.scope,
+    hooks: statusRows(result),
+    ...(problems.length ? { warning: problems.join("; ") } : {}),
+  };
+}
+
+export const setupCommand = makeDispatcher(
+  "setup",
+  { hooks, status, uninstall },
+  {
+    summary: {
+      hooks: "Install SessionStart hooks for Claude Code, Codex, and OpenCode",
+      status: "Report which session hooks are installed",
+      uninstall: "Remove the session hooks this tool installed",
+    },
+  },
+);