ts-axi 0.1.9 → 0.1.10

package/README.md

@@ -11,9 +11,9 @@ $ ts-axi impact main...HEAD
 base: 923fb4d7ddc8f4e5c4df9029be388f8cb29ce095
 head: HEAD
 changes: 2
-changed[2]{symbol,kind,change,exported,at,refs_total,refs_outside,via,files,tests}:
-  formatPrice,function,signature,true,"src/lib/format.ts:5",13,12,0,6,2
-  Cart.total,method,body,true,"src/lib/cart.ts:32",8,8,0,5,3
+changed[2]{symbol,change,at,refs_outside}:
+  formatPrice,signature,"src/lib/format.ts:5",12
+  Cart.total,body,"src/lib/cart.ts:32",8
 refs[20]{symbol,file,line,context}:
   formatPrice,src/components/Counter.tsx,2,"import { formatPrice } from '../lib';"
   formatPrice,src/components/Counter.tsx,12,"{cups} cups = {formatPrice(cups * CUP_CENTS)}"
@@ -25,17 +25,18 @@ refs[20]{symbol,file,line,context}:
 blind_spots[1]{symbol,file,line,reason}:
   Cart.total,src/components/CartSummary.tsx,16,string key 'total' on a type without that member
 elapsed_ms: 679
-help[5]:
+help[6]:
   - "Run `ts-axi refs src/lib/format.ts:5` for every Reference of formatPrice"
   - "Run `ts-axi callers src/lib/format.ts:5` for its call sites with the enclosing function"
   - "Run `ts-axi def src/lib/format.ts:5` for the changed declaration"
+  - Run `ts-axi impact main...HEAD --fields files,tests` for how many files and Test files reference each Symbol
   - Run `ts-axi impact main...HEAD --grep` for textual matches the checker cannot see
   - Run `ts-axi impact main...HEAD --depth 2` for who calls the callers
 ```
 
-(`...` marks rows cut from this README; the command prints all 20.)
+(`...` marks rows cut from this README; the command prints all 20. `--fields all` restores the full row: `{symbol,kind,change,exported,at,refs_total,refs_outside,via,files,tests}`.)
 
-Read-only: no lint, no refactor, no rename.
+Read-only on your code: no lint, no refactor, no rename. The only files it writes are `.ts-axi.json` (`config set`) and, when you ask for it, your agents' hook config (`setup hooks`).
 
 ## Status (v0.1.4)
 
@@ -63,12 +64,15 @@ Then tell your agent about it - one line in `CLAUDE.md` / `AGENTS.md`:
 Use `ts-axi` to find definitions, references and callers in TypeScript/JavaScript code, and `ts-axi impact` to see what a diff affects before reviewing it.
 ```
 
-Or install the on-demand Agent Skill (no per-session cost):
+Or install one of the two integrations (you only need one):
 
 ```sh
-npx skills add cmosgh/ts-axi --skill ts-axi
+ts-axi setup hooks                           # SessionStart hook: the project overview as ambient context (Claude Code, Codex, OpenCode)
+npx skills add cmosgh/ts-axi --skill ts-axi  # on-demand Agent Skill, no per-session cost
 ```
 
+The hook runs `ts-axi` with no arguments: it reads only the file tree and git status (no compiler run, no network) and exits 0 in any directory. `ts-axi setup hooks --project` installs it for the current repository only, `ts-axi setup status` shows what is installed, and `ts-axi setup uninstall` removes only ts-axi's own entries.
+
 ## Commands
 
 | Command | What it does |
@@ -77,9 +81,10 @@ npx skills add cmosgh/ts-axi --skill ts-axi
 | `def <target>` | Declarations of a symbol by name (`save`, `User.save`, `path:line`): one match prints detail and body, several print a compact list, none prints `did_you_mean` |
 | `refs <target>` | References of one symbol, grouped by file, with test counts. A class member that implements an interface (or overrides a base) member counts only its direct References; calls through the interface are `via_interface: n (Iface.member)`, sibling implementations are dropped, and an interface member reports `implementations: n`. `--limit`, `--kind calls`, `--via` (via rows with a `via` column), `--implementations` |
 | `callers <target>` | Incoming calls of a function-like symbol, split the same way (`via_interface`, `--via`). `--depth 1..3` |
