Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* `claudish hooks` — inspect, check and scaffold hooks.
*
* claudish hooks list [--json] every hook in effective order, then load errors
* claudish hooks check <file> [--json] load one module in isolation and validate it
* claudish hooks init [dir] write example-hook.ts + claudish-hooks.d.ts
* claudish hooks corpus [--write] [--json] replay recorded transcripts for divergences
* claudish hooks telemetry [--enable | --disable] show or change the upload consent
*
* `list` exists because the hook system is otherwise invisible: a user who edits
* `hooks.severity` has no way to tell whether their glob matched, or whether a
* built-in is off because it is scoped to foreign routes. It prints the
* effective order, which is the order actions are applied in.
*/
import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join, resolve } from "node:path";
import { HOOKS_AMBIENT_DTS } from "./hooks/ambient-dts.generated.js";
import { OBSERVER_HOOK_ID, observerEnabled } from "./hooks/builtins/observer.js";
import { parseHooksConfig } from "./hooks/config.js";
import { loadHookSet } from "./hooks/index.js";
import { loadUserHooks } from "./hooks/loader.js";
import { buildCorpus } from "./hooks/observer/corpus.js";
import { HOOK_API_VERSION } from "./hooks/public.js";
import type { RegisteredHook } from "./hooks/registry.js";
import { outboxPath } from "./hooks/telemetry/aggregate.js";
import { activeConfigFile, loadConfig } from "./profile-config.js";
import { cliAnsi } from "./theme/ansi.js";
// Theme-aware colour helpers. cliAnsi() is resolved inside each helper (at
// render time), never at module load — theme detection runs at CLI startup,
// after this module is imported.
const paint = (code: "GREEN" | "YELLOW" | "DIM" | "BOLD" | "RED") => (s: string) => {
const a = cliAnsi();
return `${a[code]}${s}${a.RESET}`;
};
const green = paint("GREEN");
const yellow = paint("YELLOW");
const red = paint("RED");
const dim = paint("DIM");
const bold = paint("BOLD");
function severityColor(sev: string): string {
if (sev === "fix") return green(sev);
if (sev === "warn") return yellow(sev);
return dim(sev);
}
/**
* A hook as `list --json` and `check --json` print it (§4.9). A built-in selected from catalog
* data also carries `catalogSelection`: on a route with a catalog connection the wire APIs and
* vendors there decide, and `models` only on a route without one.
*/
function hookRow(hook: RegisteredHook, severity: string) {
return {
id: hook.id,
source: hook.source,
events: [...hook.events],
defaultSeverity: hook.defaultSeverity,
severity,
routes: hook.routes,
models: [...hook.models],
...(hook.selectByUpstream && {
catalogSelection: {
wireApis: [...hook.selectByUpstream.wireApis],
vendors: [...hook.selectByUpstream.vendors],
},
}),
order: hook.order,
unsafe: hook.unsafe,
};
}
/** The scope line's selection: catalog facts first when the hook has them, then the name globs. */
function selectionOf(r: ReturnType<typeof hookRow>): string | null {
const globs = r.models.join(", ");
if (!r.catalogSelection) return r.models.join(",") !== "*" ? `models ${globs}` : null;
const facts = [
...r.catalogSelection.wireApis.map((w) => `wire ${w}`),
...r.catalogSelection.vendors.map((v) => `vendor ${v}`),
].join(" or ");
return `catalog ${facts}; without a catalog connection, models ${globs}`;
}
/* ───────────── list ───────────── */
async function list(json: boolean): Promise<number> {
// The config-load reporters write to stderr as they do for every claudish run (stdout
// stays pure JSON with --json). Per-module warnings are not printed twice: each is in
// `errors`, which this command reports.
const set = await loadHookSet({ hostMode: "other", moduleWarn: () => {} });
const rows = set.registry.hooks.map((h) => hookRow(h, set.registry.severityOf(h)));
if (json) {
console.log(
JSON.stringify(
{
apiVersion: HOOK_API_VERSION,
configFile: activeConfigFile(),
hooks: rows,
errors: set.errors,
behaviorConfigFound: set.behaviorConfigFound,
},
null,
2
)
);
return 0;
}
console.log(bold("\nHooks, in effective order\n"));
// A severity says how a hook acts once it runs; the observer also needs its own
// switch, so without it a `fix` row would read as active.
const observerOff = !observerEnabled(set.config);
for (const r of rows) {
const overridden =
r.severity !== r.defaultSeverity ? dim(` (default ${r.defaultSeverity})`) : "";
const unsafe = r.unsafe ? ` ${red("UNSAFE")}` : "";
const inactive =
r.id === OBSERVER_HOOK_ID && observerOff
? dim(" (inactive: hooks.observer.enabled is off)")
: "";
console.log(
` ${severityColor(r.severity).padEnd(18)} ${r.id}${overridden}${unsafe}${inactive}`
);
const scope = [
`${r.source}`,
`events ${r.events.join(", ")}`,
`routes ${r.routes}`,
selectionOf(r),
r.order !== "normal" ? `order ${r.order}` : null,
].filter(Boolean);
console.log(` ${dim(scope.join(" · "))}\n`);
}
console.log(dim(` config: ${activeConfigFile()}\n`));
if (set.errors.length > 0) {
console.log(bold("Not loaded\n"));
for (const e of set.errors) console.log(` ${yellow(e.module)}\n ${dim(e.reason)}\n`);
}
if (set.behaviorConfigFound) {
console.log(
yellow(' A "behavior" block is in the config. It is no longer read: move it to "hooks".\n')
);
}
return 0;
}
/* ───────────── check ───────────── */
async function check(file: string | undefined, json: boolean): Promise<number> {
if (!file) {
console.error("Usage: claudish hooks check <file> [--json]");
return 1;
}
const path = resolve(process.cwd(), file);
const notes: string[] = [];
const loaded = await loadUserHooks({
modules: [path],
configDir: process.cwd(),
hostMode: "other",
warn: (line) => notes.push(line),
});
const valid = loaded.errors.length === 0 && loaded.hooks.length > 0;
const hooks = loaded.hooks.map((u) => ({
id: u.id,
events: Object.keys(u.def.on ?? {})
.filter((k) => (u.def.on as Record<string, unknown>)[k] !== undefined)
.concat(Object.keys((u.def as { raw?: object }).raw ?? {}).map((k) => `raw.${k}`)),
unsafe: (u.def as { unsafe?: boolean }).unsafe === true,
}));
if (json) {
console.log(JSON.stringify({ file: path, valid, hooks, errors: loaded.errors }, null, 2));
return valid ? 0 : 1;
}
console.log(`\n ${valid ? green("valid") : red("invalid")} ${path}\n`);
for (const h of hooks) {
console.log(` ${h.id}${h.unsafe ? ` ${red("UNSAFE")}` : ""} ${dim(h.events.join(", "))}`);
}
if (hooks.length === 0 && loaded.errors.length === 0) {
console.log(` ${yellow("the module exports no hook")}`);
}
for (const e of loaded.errors) console.log(` ${red("✗")} ${e.reason}`);
console.log();
return valid ? 0 : 1;
}
/* ───────────── init ───────────── */
const EXAMPLE_HOOK = `/// <reference path="./claudish-hooks.d.ts" />
/**
* An example claudish hook. Add its path to "hooks.modules" in
* ~/.claudish/config.json, then run \`claudish hooks list\` to see it.
*
* Check it with: claudish hooks check example-hook.ts
*/
import type { HookDefinition } from "claudish/hooks";
export default {
apiVersion: 1,
id: "reply-language",
description: "Asks foreign models to answer in English",
routes: "foreign",
on: {
request(ctx) {
ctx.log(\`request for \${ctx.route.modelId}\`);
return [{ type: "injectSystemNote", text: "Always answer in English." }];
},
},
} satisfies HookDefinition;
`;
function init(dirArg: string | undefined): number {
const dir = dirArg ? resolve(process.cwd(), dirArg) : join(homedir(), ".claudish", "hooks");
const files: Array<[string, string]> = [
[join(dir, "example-hook.ts"), EXAMPLE_HOOK],
[join(dir, "claudish-hooks.d.ts"), HOOKS_AMBIENT_DTS],
];
const existing = files.filter(([path]) => existsSync(path)).map(([path]) => path);
if (existing.length > 0) {
for (const path of existing) console.error(`${path} already exists; not overwriting it.`);
return 1;
}
mkdirSync(dir, { recursive: true });
for (const [path, text] of files) writeFileSync(path, text, { flag: "wx" });
console.log(`\n wrote ${files.map(([p]) => p).join("\n wrote ")}\n`);
console.log(dim(` Add "${files[0]?.[0]}" to "hooks.modules" in ${activeConfigFile()}.\n`));
return 0;
}
/* ───────────── corpus ───────────── */
/** Per-model breakdown — the actionable part: it says WHICH models need a rule. */
function printByModel(records: { model?: string; outcome: string }[]): void {
const byModel = new Map<string, { ok: number; degraded: number }>();
for (const r of records) {
const m = r.model ?? "unknown";
const e = byModel.get(m) ?? { ok: 0, degraded: 0 };
if (r.outcome === "degraded") e.degraded++;
else e.ok++;
byModel.set(m, e);
}
if (byModel.size === 0) return;
console.log(bold(" by model (degraded / ok)\n"));
const ranked = [...byModel.entries()].sort(
(a, b) => b[1].degraded - a[1].degraded || b[1].ok - a[1].ok
);
for (const [model, v] of ranked) {
const flag = v.degraded > 0 ? yellow(String(v.degraded)) : dim(String(v.degraded));
console.log(` ${model.padEnd(26)} ${flag} / ${v.ok}`);
}
console.log();
}
function corpus(write: boolean, json: boolean): number {
const result = buildCorpus({ write });
if (json) {
console.log(JSON.stringify(result, null, 2));
return 0;
}
const degraded = result.records.filter((r) => r.outcome === "degraded");
const ok = result.records.filter((r) => r.outcome === "ok");
const catchable = degraded.filter((r) => r.observedPaths.length > 0);
console.log(bold("\nBehavior divergence corpus\n"));
console.log(` transcripts scanned : ${result.scanned}`);
console.log(` plan-exit records : ${result.records.length}`);
console.log(` ${green("plan found")} : ${ok.length}`);
console.log(` ${yellow("degraded (no plan)")} : ${degraded.length}`);
console.log(` of those, a hook would have fired on ${catchable.length}\n`);
printByModel(result.records);
if (result.outputPath) console.log(dim(` appended to ${result.outputPath}\n`));
else if (write) console.log(dim(" nothing to write (no records found)\n"));
else console.log(dim(" pass --write to append these records to the divergence log\n"));
return 0;
}
/* ───────────── telemetry ───────────── */
/**
* Flip `hooks.telemetry.enabled` in the global config, preserving every other
* key byte-for-byte. A RAW read-modify-write, deliberately not
* `saveConfig(loadConfig())`: `loadConfig` merges through an allow-list, so any
* key it does not enumerate would be dropped on save.
*/
function setTelemetryEnabled(value: boolean): void {
// The ACTIVE global config: with `--config` / `CLAUDISH_CONFIG` that is the
// override, which is also the file `loadConfig` reads back below.
const path = activeConfigFile();
let cfg: Record<string, unknown> = {};
try {
if (existsSync(path)) {
const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
cfg = parsed as Record<string, unknown>;
}
}
} catch {
// Garbled file → start from empty rather than crash. Matches readRawConfig.
}
const hooks =
cfg.hooks && typeof cfg.hooks === "object" && !Array.isArray(cfg.hooks)
? { ...(cfg.hooks as Record<string, unknown>) }
: {};
hooks.telemetry = { enabled: value };
cfg.hooks = hooks;
writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`, "utf-8");
}
/**
* Show — and change — the behaviour-telemetry opt-in. It states the retention
* period and the never-send list up front, because consent to something
* unstated is not consent.
*/
function telemetry(action: "status" | "enable" | "disable", json: boolean): number {
if (action !== "status") setTelemetryEnabled(action === "enable");
const on = parseHooksConfig(loadConfig().hooks, () => {}).telemetry?.enabled === true;
// Reports are spooled at exit and delivered by a LATER run, so a non-zero
// count is normal rather than a symptom.
let pending = 0;
try {
const path = outboxPath();
if (existsSync(path)) pending = readFileSync(path, "utf8").split("\n").filter(Boolean).length;
} catch {
// An unreadable outbox is not worth failing a status command over.
}
if (json) {
console.log(JSON.stringify({ enabled: on, pendingReports: pending }, null, 2));
return 0;
}
console.log(bold("\nBehavior telemetry\n"));
console.log(` status : ${on ? green("enabled") : dim("disabled")}`);
console.log(` pending : ${pending} session report(s) awaiting delivery\n`);
if (!on) {
console.log(" Opting in shares which models violate Claude Code conventions,");
console.log(" so hooks can be written for models we cannot test ourselves.\n");
console.log(dim(" Sent : model, provider, built-in hook id, tool name, decision counts,"));
console.log(dim(" a coarse context bucket, and categorical path relations"));
console.log(dim(" Never : your own hook ids, MCP tool names on their rows, file paths,"));
console.log(dim(" argument values, prompts, code, model output, credentials,"));
console.log(dim(" or repo/branch/project names"));
console.log(dim(" Session : identified by a salted hash, unlinkable across sessions"));
console.log(dim(" Kept : 12 months, then non-identifying weekly aggregates only\n"));
console.log(` Enable with ${bold("claudish hooks telemetry --enable")}\n`);
return 0;
}
console.log(dim(" Local journalling is always on and unaffected by this setting.\n"));
console.log(` Disable with ${bold("claudish hooks telemetry --disable")}\n`);
return 0;
}
/* ───────────── dispatch ───────────── */
const USAGE = `Usage:
claudish hooks list [--json]
claudish hooks check <file> [--json]
claudish hooks init [dir]
claudish hooks corpus [--write] [--json]
claudish hooks telemetry [--enable | --disable] [--json]
`;
/** Run `claudish hooks <action>`. Returns the process exit code. */
export async function hooksCommand(argv: string[]): Promise<number> {
const json = argv.includes("--json");
const positional = argv.filter((a) => !a.startsWith("-"));
const action = positional[0] ?? "list";
switch (action) {
case "list":
return list(json);
case "check":
return check(positional[1], json);
case "init":
return init(positional[1]);
case "corpus":
return corpus(argv.includes("--write"), json);
case "telemetry":
return telemetry(
argv.includes("--enable") ? "enable" : argv.includes("--disable") ? "disable" : "status",
json
);
default:
console.error(`Unknown action "${action}".\n\n${USAGE}`);
return 1;
}
}