-| `outline <file>` | Top-level declarations in source order, class members nested. `--exports` |
-| `impact [<git-range> \| -]` | Declarations changed by the working tree (untracked files included; `--staged`), a git range (`main...HEAD`) or a unified diff on stdin (`bb-axi pr diff 42 --raw \| ts-axi impact -`), riskiest first: change class (`signature`, `removed`, `type`, `added`, `body`, `modified`), References outside the change set (direct only), a `via` count of calls through an interface or base member (`--via` lists them), test-file counts, `notes` (a signature change of a member that implements an interface member), `blind_spots`, `local_only`, `file_level` and `skipped` (non-TS files in the diff). `--limit`, `--depth 2..3`, `--grep`. Analyses the current checkout |
+| `outline <file>` | Top-level declarations in source order, class members nested: `{line,kind,name,signature}` (`{at,kind,name,signature}` over several files). `--exports`, `--fields exported` |
+| `impact [<git-range> \| -]` | Declarations changed by the working tree (untracked files included; `--staged`), a git range (`main...HEAD`) or a unified diff on stdin (`bb-axi pr diff 42 --raw \| ts-axi impact -`), riskiest first: change class (`signature`, `removed`, `type`, `added`, `body`, `modified`), References outside the change set (direct only), a `via` count of calls through an interface or base member (`--via` lists them), test-file counts, `notes` (a signature change of a member that implements an interface member), `blind_spots`, `local_only`, `file_level` and `skipped` (non-TS files in the diff). `--limit`, `--depth 2..3`, `--grep`. Rows default to `{symbol,change,at,refs_outside}`; `--fields kind,exported,refs_total,via,files,tests` (or `all`) adds columns. Analyses the current checkout |
 | `config` | Show effective settings with their source; `config set <key> <value>` and `config unset <key>` write `.ts-axi.json` |
+| `setup <hooks\|status\|uninstall>` | Opt-in SessionStart hook for Claude Code, Codex and OpenCode that runs the home view at session start. `--project` for the current repository only |
 
 `ts-axi <command> --help` prints a concise, complete flag reference. `-P <tsconfig>` selects a project on any command that may analyse types; `--json` prints the decoded payload.
 
@@ -135,9 +140,9 @@ The line numbers in front of the body are file lines, so an agent can cite or co
 ```
 $ ts-axi def parse
 symbol: parse
-matches[2]{file,line,kind,exported,signature}:
-  src/lib/parse.ts,1,function,true,"export function parse(input: string): number"
-  src/lib/query.ts,1,function,true,"export function parse(q: string): Record<string, string>"
+matches[2]{at,kind,signature}:
+  "src/lib/parse.ts:1",function,"export function parse(input: string): number"
+  "src/lib/query.ts:1",function,"export function parse(q: string): Record<string, string>"
 help[4]:
   - "Run `ts-axi def src/lib/parse.ts:1` for the one in src/lib/parse.ts"
   - "Run `ts-axi def src/lib/query.ts:1` for the one in src/lib/query.ts"
@@ -167,7 +172,7 @@ refs[1]{file,line,context}:
 ### Script-style JavaScript
 
 ```
-$ ts-axi outline client/app.js
+$ ts-axi outline client/app.js --fields exported
 decls[4]{line,kind,name,exported,signature}:
   6,function,CartCtrl,true,"controller CartCtrl($scope, priceService)"
   12,function,priceService,true,service priceService()

package/dist/src/args.js

@@ -171,14 +171,17 @@ export function parseFields(raw, available) {
     const requested = [
         ...new Set(raw
             .split(",")
-            .map((f) => f.trim())
+            .map((f) => f.trim().toLowerCase())
             .filter(Boolean)),
     ];
-    const bad = requested.filter((f) => !available.includes(f));
+    const bad = requested.filter((f) => f !== "all" && !available.includes(f));
     if (bad.length > 0) {
         throw usageError(`unknown field${bad.length > 1 ? "s" : ""}: ${bad.join(", ")}`, [
-            `available --fields: ${available.join(", ")}`,
+            `available --fields: ${available.join(", ")} (or all)`,
         ]);
     }
-    return requested;
+    if (requested.includes("all"))
+        return [...available];
+    // Columns keep the documented order whatever order they were asked in.
+    return available.filter((f) => requested.includes(f));
 }

package/dist/src/cli.js

@@ -5,13 +5,14 @@ import { homeCommand } from "./commands/home.js";
 import { impactCommand, IMPACT_HELP } from "./commands/impact.js";
 import { outlineCommand, OUTLINE_HELP } from "./commands/outline.js";
 import { callersCommand, CALLERS_HELP, refsCommand, REFS_HELP } from "./commands/refs.js";
+import { setupCommand, SETUP_HELP } from "./commands/setup.js";
 import { AxiError, exitCodeForError } from "./errors.js";
 import { renderErrorOutput, setJsonMode, toJson } from "./render.js";
 import { VERSION } from "./version.js";
 export const DESCRIPTION = "TypeScript/JavaScript symbol CLI for agents - definitions, references, callers, file outlines and change impact (what a diff affects) from the TypeScript compiler. Prefer it over grep for 'who uses this'.";
 export const TOP_HELP = `usage: ts-axi [command] [args] [flags]
-commands[7]:
-  (none)=project overview, def, refs, callers, outline, impact, config
+commands[8]:
+  (none)=project overview, def, refs, callers, outline, impact, config, setup (opt-in session hooks)
 targets:
   name (save), member (User.save) or position (src/a.ts:42 or src/a.ts:42:7)
 flags[4]:
@@ -32,6 +33,7 @@ const COMMAND_HELP = {
     outline: OUTLINE_HELP,
     impact: IMPACT_HELP,
     config: CONFIG_HELP,
+    setup: SETUP_HELP,
 };
 function command(name, handler, ctx) {
     return async (args) => (args.includes("-h") ? (COMMAND_HELP[name] ?? "").trimEnd() : handler(args, ctx));
@@ -70,10 +72,11 @@ export async function main(options = {}) {
                 outline: command("outline", outlineCommand, ctx),
                 impact: command("impact", impactCommand, ctx),
                 config: command("config", configCommand, ctx),
+                setup: command("setup", (args) => setupCommand(args), ctx),
             },
             getCommandHelp: (name) => COMMAND_HELP[name],
             renderUnknownCommand: (name) => `${renderErrorOutput(`unknown command '${name}'`, "VALIDATION_ERROR", [
-                "commands: def, refs, callers, outline, impact, config (no command = project overview)",
+                "commands: def, refs, callers, outline, impact, config, setup (no command = project overview)",
                 "Run `ts-axi --help` for examples",
             ])}\n`,
             formatError,

package/dist/src/commands/common.js

@@ -100,11 +100,10 @@ export function positionOf(group) {
 export const MATCH_ROWS = 20;
 /** `matches` (first MATCH_ROWS, shallowest first) plus `matches_total` / `truncated` past that. */
 export function matchRows(groups) {
+    // `at` pastes into `ts-axi def`; TS signatures carry `export`, and `--exported` narrows to exported ones.
     const rows = groups.slice(0, MATCH_ROWS).map((g) => ({
-        file: g.primary.file,
-        line: g.decls[0].nameLine,
+        at: positionOf(g),
         kind: g.primary.kind,
-        exported: g.primary.exported,
         signature: g.decls[0].signature,
     }));
     return { matches: rows, ...(groups.length > MATCH_ROWS ? { matches_total: groups.length, truncated: true } : {}) };

package/dist/src/commands/def.js

@@ -8,7 +8,7 @@ flags[7]:
   --kind <function|class|method|property|variable|interface|type|enum|enum-member|namespace|state>, --in <dir|glob> (repeatable; restrict to files), --exported, --fuzzy (substring, case-insensitive), --full (whole body; default first ${BODY_LINES} lines), -P <tsconfig>, --json
 output:
   1 match = file, line, kind, exported, signature + body fenced with file line numbers
-  several = matches[n]{file,line,kind,exported,signature} (at most ${MATCH_ROWS}; matches_total + truncated past that) + the narrowing forms (--in, --kind, Class.member, --exported) with how many each keeps
+  several = matches[n]{at,kind,signature} (at = path:line) (at most ${MATCH_ROWS}; matches_total + truncated past that) + the narrowing forms (--in, --kind, Class.member, --exported) with how many each keeps
   none = matches: 0 + did_you_mean
 examples[5]:
   ts-axi def User

package/dist/src/commands/home.js

@@ -1,7 +1,7 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { expectPositionals, flag, flags, parseArgs } from "../args.js";
-import { usageError } from "../errors.js";
+import { AxiError, usageError } from "../errors.js";
 import { currentBranch, dirtyFileCount, isGitRepo } from "../git.js";
 import { block, helpBlock, out } from "../render.js";
 import { SETTINGS_FILE, isTestFile, loadSettings, readSettingsFile } from "../settings.js";
@@ -95,11 +95,30 @@ export async function homeCommand(args, ctx) {
     expectPositionals(parsed, 0, "ts-axi [-P <tsconfig>] [--test-glob <glob>]");
     const cwd = ctx?.cwd ?? process.cwd();
     const project = flag(parsed, "--project");
-    const settings = loadSettings(cwd, {
-        testGlobs: flags(parsed, "--test-glob"),
-        ...(project !== undefined ? { project } : {}),
-    });
-    const tsconfig = resolveTsconfig(cwd, settings);
+    const overrides = { testGlobs: flags(parsed, "--test-glob"), ...(project !== undefined ? { project } : {}) };
+    // A broken .ts-axi.json must not fail the session-start view: report it and carry on without the file.
+    let broken;
+    let settings;
+    try {
+        settings = loadSettings(cwd, overrides);
+    }
+    catch (error) {
+        if (!(error instanceof AxiError))
+            throw error;
+        broken = error.message;
+        settings = loadSettings(cwd, { ...overrides, ignoreFile: true });
+    }
+    let tsconfig;
+    try {
+        tsconfig = resolveTsconfig(cwd, settings);
+    }
+    catch (error) {
+        if (!(error instanceof AxiError) || settings.sources.project !== SETTINGS_FILE)
+            throw error;
+        broken = error.message;
+        settings = loadSettings(cwd, { ...overrides, ignoreFile: true });
+        tsconfig = resolveTsconfig(cwd, settings);
+    }
     // Same rule as the semantic commands: no explicit project + a multi-project workspace = workspace scope.
     let workspace;
     if (settings.project === undefined && (tsconfig === undefined || hasMultiProjectSignal(settings.root))) {
@@ -121,13 +140,17 @@ export async function homeCommand(args, ctx) {
     ]);
     const testFiles = counted.files.filter((f) => isTestFile(rel(settings.root, f), settings)).length;
     const plus = counted.capped ? "+" : "";
-    const present = readSettingsFile(settings.root) !== undefined;
+    const present = broken === undefined && readSettingsFile(settings.root) !== undefined;
     const onDefaultBranch = git.branch === undefined || git.branch === "main" || git.branch === "master";
     const help = [];
-    if (git.dirty > 0 || !onDefaultBranch) {
+    if (broken !== undefined)
+        help.push(`Fix or delete ${SETTINGS_FILE} - def, refs, callers, impact and config refuse to run until then (outline still works)`);
+    if (broken === undefined && (git.dirty > 0 || !onDefaultBranch)) {
         help.push("Run `ts-axi impact` to see which other code your changes affect");
     }
-    help.push("Run `ts-axi outline <file>` to list the declarations in a file", "Run `ts-axi def <name>` to find where a symbol is declared", "Run `ts-axi config` to see or change the test-file globs", "Run `ts-axi --help` for all commands");
+    help.push("Run `ts-axi outline <file>` to list the declarations in a file", ...(broken === undefined
+        ? ["Run `ts-axi def <name>` to find where a symbol is declared", "Run `ts-axi config` to see or change the test-file globs"]
+        : []), "Run `ts-axi --help` for all commands");
     return out(block({
         root: settings.root,
         ...(workspace ? { workspace: `${workspace.kind} (${workspace.projects.length} projects)` } : {}),
@@ -140,6 +163,6 @@ export async function homeCommand(args, ctx) {
         test_globs: settings.testGlobs.length,
         test_files: counted.capped ? `${testFiles}${plus}` : testFiles,
         git: git.text,
-        settings: `${SETTINGS_FILE} (${present ? "present" : "absent"})`,
+        settings: broken !== undefined ? `${SETTINGS_FILE} (ignored - ${/not valid JSON/.test(broken) ? "not valid JSON" : broken.replace(`${SETTINGS_FILE} `, "")})` : `${SETTINGS_FILE} (${present ? "present" : "absent"})`,
     }), helpBlock(help));
 }

package/dist/src/commands/impact.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, relative, sep } from "node:path";
 import ts from "typescript";
-import { bool, intFlag, parseArgs, flag } from "../args.js";
+import { bool, flag, intFlag, parseArgs, parseFields } from "../args.js";
 import { changedRanges, parseUnifiedDiff } from "../diff.js";
 import { AxiError, usageError } from "../errors.js";
 import { diffNameStatus, diffUnified, isGitRepo, resolveBaseRev, showFile, untrackedFiles } from "../git.js";
@@ -24,10 +24,10 @@ input:
   (none) = working tree vs HEAD (staged + unstaged + untracked); --staged = index vs HEAD
   <git-range> = any git diff range (main...HEAD, abc123, v1..v2); - = unified diff on stdin (needs the after side checked out)
   analysis is of the current checkout - for a range whose head is not the working tree, check that head out first
-flags[7]:
-  --staged, --via (adds References through an interface or base member to refs[n] with a via column), --depth <1-3> (callers_depthN[n]{file,count} for N > 1), --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} ref rows across the report), --grep (adds unresolved[n]{file,line,context} - textual matches that are not References; also searches .astro/.vue/.svelte/.mdx/.html), --test-glob <glob> (repeatable), -P <tsconfig>, --json
+flags[8]:
+  --staged, --via (adds References through an interface or base member to refs[n] with a via column), --depth <1-3> (callers_depthN[n]{file,count} for N > 1), --limit <1-${MAX_LIMIT}> (default ${DEFAULT_LIMIT} ref rows across the report), --grep (adds unresolved[n]{file,line,context} - textual matches that are not References; also searches .astro/.vue/.svelte/.mdx/.html), --test-glob <glob> (repeatable), --fields <kind,exported,refs_total,via,files,tests|all> (extra changed[n] columns), -P <tsconfig>, --json
 output:
-  base, head, changes (count), changed[n]{symbol,kind,change,exported,at,refs_total,refs_outside,via,files,tests}
+  base, head, changes (count), changed[n]{symbol,change,at,refs_outside} by default; --fields adds columns in place, --fields all gives {symbol,kind,change,exported,at,refs_total,refs_outside,via,files,tests}
   change = signature | removed | type | added | body | modified (before unavailable) - riskiest first
   textual = column added only when an untyped (JavaScript; implicit project) Symbol has more whole-word matches outside the change set than refs_outside - those are uses the checker cannot resolve (declaring file only for a non-exported local); - for typed rows; such a Change is never local_only
   refs_* / files / tests count direct References only; via = References outside the change set that reach the Symbol through an interface or base member it implements (or name an override of it) - they MAY call it
@@ -38,7 +38,7 @@ output:
   templates = column added only when a changed Symbol is one templates name (directive, component, binding, controller, filter): its usages in .html/.htm/.ejs/.hbs/.njk/.pug files; - for other rows; such a Change is never local_only
   template_changes[n]{file,symbols} = templates in the diff that use a changed directive, binding, controller or filter - review them with that change
   skipped[n]{file,reason} = files in the diff that were not analysed (.astro, .json, outside the Project)
-  tests: 0 on an exported signature or body change = no Test file references it
+  tests: 0 on an exported signature or body change = no Test file references it (columns from --fields exported,tests)
   scope = in a monorepo without -P the program is the touched files + two levels of importers (scope_partial: true when capped)
 examples[5]:
   ts-axi impact
@@ -54,8 +54,12 @@ const SPECS = [
     { name: "--limit" },
     { name: "--grep", boolean: true },
     { name: "--test-glob", repeatable: true },
+    { name: "--fields" },
     { name: "-P" },
 ];
+// Opt-in columns of changed[n]; the default keeps symbol, change, at, refs_outside.
+const IMPACT_FIELDS = ["kind", "exported", "refs_total", "via", "files", "tests"];
+const OPT_IN = new Set(IMPACT_FIELDS);
 async function readStdin() {
     if (process.stdin.isTTY) {
         throw usageError("`impact -` reads a unified diff from stdin and nothing was piped", ["git diff -U0 | ts-axi impact -"]);
@@ -383,15 +387,33 @@ function capped(key, rows) {
         ...(rows.length > SIDE_ROWS ? { [`${key}_total`]: rows.length } : {}),
     };
 }
+/** Quotes a value for a pasteable command. */
+function shellWord(value) {
+    return /^[\w@%+=:,.\/-]+$/.test(value) ? value : `'${value.replace(/'/g, "'\\''")}'`;
+}
+/** The same `impact` invocation with every given flag replayed, the one `extra` sets replaced by it. */
 function rerun(arg, parsed, extra) {
     const parts = ["ts-axi impact"];
     if (arg !== undefined)
-        parts.push(arg);
-    if (bool(parsed, "--staged"))
-        parts.push("--staged");
-    const project = flag(parsed, "-P");
-    if (project)
-        parts.push(`-P ${project}`);
+        parts.push(shellWord(arg));
+    const replaced = extra.split(" ")[0];
+    for (const spec of SPECS) {
+        if (spec.name === replaced)
+            continue;
+        if ("boolean" in spec) {
+            if (bool(parsed, spec.name))
+                parts.push(spec.name);
+        }
+        else if (spec.name === "--fields") {
+            const fields = parseFields(flag(parsed, "--fields"), IMPACT_FIELDS);
+            if (fields.length > 0)
+                parts.push(`--fields ${fields.length === IMPACT_FIELDS.length ? "all" : fields.join(",")}`);
+        }
+        else {
+            for (const value of parsed.values.get(spec.name) ?? [])
+                parts.push(`${spec.name} ${shellWord(value)}`);
+        }
+    }
     parts.push(extra);
     return `${arg === "-" ? "<diff> | " : ""}${parts.join(" ")}`;
 }
@@ -434,6 +456,7 @@ export async function impactCommand(args, ctx) {
     const staged = bool(parsed, "--staged");
     if (staged && arg !== undefined)
         throw usageError("--staged cannot be combined with a range or -", ["Run `ts-axi impact --staged` alone"]);
+    const extras = new Set(parseFields(flag(parsed, "--fields"), IMPACT_FIELDS));
     const limit = intFlag(parsed, "--limit", DEFAULT_LIMIT, { min: 1, max: MAX_LIMIT });
     const depth = intFlag(parsed, "--depth", 1, { min: 1, max: 3 });
     const grep = bool(parsed, "--grep");
@@ -663,6 +686,8 @@ export async function impactCommand(args, ctx) {
             help.push(`Run \`ts-axi callers ${top.at}\` for its call sites with the enclosing function`);
         help.push(`Run \`ts-axi def ${top.at}\` for the changed declaration`);
     }
+    if (listed.length > 0 && extras.size === 0)
+        help.push(`Run \`${rerun(arg, parsed, "--fields files,tests")}\` for how many files and Test files reference each Symbol`);
     const removedTop = listed.find((r) => r.change.change === "removed");
     if (removedTop)
         help.push(`${removedTop.symbol} was removed but is still referenced - those files break`);
@@ -697,19 +722,23 @@ export async function impactCommand(args, ctx) {
         ...header,
         ...(listed.length > 0
             ? {
-                changed: listed.map((r) => ({
-                    symbol: r.symbol,
-                    kind: r.kind,
-                    change: r.change.change,
-                    exported: r.exported,
-                    at: r.at,
-                    refs_total: r.all.length,
-                    refs_outside: r.outside.length,
-                    via: r.via.length,
-                    ...(gap > 0 ? { textual: r.textual ? r.textual.matches : "-" } : {}),
-                    ...(rows.some((x) => x.template) ? { templates: r.templates ? r.templates.length : "-" } : {}),
-                    ...fileCounts(r),
-                })),
+                changed: listed.map((r) => {
+                    // Built in the full column order, then cut to the default plus --fields, so --fields all matches the old output.
+                    const full = {
+                        symbol: r.symbol,
+                        kind: r.kind,
+                        change: r.change.change,
+                        exported: r.exported,
+                        at: r.at,
+                        refs_total: r.all.length,
+                        refs_outside: r.outside.length,
+                        via: r.via.length,
+                        ...(gap > 0 ? { textual: r.textual ? r.textual.matches : "-" } : {}),
+                        ...(rows.some((x) => x.template) ? { templates: r.templates ? r.templates.length : "-" } : {}),
+                        ...fileCounts(r),
+                    };
+                    return Object.fromEntries(Object.entries(full).filter(([k]) => !OPT_IN.has(k) || extras.has(k)));
+                }),
                 ...(refRows.length > 0 ? { refs: refRows } : {}),
             }
             : {}),

package/dist/src/commands/outline.js

@@ -1,16 +1,16 @@
 import { existsSync, statSync } from "node:fs";
 import { posix, relative, resolve, sep } from "node:path";
-import { bool, flag, parseArgs } from "../args.js";
+import { bool, flag, parseArgs, parseFields } from "../args.js";
 import { usageError } from "../errors.js";
 import { hasGlobMagic, matchesGlob } from "../glob.js";
 import { createSyntacticIndex, findRepoRoot, openProject, SOURCE_EXTENSIONS } from "../project.js";
 import { block, helpBlock, out } from "../render.js";
 const MAX_ROWS = 300;
 export const OUTLINE_HELP = `usage: ts-axi outline <file | glob>... [flags]
-flags[3]:
-  --exported (alias --exports; exported Declarations only), -P <tsconfig> (file list for globs), --json
+flags[4]:
+  --exported (alias --exports; exported Declarations only), --fields exported (adds an exported column), -P <tsconfig> (file list for globs), --json
 output:
-  one file = file + decls[n]{line,kind,name,exported,signature}; several = decls[n]{file,line,kind,name,exported,signature}
+  one file = file + decls[n]{line,kind,name,signature}; several = decls[n]{at,kind,name,signature} (at = path:line); --exported keeps only exported Declarations, --fields exported adds the column
   class members follow their class as Class.member; at most ${MAX_ROWS} rows
   kind state = a ui-router / ngRoute state as states.<name> (routes.<path>); its callbacks follow as states.<name>.resolve.<key> / states.<name>.onEnter
 examples[3]:
@@ -25,12 +25,14 @@ function isSource(path) {
 export async function outlineCommand(args, ctx) {
     const parsed = parseArgs(args, [
         { name: "--exported", alias: "--exports", boolean: true },
+        { name: "--fields" },
         { name: "-P" },
     ], COMMAND);
     if (parsed.positionals.length === 0) {
         throw usageError("missing argument", [`usage: ${COMMAND} <file | glob>... [--exported]`]);
     }
     const exportedOnly = bool(parsed, "--exported");
+    const showExported = parseFields(flag(parsed, "--fields"), ["exported"]).length > 0;
     const override = flag(parsed, "-P");
     const root = findRepoRoot(ctx.cwd);
     const cwdPrefix = relative(root, resolve(ctx.cwd)).split(sep).join("/");
@@ -73,11 +75,10 @@ export async function outlineCommand(args, ctx) {
     const shown = decls.slice(0, MAX_ROWS);
     const single = unique.length === 1;
     const rows = shown.map((d) => ({
-        ...(single ? {} : { file: d.file }),
-        line: d.nameLine,
+        ...(single ? { line: d.nameLine } : { at: `${d.file}:${d.nameLine}` }),
         kind: d.kind,
         name: d.qualifiedName,
-        exported: d.exported,
+        ...(showExported ? { exported: d.exported } : {}),
         signature: d.signature,
     }));
     const help = [];

package/dist/src/commands/setup.js

@@ -0,0 +1,97 @@
+import { readFileSync } from "node:fs";
+import { installSessionStartHooks, sessionStartHookStatus, uninstallSessionStartHooks } from "axi-sdk-js";
+import { bool, expectPositionals, parseArgs } from "../args.js";
+import { axiError, usageError } from "../errors.js";
+import { block, helpBlock, out } from "../render.js";
+export const SETUP_HELP = `usage: ts-axi setup <hooks|status|uninstall> [--project]
+Manage the opt-in SessionStart integration that shows the ts-axi project overview to Claude Code, Codex and OpenCode at session start.
+flags:
+  --project (install into the current repository's agent config instead of your user config)
+notes:
+  The overview only reads the file tree and git status: no compiler run, no network, exit 0 in any directory (outside a TS/JS project it is a few lines)
+  Only these hooks are touched; others in the same files are kept
+examples[3]:
+  ts-axi setup hooks
+  ts-axi setup hooks --project
+  ts-axi setup status
+`;
+// distEntrypoints names the built entrypoint explicitly; the SDK also infers it, so `node dist/bin/ts-axi.js setup hooks` installs either way.
+const IDENTITY = { marker: "ts-axi", binaryNames: ["ts-axi"], distEntrypoints: ["dist/bin/ts-axi.js"] };
+export async function setupCommand(args) {
+    const [sub, ...rest] = args;
+    if (sub !== "hooks" && sub !== "status" && sub !== "uninstall") {
+        throw usageError(sub ? `unknown setup action '${sub}'` : "missing setup action", [
+            "Run `ts-axi setup hooks` to install, `ts-axi setup status` to inspect, `ts-axi setup uninstall` to remove",
+        ]);
+    }
+    const command = `ts-axi setup ${sub}`;
+    const parsed = parseArgs(rest, [{ name: "--project", boolean: true }], command);
+    expectPositionals(parsed, 0, `${command} [--project]`);
+    const scope = bool(parsed, "--project") ? "project" : "user";
+    const flagHint = scope === "project" ? " --project" : "";
+    if (sub === "status") {
+        const status = sessionStartHookStatus({ ...IDENTITY, scope });
+        // Codex runs hooks only with `[features] hooks = true` in the user config.toml.
+        const codexOn = status.codex.installed && status.codex.userFeatureEnabled;
+        const agents = { claude_code: status.claude.installed, codex: codexOn, opencode: status.opencode.installed };
+        const missing = Object.values(agents).some((installed) => !installed);
+        return out(block({
+            hooks: {
+                scope,
+                claude_code: agents.claude_code ? "installed" : "not installed",
+                codex: codexOn ? "installed" : status.codex.installed ? "installed (hooks feature off)" : "not installed",
+                opencode: agents.opencode ? "installed" : "not installed",
+            },
+        }), helpBlock(missing ? [`Run \`ts-axi setup hooks${flagHint}\` to install the missing ones`] : []));
+    }
+    if (sub === "uninstall") {
+        const errors = [];
+        uninstallSessionStartHooks({ ...IDENTITY, scope, onError: (message) => errors.push(message) });
+        const left = installedAgents(scope);
+        if (errors.length > 0 || left.length > 0) {
+            throw axiError(`hooks not fully removed${left.length > 0 ? ` (still installed: ${left.join("; ")})` : ""}`, "SETUP_FAILED", errors);
+        }
+        return block({ hooks: { scope, status: "removed (or were not installed)" } });
+    }
+    const before = configSnapshot(scope);
+    // The SDK skips exec paths it does not recognise and reports write failures only via onError, so verify by re-reading.
+    const errors = [];
+    installSessionStartHooks({ ...IDENTITY, scope, onError: (message) => errors.push(message) });
+    const installed = installedAgents(scope, true);
+    if (installed.length === 0) {
+        throw axiError("no hooks were installed", "SETUP_FAILED", errors.length > 0 ? errors : [
+            "Hooks are only installed from an installed binary, not npx: run `npm i -g ts-axi`, then `ts-axi setup hooks`",
+        ]);
+    }
+    if (errors.length > 0 || installed.length < 3) {
+        throw axiError(`hooks only partly installed (installed: ${installed.join("; ")})`, "SETUP_FAILED", errors);
+    }
+    if (configSnapshot(scope) === before) {
+        return block({ hooks: { scope, status: "already installed (no-op)", integrations: installed.join("; ") } });
+    }
+    return out(block({ hooks: { scope, status: "installed", integrations: installed.join("; ") } }), helpBlock(["Restart the agent session to get the ts-axi project overview as ambient context"]));
+}
+/** Contents of the agent config files the hooks live in; equal before and after = nothing was written. */
+function configSnapshot(scope) {
+    const status = sessionStartHookStatus({ ...IDENTITY, scope });
+    return [status.claude.path, status.codex.path, status.codex.userFeaturePath, status.opencode.path]
+        .map((path) => {
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch {
+            return "";
+        }
+    })
+        .join("\0");
+}
+/** `active`: count Codex only when its hooks feature is on (after an install); uninstall checks the entries alone. */
+function installedAgents(scope, active = false) {
+    const status = sessionStartHookStatus({ ...IDENTITY, scope });
+    const agents = [
+        ["Claude Code", status.claude.installed],
+        ["Codex", status.codex.installed && (!active || status.codex.userFeatureEnabled)],
+        ["OpenCode", status.opencode.installed],
+    ];
+    return agents.filter(([, installed]) => installed).map(([agent]) => agent);
+}

package/dist/src/errors.js

@@ -1,9 +1,7 @@
 import { AxiError, exitCodeForError as sdkExitCode } from "axi-sdk-js";
 export { AxiError };
-/** SDK mapping (2 usage, 1 otherwise) plus `GIT_ERROR` → 3. */
+/** SDK mapping: 2 for usage errors, 1 otherwise (`GIT_ERROR` included). */
 export function exitCodeForError(error) {
-    if (error instanceof AxiError && error.code === "GIT_ERROR")
-        return 3;
     return sdkExitCode(error);
 }
 export function usageError(message, suggestions = []) {

package/dist/src/git.js

@@ -42,7 +42,12 @@ function gitError(result, args) {
     const message = first.replace(/^(fatal|error): /, "");
     const suggestions = /not a git repository/i.test(first)
         ? ["Run `ts-axi impact -` with a unified diff on stdin instead"]
-        : [];
+        : /unknown revision|bad revision|invalid object name|no merge base/i.test(first)
+            ? [
+                "Run `git branch -a` or `git log --oneline -5` to pick an existing revision",
+                "Run `ts-axi impact` for uncommitted changes, or `ts-axi impact <base>...HEAD` for a branch",
+            ]
+            : [];
     return new AxiError(message, "GIT_ERROR", suggestions);
 }
 async function runOrThrow(cwd, args) {

package/dist/src/settings.js

@@ -74,7 +74,7 @@ export function writeSettingsFile(root, data) {
 }
 export function loadSettings(cwd, overrides = {}) {
     const root = findRoot(cwd);
-    const file = readSettingsFile(root);
+    const file = overrides.ignoreFile ? undefined : readSettingsFile(root);
     const fileGlobs = file?.testGlobs ?? [];
     // An empty list cannot replace the defaults: that would turn every file into a non-test.
     const replace = file?.testGlobsReplace === true && fileGlobs.length > 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-axi",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "AXI-compliant TypeScript symbol CLI for agents - definitions, references, callers, file outlines and change impact (blast radius) with token-efficient TOON output",
   "type": "module",
   "keywords": [