Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
#!/usr/bin/env node
/**
* The `trail` CLI, also run as `graft`, its old name. Commands: build, ask,
* check, viz, mcp, callers, skeleton, grep, map, init. Git is the sync: commit
* graft/ and a clone has the graph. A workspace parent (≥2 git children)
* federates query commands across children.
*
* Both names run this file. Under `graft` every command keeps its old name and
* meaning; under `trail` the layout changes (see `TRAIL` below and brand.ts).
*/
import { spawnSync } from "node:child_process";
import "dotenv/config";
import { Command } from "commander";
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { basename, dirname, join, relative, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { Graft } from "./engine.js";
import { resolveConfig, type EngineConfig } from "./ai/providers.js";
import type { ProviderKind } from "./ai/llm/factory.js";
import { formatCheckReport } from "./context/check.js";
import { formatGraphCheckReport } from "./graph/check.js";
import { buildGraphIfMissing, runInit } from "./claude/init.js";
import { statuslineWanted } from "./claude/settings-merge.js";
import { runHostsInit } from "./hosts/init.js";
import { codexStatusLines, codexTrustLine } from "./hosts/codex-trust.js";
import { hostIds } from "./hosts/registry.js";
import { checkoutRoot, ensureRepoHome, keepsNotes, noteCount, rememberRepo, repoName, repoPlace, shownPath } from "./notes/home.js";
import { brand, cmd, graftNotice, strandedRepoNotice, tag } from "./brand.js";
import { branchDiff } from "./cloud/diff.js";
import { openBrowser } from "./util/browser.js";
import { committedAtBase, learningsAtBase, teammateEdits, withBaseLearnings } from "./check/learning-edits.js";
import { contextDirFor } from "./context/node-file.js";
import { loadGraphCached } from "./graph/load.js";
import { ensureFreshChildren, ensureFreshGraph, refreshNote } from "./graph/refresh.js";
import { isWorkspaceBuildRoot, readWorkspace } from "./graph/workspace.js";
import { NOT_GIT_LINE, homeFolderRefusal, isGitWorkTree } from "./init-guard.js";
import { hasGraftIndex, nearestGraftRoot } from "./graph/root.js";
import { unsupportedExtensions, supportedExtensions } from "./graph/source-files.js";
import { discoverWorkspaceChildren } from "./graph/scopes.js";
import {
runWorkspaceAsk,
runWorkspaceBuild,
runWorkspaceCallers,
runWorkspaceCheck,
runWorkspaceGrep,
runWorkspaceMap,
} from "./graph/workspace-cli.js";
import { formatInitEpilogue } from "./cli-epilogue.js";
import { planInit, selectedWrites } from "./hosts/plan.js";
import { planRetract, runRetract, changed, type Retraction } from "./hosts/retract.js";
import { compactWrites, formatNonInteractiveHelp, formatPlan, runPicker } from "./cli-picker.js";
import { buildGraphWithProgress } from "./claude/build-progress.js";
import { installBrainsServer, removeBrainsServer } from "./hosts/claude-global.js";
import { homedir } from "node:os";
import { formatUpgradeReport, formatVersionReport, getNpmViewVersion, readCurrentVersion, readPackageName, runUpgrade } from "./cli-meta.js";
import { nativeFallbackNotice } from "./graph/native.js";
import { patchBuildConfig, type BuildConfig } from "./util/state.js";
import { normalizePathPrefix } from "./util/paths.js";
import { latestSession, formatSessionStats, sessionInputRate } from "./claude/session-metrics.js";
import { listSessionIds, readSession, sessionDir } from "./claude/state.js";
import { costLabel, listNotes, noteName, notePlace, noteTargets, readingTokens, commitLines, PERSONAL_SAVED_LINE, PR_SPEEDUP, SECTIONS, tokensWorthSaying, sectionLead, shortDate, tokensLabel, writeNote, type Note, mentionedFiles } from "./notes/notes.js";
import { aboutTerms, currentSessionCost } from "./notes/session-cost.js";
import { flatLine, unmarkedWords } from "./notes/flatten.js";
import { beginLookBack, finishLookBack, type FoundSkill } from "./init/run.js";
import { keepCommand } from "./init/keep.js";
import { recordInit, snapInit } from "./init/install-paths.js";
import { finishPair, PairRun, validPairCode } from "./cloud/pair.js";
import { currentBranch, noteAuthor, teammatesOn } from "./notes/git-facts.js";
import { listSkills } from "./skills/skills.js";
import { registerSkillCommands } from "./skills/cli-skills.js";
import { gateNote, namesRepoSymbol, symbolCandidates, trackedFiles } from "./notes/note-gate.js";
import { recordLookup } from "./cloud/lookup-activity.js";
import { clearPending, cloudLines, loginLink, sessionKey, waitForConnect } from "./cloud/nudge.js";
import { addRepo, clearCloud, cloudEnabled, fetchMe, fetchTeam, isError, readCloud, serverUrl, trailUrl, useServer, writeCloud, type Cloud } from "./cloud/workspace.js";
import {
claimConnectCode,
connectAgain,
offlineLine,
learningsSummary,
machineName,
normalizeCode,
OnboardingReporter,
repoRef,
teammatesChecked,
teammatesFromGit,
tokensOnOneLookup,
} from "./cloud/onboarding.js";
import { inWorkspace, maybeSyncInBackground, recordActivity, runSyncChild, syncRepo, workspaceLearnings } from "./cloud/workspace-sync.js";
import type { CheckResult } from "./check/types.js";
import { checkLocally } from "./check/local-check.js";
import { findLearning, learningFileName, liveLearnings } from "./notes/learning-fields.js";
import { savedIdLine } from "./notes/replace.js";
import { formatOverlap, maybeRefreshBranches, overlapsWith, pushedWhen, readBranchCache, refreshBranches } from "./notes/branches.js";
import { ensureRepoTrail, LEARNINGS_DIR } from "./notes/repo-trail.js";
import type { AskResult } from "./ask/ask.js";
import { setInputRate } from "./context/savings.js";
import { formatUpdateNudge, maybeRefreshInBackground, readStamp, readUpdateCache, refreshUpdateCache, wiredHostIds, wiringOpts, writeStamp } from "./upkeep.js";
import { shouldMoveToTrail } from "./upkeep-run.js";
import {
countBucket,
errorCode,
filesBucket,
durationBucket,
formatDebug,
formatStatus,
firstRunNotice,
isTrackedCommand,
langsValue,
offReason,
maybeFlushInBackground,
patchState,
runFlush,
track,
trackFirstRunIfNew,
} from "./telemetry/index.js";
const program = new Command();
const currentVersion = readCurrentVersion(import.meta.url);
/**
* Started as `trail` rather than `graft`. Decided once, before any command is
* registered, because it changes which commands exist: under trail the old
* `graft trail …` group moves to the top level, `check` hands its name to the
* team check (the freshness check is `build --check`), and `stats` and
* `trail status` become one `status`. Under graft nothing moves.
*/
const TRAIL = brand() === "trail";
/** Help-screen groups under trail; graft keeps its one flat list. */
const GROUP = {
find: "Find code · your agent runs these:",
memory: "Learnings:",
setup: "Setup:",
cloud: "Workspace · your team's view, across repos:",
ci: "CI:",
} as const;
/** Put a command in a help group, under trail only. */
function grouped(c: Command, heading: string): Command {
if (TRAIL) c.helpGroup(heading);
return c;
}
/**
* What the `query` telemetry event will say, filled in by the command as it runs
* and emitted once from the `postAction` hook below.
*
* A module-level slot rather than a threaded parameter because the repo root is
* resolved deep inside each action (`queryRoot`) while the event is emitted
* centrally — and because a command that calls `process.exit` should simply
* report nothing, which falls out of never emitting until postAction.
*/
let queryNote: { repo?: string; hit?: "yes" | "no"; command?: string; notes?: string } = {};
/** Record the repo a query ran against, and pass it straight through so call
* sites stay one line. */
function noteQuery(dir: string): string {
queryNote.repo = dir;
// Every retrieval command funnels through here, which makes it the one place
// that can price this session's tokens before a formatter needs the number.
setInputRate(sessionInputRate(dir));
return dir;
}
/** Whether a query found anything. Only the commands that have a result count in
* hand call this; the property is simply absent for the others. */
function noteHit(found: boolean): void {
queryNote.hit = found ? "yes" : "no";
}
program
.name(brand())
.description(
TRAIL
? "A code map for your coding agents, and the learnings each session leaves\n" +
"in your repo's .trail/, so everyone's Claude in the repo starts from them."
: "Build a repo's context graph as linked markdown, and keep it in sync with the code.",
)
.version(currentVersion, "-v, --version")
.option("--dir <path>", "context graph directory (default: <repo>/graft)")
.option("--provider <name>", "LLM wire format: openai | anthropic | litellm | orcarouter (env GRAFT_PROVIDER)")
.option("--model <id>", "model id for the LLM pass (env GRAFT_MODEL)")
.option("--api-key <key>", "provider API key (env GRAFT_API_KEY)")
.option("--base-url <url>", "OpenAI-compatible endpoint URL (env GRAFT_BASE_URL)");
interface GlobalOpts {
dir?: string;
provider?: string;
model?: string;
apiKey?: string;
baseUrl?: string;
}
/** Config drawn from the global CLI flags (env + defaults fill the rest). */
function cliConfig(): EngineConfig {
const o = program.opts<GlobalOpts>();
return {
contextDir: o.dir,
provider: o.provider as ProviderKind | undefined,
model: o.model,
apiKey: o.apiKey,
baseUrl: o.baseUrl,
};
}
const engineFrom = (): Graft => new Graft(cliConfig());
/**
* Warn (never fail) when a user's `-e` extension has no parser, so it is never a silent
* no-op — `graft build -e ".vue"` used to accept it, index nothing, and exit 0. The
* supported set is listed so `-e` also answers "what is actually supported".
*/
function warnUnsupportedExtensions(exts?: string[]): void {
if (!exts?.length) return;
const bad = unsupportedExtensions(exts);
if (bad.length === 0) return;
for (const e of bad) {
const shown = e.trim().startsWith(".") ? e.trim() : `.${e.trim()}`;
console.error(`⚠ -e "${shown}": no parser registered for this extension, so it is ignored.`);
}
console.error(` supported: ${supportedExtensions().join(" ")}`);
}
/** Text for the omitted-`[dir]` case, shared by every query command's help. */
const DIR_ARG = ["[dir]", "repository root (default: nearest ancestor with a graft/ index)"] as const;
/**
* The root a query runs against: the dir the user named, else the nearest
* ancestor holding a graft index (`graph/root.ts`) so a shell or agent session
* in a subdirectory still finds the graph. The walk is announced on stderr —
* answering from an ancestor's graph must never be silent.
*/
function queryRoot(dir?: string): string {
if (dir !== undefined) return resolve(dir);
const { root, levels } = nearestGraftRoot(process.cwd(), program.opts<GlobalOpts>().dir);
if (levels > 0) console.error(`${tag()} no code map here: answering from ${contextDirFor(root, program.opts<GlobalOpts>().dir)}`);
return root;
}
/**
* Bring the graph up to date with the working tree before a query answers from it
* — the same gate the MCP tools run (see `graph/refresh.ts`). Cheap when nothing
* moved; a structural, $0 rebuild when it did. The note goes to stderr so `--json`
* stdout stays machine-readable.
*/
async function refreshBefore(dir: string, opts: { refresh?: boolean }): Promise<void> {
const globalDir = program.opts<GlobalOpts>().dir;
const root = resolve(dir);
const disabled = opts.refresh === false;
const ws = readWorkspace(root, globalDir);
const r = ws
? await ensureFreshChildren(root, ws.children, { contextDir: globalDir, disabled })
: await ensureFreshGraph(root, { contextDir: globalDir, disabled });
const note = refreshNote(r);
if (note) console.error(note);
}
/** Attached to every query command: `--no-refresh` answers from the graph exactly
* as it is on disk, no rebuild. */
const NO_REFRESH_FLAG = ["--no-refresh", "skip the freshness check: answer from the graph as-is"] as const;
const VIZ_TABS = ["context", "code", "outline"] as const;
type VizTab = (typeof VIZ_TABS)[number];
/**
* `--tabs context,code` → the tabs to write into an exported page.
*
* An unknown name is a caller mistake worth failing on rather than silently
* dropping: a page exported with a typo'd tab list would be missing a tab and
* nothing would say why. Undefined means "all of them", which is the default the
* exporter already applies.
*/
function parseTabs(raw: string | undefined): VizTab[] | undefined {
if (raw === undefined) return undefined;
const want = raw.split(",").map((t) => t.trim()).filter(Boolean);
const bad = want.filter((t) => !VIZ_TABS.includes(t as VizTab));
if (bad.length > 0 || want.length === 0) {
console.error(`✗ --tabs takes a comma-separated subset of ${VIZ_TABS.join(", ")}${bad.length ? `, not "${bad.join('", "')}"` : ""}`);
process.exit(1);
}
return want as VizTab[];
}
/**
* Commands that own the upgrade story themselves (`version`, `upgrade`) or must
* not editorialize on stderr at startup (`mcp` runs its own upkeep at boot, and
* `_update-check` IS the fetch).
*/
const UPKEEP_SKIP = new Set(["version", "upgrade", "_update-check", "mcp"]);
/**
* Every other command: top up the cached registry answer in the background and,
* if a newer graft is out, say so once on stderr. This is what makes the CLI the
* cache filler for the hooks, which are not allowed to touch the network.
*/
program.hook("preAction", (_parent, action) => {
if (UPKEEP_SKIP.has(action.name())) return;
// Someone typing graft by hand learns its new name, once a day. Agents,
// hooks, CI and pipes never see it (see graftNotice).
const renamed = graftNotice({ ran: spelling(action), tty: Boolean(process.stderr.isTTY) });
if (renamed) console.error(renamed);
// Someone typing trail in a repo whose graft-era hooks can't reach it learns
// the one command that moves it (init itself is that command).
const stranded = action.name() === "init" ? null : strandedRepoNotice({ cwd: process.cwd(), tty: Boolean(process.stderr.isTTY) });
if (stranded) console.error(stranded);
maybeRefreshInBackground();
const nudge = formatUpdateNudge(currentVersion, readUpdateCache()?.latest);
if (nudge) console.error(nudge);
// Telemetry, in the order a user should experience it: disclose first, then
// record, then (at most once a day, detached) send. Every step is a no-op in a
// fork, in CI, under DO_NOT_TRACK, or after `graft telemetry disable`.
const notice = firstRunNotice();
if (notice) console.error(notice);
trackFirstRunIfNew();
maybeFlushInBackground();
});
/**
* The `query` event, emitted after the command rather than before it, so it can
* carry what the query actually did. A command that exits early via
* `process.exit` never reaches here and is simply not counted — under-reporting
* is the right failure mode for a metric.
*/
program.hook("postAction", (_parent, action) => {
// `trail build --check` is graft's `check`, and counts as it always has.
const name = queryNote.command ?? action.name();
if (!isTrackedCommand(name)) return;
track("query", { command: name, surface: "cli", hit: queryNote.hit, notes: queryNote.notes }, { repo: queryNote.repo });
});
/** `graft ask`, `graft build`: a command as graft spells it, whatever ran it. */
function spelling(action: Command): string {
const words: string[] = [];
for (let c: Command | null = action; c && c.parent; c = c.parent) words.unshift(c.name());
return ["graft", ...words].join(" ");
}
// Hidden: spawned detached by maybeSyncInBackground when a workspace repo's
// learnings changed, or uses are waiting to go. Running it by hand syncs now.
program
.command("_trail-sync", { hidden: true })
.description("internal: send this repo's learnings and the waiting uses to the Trail workspace")
.argument("[dir]", "target repo directory", ".")
.action(async (dir: string) => {
await runSyncChild(resolve(dir));
});
// Hidden: spawned detached by maybeRefreshBranches.
program
.command("_trail-branches", { hidden: true })
.description("internal: fetch, then note which files teammates' open branches change and the learnings they carry")
.argument("[dir]", "target repo directory", ".")
.action((dir: string) => {
refreshBranches(resolve(dir), { prs: true });
});
program
.command("_trail-claim", { hidden: true })
.description("internal: wait for a sign-in through the link trail handed the agent, then connect the workspace")
.action(async () => {
await waitForConnect();
});
program
.command("_trail-pair", { hidden: true })
.description("internal: after `init --pair`, wait for the connect and the review in the browser, then upload the repo's learnings")
.argument("<state>")
.argument("<dir>")
.argument("[server]", "the Trail the run reported to (init's --server)")
.action(async (state: string, dir: string, server?: string) => {
const base = serverUrl(server);
if (base) useServer(base);
await finishPair(state, resolve(dir));
});
program
.command("_update-check", { hidden: true })
.description("internal: refresh the cached latest-version answer")
.action(() => {
refreshUpdateCache();
});
// Hidden for the same reason as _update-check: only ever spawned detached, by
// maybeFlushInBackground. Running it by hand is harmless — it drains the queue.
program
.command("_telemetry-flush", { hidden: true })
.description("internal: POST the queued anonymous usage events")
.action(async () => {
await runFlush();
});
grouped(program.command("telemetry"), GROUP.setup)
.description("Show, inspect, or turn off the anonymous usage stats (see TELEMETRY.md)")
.argument("[action]", "status (default) | enable | disable | debug", "status")
.action((action: string) => {
switch (action) {
case "status":
console.log(formatStatus());
return;
case "enable":
patchState({ enabled: true });
console.log(`telemetry: on, anonymous and aggregate-only. \`${cmd("graft telemetry status")}\` for details.`);
return;
case "disable":
// Also stamp the notice as shown: someone who has just opted out should
// not be told about telemetry again the next time they run a command.
patchState({ enabled: false, noticeShownAt: new Date().toISOString() });
console.log("telemetry: off. Nothing further will be recorded or sent.");
return;
case "debug":
console.log(formatDebug());
return;
default:
console.error(`✗ unknown action "${action}": expected status, enable, disable, or debug`);
process.exit(1);
}
});
// Hidden under trail, where -v says the same; listed under graft as it was.
program
.command("version", { hidden: TRAIL })
.description("Print the installed version and the latest published on npm")
.action(() => {
const latest = getNpmViewVersion();
console.log(formatVersionReport(currentVersion, latest));
});
grouped(program.command("upgrade"), GROUP.setup)
.description(`Upgrade the globally installed ${brand()} to the latest version on npm`)
.action(() => {
const result = runUpgrade(import.meta.url);
console.log(formatUpgradeReport(result));
if (result.ran && !result.ok) process.exit(1);
if (!TRAIL && result.ok && result.trailVersion) moveHereToTrail(process.cwd());
});
/**
* After `graft upgrade` brought the trail command along, the repo it ran in
* moves to trail now, with the agents and flags its last init chose, and its
* past sessions are read for learnings. Every other repo wired as graft moves
* the next time a session opens in it (upkeep-run.ts).
*/
function moveHereToTrail(dir: string): void {
const root = checkoutRoot(dir);
if (!root || !shouldMoveToTrail(root)) return;
const stamp = readStamp(root);
const hosts = [...new Set([...(stamp?.hosts ?? []), ...wiredHostIds(root)])];
const o = wiringOpts(stamp);
const flags = [o.global ? null : "--no-global", o.mcp ? null : "--no-mcp", o.hooks ? null : "--no-hooks", o.statusline ? null : "--no-statusline"].filter(
(f): f is string => f !== null,
);
console.log(`· moving this repo to trail: trail init ${hosts.length ? `--agents ${hosts.join(" ")} ` : ""}${flags.join(" ")}`.trimEnd());
spawnSync("trail", ["init", root, "--agents", ...hosts, ...flags], { stdio: "inherit" });
}
grouped(program.command("build"), GROUP.setup)
.description(
TRAIL
? "Rebuild the code map in .trail/cache/ ($0, no key). --check fails if it's stale; --deep adds LLM summaries."
: "Build graft/ from your code: wiring graph + per-file cards ($0, no key). " +
"Add --deep for the LLM concept map + per-symbol summaries/crux.",
)
.argument("[dir]", "repository root", ".")
.option("--check", "build nothing: fail if graft/ is stale relative to the code (for CI)")
.option("--json", "with --check: output the drift as JSON")
.option("--deep", "run the LLM pass: concept nodes (graft/*.md) + per-symbol summary/crux")
.option("-e, --extensions <exts...>", 'code extensions to include (e.g. ".ts" ".py"); an extension with no parser is ignored with a warning that lists the supported set')
.option("-j, --concurrency <n>", "files summarized in parallel during --deep (default 5)")
.option(
"--synth-concurrency <n>",
"concept synthesis batches in flight at once during --deep (default 4). Separate from -j: " +
"each synthesis call carries a whole batch of summaries, not one file",
)
.option("--no-reuse", "re-parse every file instead of replaying unchanged ones from the extraction cache")
.option("--lsp", "add compiler-grade call edges via a language server if one is installed (opt-in, slower; e.g. rust-analyzer, clangd)")
.option("--allow-partial", "with --deep: exit 0 even when some files' summaries failed (default: a degraded meaning tier exits 1)")
.option(
"--follow-submodules",
"include initialized Git submodules recursively; persisted for later builds and automatic refreshes",
)
.option(
"--no-follow-submodules",
"exclude Git submodules; persisted for later builds and automatic refreshes (default)",
)
.option(
"--follow-nested-repos",
"include nested Git clones the index does not track (a multi-repo manifest checkout, or any repo cloned into the tree) " +
"as ONE graph, so imports across them resolve; persisted for later builds and automatic refreshes",
)
.option(
"--no-follow-nested-repos",
"exclude untracked nested Git clones; persisted for later builds and automatic refreshes (default)",
)
.option(
"--include-dir <name>",
"override SKIP_DIRS for this repo's walks, repeatable (e.g. --include-dir build --include-dir tools); " +
"persisted, so a later build (and the hooks/refresh path) include it without the flag; dot-dirs are never overridable",
(val: string, prev: string[]) => [...prev, val],
[] as string[],
)
.option(
"--only-dir <path>",
"only index files under this repo-relative path, repeatable; the wiring walk and the --deep " +
"concept pass both honor it. Recorded in the graph fingerprint so a later build " +
"(and the hooks/refresh path) walks the same set; everything outside the list is skipped",
(val: string, prev: string[]) => [...prev, val],
[] as string[],
)
.option("--no-gitignore", "skip writing graft/ into .gitignore (same as GRAFT_NO_GITIGNORE=1)")
.option("--no-ignore", "skip writing .ignore for ripgrep re-admit (same as GRAFT_NO_IGNORE=1)")
.action(async (
dir: string,
opts: {
check?: boolean;
json?: boolean;
deep?: boolean;
extensions?: string[];
concurrency?: string;
reuse?: boolean;
lsp?: boolean;
allowPartial?: boolean;
synthConcurrency?: string;
includeDir?: string[];
onlyDir?: string[];
followSubmodules?: boolean;
followNestedRepos?: boolean;
gitignore?: boolean;
ignore?: boolean;
},
command: Command,
) => {
if (opts.check) {
// The freshness check, which was `graft check`. Counted as `check` so the
// metric carries on across the rename; the dir defaults like a query's.
queryNote.command = "check";
await runCheckCommand(command.args[0], { extensions: opts.extensions, json: opts.json }, cmd("graft check"));
return;
}
const buildStartedAt = Date.now();
if (opts.gitignore === false) process.env.GRAFT_NO_GITIGNORE = "1";
if (opts.ignore === false) process.env.GRAFT_NO_IGNORE = "1";
const concurrency = opts.concurrency ? Math.max(1, Number(opts.concurrency)) : undefined;
if (opts.concurrency && !Number.isFinite(concurrency)) {
console.error(`✗ --concurrency must be a number, got "${opts.concurrency}"`);
process.exit(1);
}
const synthConcurrency = opts.synthConcurrency ? Math.max(1, Number(opts.synthConcurrency)) : undefined;
if (opts.synthConcurrency && !Number.isFinite(synthConcurrency)) {
console.error(`✗ --synth-concurrency must be a number, got "${opts.synthConcurrency}"`);
process.exit(1);
}
warnUnsupportedExtensions(opts.extensions);
// Persisted BEFORE the build itself runs, so this invocation's walks (and
// every later no-flag build / hooks refresh) see it identically — the
// walkDir call sites read it from state, not from a threaded option.
const buildConfigPatch: BuildConfig = {};
if (opts.includeDir && opts.includeDir.length > 0) {
// --include-dir takes bare SKIP_DIRS-style directory NAMES (shouldSkipDir
// compares a single path segment), never paths, and dot-dirs are never
// overridable at all (see the option's own help text) — reject anything
// else up front instead of silently persisting a value that can never
// match a real directory name.
for (const name of opts.includeDir) {
if (name.startsWith(".")) {
console.error(`✗ --include-dir "${name}": dot-directories are never overridable`);
process.exit(1);
}
if (name.includes("/") || name.includes("\\")) {
console.error(`✗ --include-dir "${name}": expected a bare directory name, not a path`);
process.exit(1);
}
}
buildConfigPatch.includeDirs = opts.includeDir;
}
// The whitelist is NOT persisted to `.graft/config.json`: it belongs with the
// graph (the fingerprint records it at build time), never in the source repo,
// so a `--only-dir` build leaves no trace under the repo being indexed.
let onlyDirs: string[] | undefined;
if (opts.onlyDir && opts.onlyDir.length > 0) {
// --only-dir takes a repo-relative path prefix, normalized to the same
// posix, no-`./`, no-trailing-slash form `--in` uses, so the prefix match
// is exact. A prefix that normalizes to "" (a bare "/" or ".") is rejected:
// it would mean "match nothing" or "match everything", neither of which is
// a deliberate whitelist.
const normalized = opts.onlyDir.map((p) => normalizePathPrefix(p)).filter((p) => p !== "");
if (normalized.length === 0) {
console.error("✗ --only-dir: expected a non-empty repo-relative path");
process.exit(1);
}
onlyDirs = normalized;
}
const followSubmodulesWasExplicit = command.getOptionValueSource("followSubmodules") === "cli";
if (followSubmodulesWasExplicit && typeof opts.followSubmodules === "boolean") {
buildConfigPatch.followSubmodules = opts.followSubmodules;
}
const followNestedReposWasExplicit = command.getOptionValueSource("followNestedRepos") === "cli";
if (followNestedReposWasExplicit && typeof opts.followNestedRepos === "boolean") {
buildConfigPatch.followNestedRepos = opts.followNestedRepos;
}
if (Object.keys(buildConfigPatch).length > 0) {
patchBuildConfig(resolve(dir), buildConfigPatch);
}
const engine = engineFrom();
const fmt = (o: Record<string, number>) =>
Object.entries(o)
.sort((a, b) => b[1] - a[1])
.map(([k, n]) => `${n} ${k}`)
.join(", ");
// --deep needs a key; without one, degrade to the $0 structural build.
let deep = opts.deep;
const resolved = resolveConfig(cliConfig());
if (deep && !resolved.apiKey) {
deep = false;
console.error(
"⚠ no API key set, so falling back to the structural build (no LLM summaries).\n" +
" Set GRAFT_API_KEY (and GRAFT_PROVIDER / GRAFT_BASE_URL / GRAFT_MODEL for your\n" +
` provider) and re-run \`${cmd("graft build --deep")}\` to add concept nodes and summaries.`,
);
}
if (deep && resolved.usedLegacyEnv) {
console.error(
"⚠ using OPENROUTER_API_KEY (deprecated): prefer GRAFT_API_KEY + GRAFT_BASE_URL.",
);
}
// Workspace parent: build each child into its OWN graft/ + a workspace index.
const buildRoot = resolve(dir);
const buildGlobalDir = program.opts<GlobalOpts>().dir;
if (isWorkspaceBuildRoot(buildRoot, buildGlobalDir)) {
await runWorkspaceBuild(buildRoot, {
deep: !!deep,
extensions: opts.extensions,
concurrency,
synthConcurrency,
childConfig: cliConfig(),
override: buildGlobalDir,
includeDirs: opts.includeDir,
followSubmodules: followSubmodulesWasExplicit ? opts.followSubmodules : undefined,
followNestedRepos: followNestedReposWasExplicit ? opts.followNestedRepos : undefined,
packageName: readPackageName(import.meta.url),
});
return;
}
// --deep: concept nodes first, then the wiring graph links cards up to them.
let conceptErrors: string[] = [];
let conceptFatal: string | undefined;
if (deep) {
const c = await engine.init(dir, {
extensions: opts.extensions,
onlyDirs,
synthConcurrency,
onProgress: ({ phase, index, total, file }) =>
process.stderr.write(
`\r${phase === "summarize" ? "reading" : "writing"} concepts ${index + 1}/${total}: ${file.slice(0, 40).padEnd(40)}`,
),
}).catch((err: unknown) => {
// Only the stage and a code enum; the message stays on this machine.
track("build_failed", { stage: "summarize", code: errorCode(err) }, { repo: buildRoot });
throw err;
});
process.stderr.write("\n");
const conceptLine = `concepts: ${c.nodes} nodes, ${c.links} links from ${c.files} files (${c.summarized} read, ${c.cached} cached)`;
if (c.nodes === 0) console.error(`⚠ ${conceptLine}`);
else console.log(`✓ ${conceptLine}`);
for (const e of c.errors) console.error(`✗ ${e}`);
conceptErrors = c.errors;
conceptFatal = c.fatal;
}
// Wiring graph — always; LLM meaning only with --deep.
const g = await engine.graph(dir, {
llm: deep,
concurrency,
reuse: opts.reuse,
lsp: opts.lsp,
onlyDirs,
onProgress: ({ phase, index, total, file }) =>
process.stderr.write(
`\r${phase === "enrich" ? "summarizing" : "parsing"} ${index + 1}/${total}: ${file.slice(0, 50).padEnd(50)}`,
),
}).catch((err: unknown) => {
track("build_failed", { stage: "graph", code: errorCode(err) }, { repo: buildRoot });
throw err;
});
process.stderr.write("\n");
console.log(`✓ wiring: ${g.nodes} nodes (${fmt(g.byKind)}), ${g.edges} edges, ${g.cards} cards [${g.languages.join(", ")}]`);
console.log(` parsed: ${g.parsed} of ${g.files} files (${g.reused} replayed from cache)`);
// Worth one line: this build started from a graph the user never built *here*.
if (g.seededFrom) console.log(` seeded: copied a starting graph from ${g.seededFrom} (git worktree)`);
if (deep) {
const m = g.meaning;
console.log(` meaning: ${m.computed} computed, ${m.cached} cached, ${m.stale} stale, ${m.pending} pending`);
}
console.log(` → ${g.contextDir}`);
// The activation event. Everything here is a bucket or a fixed label: repo
// scale rather than a file count, a language set rather than file names.
track(
"build_completed",
{
files_bucket: filesBucket(g.files),
langs: langsValue(g.languages),
mode: deep ? "deep" : "fast",
duration_bucket: durationBucket(Date.now() - buildStartedAt),
incremental: String(g.reused > 0),
},
{ repo: buildRoot },
);
for (const e of g.errors) console.error(`✗ ${e}`);
// A language whose native grammar didn't load was parsed by its WASM stand-in:
// say which, and the install that fixes it. Nothing when everything loaded.
const fallbackNotice = nativeFallbackNotice(g.nativeFallback, readPackageName(import.meta.url));
if (fallbackNotice) console.error(fallbackNotice);
const rel = relative(process.cwd(), g.contextDir) || "graft";
if (process.env.GRAFT_NO_GITIGNORE) {
console.log(` ${rel}/ is a local cache: add it to your gitignore if you want it untracked.`);
} else {
console.log(` ${rel}/ is git-ignored (added automatically), a local cache; teammates run \`${cmd("graft build")}\` to get their own.`);
}
// #127: a --deep run whose LLM calls failed used to print the same success
// footer and exit 0, so a quota-exhausted build looked identical to a clean
// one and `graft check` still said "in sync" (it only ever checked Tier-1).
// The structural graph IS still written and every successful summary is
// cached, so this is a loud warning about a degraded tier, not a rollback.
if (deep) {
const m = g.meaning;
const failed =
m.failedFiles > 0 || m.fatal !== undefined || conceptErrors.length > 0 || conceptFatal !== undefined;
if (failed) {
const ready = m.computed + m.cached;
const total = ready + m.stale + m.pending;
const pct = total > 0 ? Math.round((ready / total) * 100) : 0;
console.error("");
console.error(`✗ the deep pass did not complete, so the meaning tier is incomplete.`);
if (conceptFatal) console.error(` concepts: ${conceptFatal}`);
if (m.fatal) console.error(` summaries: ${m.fatal}`);
if (m.failedFiles > 0) {
const skipped = m.skippedFiles > 0 ? `, ${m.skippedFiles} never attempted` : "";
console.error(` ${m.failedFiles} file(s) failed to summarize${skipped}.`);
}
if (conceptErrors.length > 0) console.error(` ${conceptErrors.length} concept-pass error(s).`);
console.error(` meaning coverage: ${ready}/${total} symbols (${pct}%).`);
console.error(
` Nothing computed was lost: re-run \`${cmd("graft build --deep")}\` to resume from what is cached.\n` +
" Pass --allow-partial to accept a degraded meaning tier and exit 0.",
);
if (!opts.allowPartial) process.exitCode = 1;
}
}
});
/**
* After `ask`, under trail: which shown learnings are a teammate's, and the
* lookup recorded (the learnings shown are a use, which is what the team page
* counts as reuse; the tokens saved ride along). Then the background upkeep
* that keeps branches and the workspace current. Spawns no git itself. Teammates' branches come up after an edit
* instead, once there's a function to compare (notes/edit-overlap.ts).
*/
function afterAsk(r: AskResult, repo: string): void {
// Every lookup is reported, not only ones that showed a learning: the tokens
// the map saved are what the team page's running total counts. A no-op unless
// this machine is connected and the repo is the workspace's.
recordLookup(r, repo);
if (!r.notesChecked) return;
rememberRepo(repo);
maybeRefreshBranches(repo);
const me = noteAuthor(repo);
const shown = r.notes ?? [];
if (shown.length) {
for (const h of shown) h.note.teammate = !!h.note.author && !!me && h.note.author !== me;
}
maybeSyncInBackground(repo);
}
grouped(program.command("ask"), GROUP.find)
.description("Query the graft/ graph: returns ranked nodes + exact file:line, routed to prose or wiring ($0, no key)")
.argument("<query>", "what you want to understand, in plain words (- reads it from stdin)")
.argument(...DIR_ARG)
.option("-n, --limit <n>", "max results", "8")
.option("--source", "inline the source at each file:line hit (retriever mode: the pack IS the answer, no need to re-open files)")
.option("--full", "with --source: inline whole definition spans instead of the default ≤8-line crux excerpts")
.option("--in <path>", "narrow to nodes under this path prefix, filtered before scoring (segment-aware, like scopeOf)")
.option("--json", "output the result as JSON")
.option("--no-graph-rank", "rank by lexical relevance only, without the graph-connectivity re-rank (ablation/eval)")
.option(...NO_REFRESH_FLAG)
.action(async (query: string, dirArg: string | undefined, opts: { limit: string; source?: boolean; full?: boolean; in?: string; json?: boolean; refresh?: boolean; graphRank?: boolean }) => {
// The prompt hook passes what the person typed on stdin, out of sight of `ps`.
if (query === "-") query = readFileSync(0, "utf8").trim();
const dir = noteQuery(queryRoot(dirArg));
await refreshBefore(dir, opts);
const askGlobalDir = program.opts<GlobalOpts>().dir;
if (readWorkspace(dir, askGlobalDir)) {
runWorkspaceAsk(dir, askGlobalDir, query, {
limit: Number(opts.limit), source: opts.source, full: opts.full, in: opts.in, json: opts.json,
});
return;
}
const engine = engineFrom();
let r;
try {
r = engine.ask(dir, query, { limit: Number(opts.limit), source: opts.source, full: opts.full, in: opts.in, graphRank: opts.graphRank });
} catch (err) {
console.error(`✗ ${err instanceof Error ? err.message : String(err)}`);
process.exit(1);
return;
}
noteHit(r.hits.length > 0);
// Teammates' branches on the same files, and the learnings shown, counted as a use.
if (TRAIL) afterAsk(r, dir);
// How many notes reached the agent: the demand side of `trail note`.
if (r.notesChecked) queryNote.notes = String(Math.min(r.notes?.length ?? 0, 2));
if (opts.json) {
console.log(JSON.stringify(r, null, 2));
} else {
const { formatAsk } = await import("./ask/ask.js");
process.stdout.write(formatAsk(r));
printLines(cloudLines(dir, { command: "ask" }));
}
});
grouped(program.command("skeleton"), GROUP.find)
.description("Signatures-only view of one file from the wiring graph: the cheapest way to see a file's API surface")
.argument("<file>", "repo-relative path (or unique basename) of the file")
.argument(...DIR_ARG)
.option("--json", "output the result as JSON")
.option(...NO_REFRESH_FLAG)
.action(async (file: string, dirArg: string | undefined, opts: { json?: boolean; refresh?: boolean }) => {
const dir = noteQuery(queryRoot(dirArg));
await refreshBefore(dir, opts);
const { skeleton, formatSkeleton } = await import("./ask/ask.js");
const globalOpts = program.opts<{ dir?: string }>();
const r = skeleton(dir, file, { contextDir: globalOpts.dir });
if (opts.json) console.log(JSON.stringify(r, null, 2));
else process.stdout.write(formatSkeleton(r));
});
if (!TRAIL) {
program
.command("check")
.description("Fail if graft/ is stale relative to the code (for CI)")
.argument(...DIR_ARG)
.option("-e, --extensions <exts...>", "code extensions to include")
.option("--json", "output the drift as JSON")
.action(async (dirArg: string | undefined, opts: { extensions?: string[]; json?: boolean }) => {
await runCheckCommand(dirArg, opts, "graft check");
});
}
// Under trail, `check` is the team check (teamCheckCommand, with the cloud
// commands below); the freshness check is `trail build --check`.
/**
* The freshness check: `graft check`, and `trail build --check`. `label` is how
* the report names the command, so each name prints its own spelling.
*/
async function runCheckCommand(
dirArg: string | undefined,
opts: { extensions?: string[]; json?: boolean },
label: string,
): Promise<void> {
warnUnsupportedExtensions(opts.extensions);
const dir = noteQuery(queryRoot(dirArg));
const checkGlobalDir = program.opts<GlobalOpts>().dir;
if (readWorkspace(dir, checkGlobalDir)) {
await runWorkspaceCheck(dir, checkGlobalDir);
return;
}
const engine = engineFrom();
const r = engine.check(dir, { extensions: opts.extensions });
const g = await engine.checkGraph(dir); // graph.json is only judged when it exists
// A layer that IS present must be in sync; a never-built layer (keyless
// build skips the markdown layer) is informational, not a failure.
const bothMissing = r.missing && g.missing;
const markdownFail = !r.missing && !r.ok;
const wiringFail = !g.missing && !g.ok;
if (opts.json) {
console.log(JSON.stringify({ context: r, graph: g.missing ? null : g }, null, 2));
} else if (bothMissing) {
console.log(`${label}: NO GRAPH\n\nNo code map found. Run \`${cmd("graft build")}\` first.`);
} else {
if (r.missing) {
console.log(
`deep layer: not built (run \`${cmd("graft build --deep")}\` for concept nodes); the wiring graph is the source of truth`,
);
} else {
console.log(formatCheckReport(r, label));
}
if (!g.missing) console.log("\n" + formatGraphCheckReport(g));
}
if (bothMissing || markdownFail || wiringFail) process.exit(1);
}
// Under trail this is part of `status`; the old name still runs, unlisted.
program
.command("stats", { hidden: TRAIL })
.description(`Show this agent session's ${brand()}-vs-source usage mix and tokens saved`)
.argument(...DIR_ARG)
.option("--json", "output the session stats as JSON")
.action((dirArg: string | undefined, opts: { json?: boolean }) => {
// Reads local session JSON only — no graph, no network. This is how a Cursor
// user (no statusline) sees the numbers the Claude Code bar would show, and it
// works under DO_NOT_TRACK because it never touches telemetry.
const dir = queryRoot(dirArg);
const s = latestSession(dir);
if (opts.json) {
console.log(JSON.stringify(s, null, 2));
return;
}
console.log(formatSessionStats(s));
});
program
.command("viz", { hidden: TRAIL })
.description("Serve an interactive visualization of the context graph (and graph.json when present)")
.argument(...DIR_ARG)
.option("-p, --port <port>", "port to serve on", "4400")
.option("--no-open", "don't open the browser")
.option("--export <dir>", "write one self-contained index.html instead of serving (for CI, GitHub Pages, or a build artifact)")
.option("--title <text>", "subtitle shown beside the repo name in an exported page (e.g. \"PR #151\")")
.option("--tabs <list>", "tabs the exported page offers, comma separated: context,code,outline (default: all three)")
.action(async (dirArg: string | undefined, opts: { port: string; open: boolean; export?: string; title?: string; tabs?: string }) => {
// Flags are checked before the repository is: a typo'd `--tabs` is a mistake
// in the command the caller just typed, and telling them to go build an index
// first sends them off to fix the wrong thing.
const tabs = parseTabs(opts.tabs);
const dir = noteQuery(queryRoot(dirArg));
const { existsSync } = await import("node:fs");
const { resolve, basename } = await import("node:path");
const { spawn } = await import("node:child_process");
const { fileURLToPath } = await import("node:url");
const { contextDirFor } = await import("./context/node-file.js");
const { startVizServer } = await import("./viz/serve.js");
const root = resolve(dir);
const globalOpts = program.opts<{ dir?: string }>();
const contextDir = contextDirFor(root, globalOpts.dir);
if (!existsSync(contextDir)) {
console.error(`✗ no context graph at ${contextDir}: run \`${cmd("graft build --deep")}\` first`);
process.exit(1);
}
const viewerDir = fileURLToPath(new URL("./viewer/", import.meta.url)); // prebuilt
if (opts.export) {
const { exportViz } = await import("./viz/export.js");
const out = exportViz({
contextDir,
viewerDir,
outDir: resolve(opts.export),
repoName: basename(root),
subtitle: opts.title,
tabs,
});
const kb = Math.round(out.bytes / 1024);
console.log(
`${cmd("graft viz")} → ${out.file} (${kb} kB, ${out.contextNodes} concept nodes, ${out.codeNodes} code nodes)`,
);
return;
}
const srv = await startVizServer({
contextDir,
viewerDir,
port: Number(opts.port),
repoName: basename(root),
});
console.log(`${cmd("graft viz")} → ${srv.url} (ctrl-c to stop)`);
if (opts.open) {
const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
spawn(opener, [srv.url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
}
});
program
.command("mcp", { hidden: TRAIL })
.description("Serve the graph over MCP (stdio): exposes graft_find_code, graft_trace_calls, graft_find_all, graft_file_api, graft_repo_map and graft_check_freshness as tools")
.argument(...DIR_ARG)
.option("--brains", "serve only the connected Trail workspace's brain tools (what Claude Code gets after init --connect)")
.action(async (dirArg: string | undefined, opts: { brains?: boolean }) => {
const { startMcpServer } = await import("./mcp/server.js");
if (opts.brains) {
startMcpServer(process.cwd(), undefined, currentVersion, { brainsOnly: true });
return;
}
const dir = noteQuery(queryRoot(dirArg));
const globalOpts = program.opts<{ dir?: string }>();
startMcpServer(dir, globalOpts.dir, currentVersion);
});
grouped(program.command("callers"), GROUP.find)
.description(
"Who calls/references a symbol ($0, no LLM). --direction out gives callees (what it calls); --depth N (or all) walks transitively for full blast radius",
)
.argument("<symbol>", "bare name, qualified (Class.method), or package-qualified (pkg.Fn)")
.argument(...DIR_ARG)
.option("--direction <in|out>", 'edge direction: "in" = callers (default), "out" = callees')
.option("-d, --depth <n>", 'walk transitively up to N hops for blast radius, or "all" for the full connected closure (default 1)')
.option("--in <path>", "narrow matches to nodes at or under this path prefix")
.option("--json", "output as JSON")
.option(...NO_REFRESH_FLAG)
.action(
async (
symbol: string,
dirArg: string | undefined,
opts: { direction?: string; depth?: string; in?: string; json?: boolean; refresh?: boolean },
) => {
const dir = noteQuery(queryRoot(dirArg));
await refreshBefore(dir, opts);
const globalOpts = program.opts<{ dir?: string }>();
if (!opts.json && readWorkspace(dir, globalOpts.dir)) {
runWorkspaceCallers(dir, globalOpts.dir, symbol, {
direction: opts.direction === "out" ? "out" : "in",
depth: opts.depth
? (/^(all|full|max)$/i.test(opts.depth) ? Number.POSITIVE_INFINITY : Number(opts.depth))
: undefined,
in: opts.in,
});
return;
}
const { runCallersCommand } = await import("./graph/traverse-cli.js");
runCallersCommand(symbol, dir, {
direction: opts.direction,
depth: opts.depth,
in: opts.in,
json: opts.json,
globalDir: globalOpts.dir,
});
},
);
grouped(program.command("blast"), GROUP.ci)
.description(
"Blast radius of a diff: what depends on the lines this change touched ($0, no LLM). " +
"Built for CI: `--format markdown` is a PR comment with a Mermaid diagram.",
)
.argument(...DIR_ARG)
.option("--base <ref>", "diff against this ref's merge base with HEAD (e.g. origin/main); default: the working tree vs HEAD")
.option("-d, --depth <n>", 'hops to walk over incoming edges, or "all" for the full closure (default 2)')
.option("--format <fmt>", "text (default) | markdown | mermaid | json")
.option("--name", "name the affected areas with one cached LLM call (needs GRAFT_API_KEY); without it, areas are named after their hub symbol")
.option("--export-viz <dir>", "also write the interactive page for this radius (one self-contained index.html, for CI, GitHub Pages, or an artifact)")
.option("--title <text>", "subtitle beside the repo name on the exported page (e.g. \"PR #171\")")
.option("--no-owners", "do not suggest who to tag (by default, git history names the people behind each affected area)")
.option("--pr-author <who...>", "GitHub login, git name or email of the PR author, so they are left out of their own suggestions")
.option(...NO_REFRESH_FLAG)
.action(async (dirArg: string | undefined, opts: { base?: string; depth?: string; format?: string; name?: boolean; exportViz?: string; title?: string; owners?: boolean; prAuthor?: string[]; refresh?: boolean }) => {
const dir = noteQuery(queryRoot(dirArg));
await refreshBefore(dir, opts);
const { runBlastCommand } = await import("./blast/blast-cli.js");
await runBlastCommand(dir, {
base: opts.base,
depth: opts.depth,
format: opts.format,
name: opts.name,
exportViz: opts.exportViz,
title: opts.title,
owners: opts.owners,
prAuthor: opts.prAuthor,
globalDir: program.opts<GlobalOpts>().dir,
});
});
grouped(program.command("grep"), GROUP.find)
.description("Regex search over indexed files, hits grouped by enclosing symbol and ranked by coupling ($0, no LLM)")
.argument("<pattern>", "regex pattern (or literal string with --fixed)")
.argument(...DIR_ARG)
.option("-i, --ignore-case", "case-insensitive match")
.option("--fixed", "treat pattern as a literal string, not a regex")
.option("--in <path>", "narrow to files at or under this path prefix")
.option("--json", "output as JSON")
.option(...NO_REFRESH_FLAG)
.action(
async (
pattern: string,
dirArg: string | undefined,
opts: { ignoreCase?: boolean; fixed?: boolean; in?: string; json?: boolean; refresh?: boolean },
) => {
const dir = noteQuery(queryRoot(dirArg));
await refreshBefore(dir, opts);
const globalOpts = program.opts<{ dir?: string }>();
if (readWorkspace(dir, globalOpts.dir)) {
runWorkspaceGrep(dir, globalOpts.dir, pattern, {
ignoreCase: opts.ignoreCase, fixed: opts.fixed, json: opts.json,
});
return;
}
const { runGrepCommand } = await import("./search/grep-cli.js");
runGrepCommand(pattern, dir, {
ignoreCase: opts.ignoreCase,
fixed: opts.fixed,
in: opts.in,
json: opts.json,
globalDir: globalOpts.dir,
});
},
);
grouped(program.command("map"), GROUP.find)
.description(
"Token-budgeted repo orientation: directory clusters, per-directory hubs, and global hotspots from the wiring graph ($0, no LLM)",
)
.argument(...DIR_ARG)
.option("--max-dirs <n>", "max directory entries shown, rest counted into dropped (default 16)")
.option("--json", "output as JSON")
.option(...NO_REFRESH_FLAG)
.action(async (dirArg: string | undefined, opts: { json?: boolean; maxDirs?: string; refresh?: boolean }) => {
const dir = noteQuery(queryRoot(dirArg));
const root = resolve(dir);
const globalOpts = program.opts<{ dir?: string }>();
let maxDirsW: number | undefined;
if (opts.maxDirs !== undefined) {
const n = parseInt(opts.maxDirs, 10);
if (!Number.isFinite(n) || n <= 0) {
console.error(`✗ --max-dirs must be a positive integer, got "${opts.maxDirs}"`);
process.exit(1);
return;
}
maxDirsW = n;
}
await refreshBefore(dir, opts); // after arg validation: a bad flag shouldn't cost a rebuild
if (!opts.json && readWorkspace(root, globalOpts.dir)) {
runWorkspaceMap(root, globalOpts.dir, { maxDirs: maxDirsW });
return;
}
const { buildRepoMap, formatRepoMap } = await import("./graph/map.js");
const contextDir = contextDirFor(root, globalOpts.dir);
const graph = loadGraphCached(contextDir);
if (!graph) {
console.error(`✗ no graph: run ${cmd("graft build")} first`);
process.exit(1);
return;
}
const map = buildRepoMap(graph, { maxDirs: maxDirsW });
if (opts.json) {
console.log(JSON.stringify(map, null, 2));
return;
}
process.stdout.write(formatRepoMap(map));
});
// `trail note`: what a session worked out, saved for the next person. Listed
// under trail; under graft it still runs, unlisted, for a teammate on graft in
// a repo where someone else set up trail.
grouped(program.command("note", { hidden: !TRAIL }), GROUP.memory)
.description("Save what this session decided, tried and ruled out, as a learning in the repo's .trail/learnings/ (the text on stdin)")
.requiredOption("--title <text>", "what the session was about, in a few words")
.option("-m, --body <text>", "the learning itself, instead of stdin")
.option("--personal", "about your own setup or habits, not the code: keep it in ~/.trail, out of the repo")
.option("--touches <list>", "comma-separated files or file#Symbol it's about (default: the files this session changed, in every repo it changed)")
.option("--author <name>", "who wrote it (default: the first word of git config user.name)")
.option("--minutes <n>", "what it took to work out, when the agent's transcript can't say")
.option("--tokens <n>", "the same, in tokens")
.option("--replaces <file>", "an earlier learning this one takes over from (its file name in .trail/learnings/); the old file stays")
.option("--anyway", "save it even if trail's checks (names code, says why, not status, not a repeat) turn it away")
.option("--json", "print the saved learning as JSON")
.argument("[dir]", "repository root", ".")
.action(async (dir: string, opts: NoteOptions) => {
await runNoteCommand(resolve(dir), opts);
});
// `trail skills` (design 1.7): the skills Trail kept for you, held ones to keep, offers and the switch; and
// `trail forget <name>`, the undo every save line names. The person-only ones refuse an agent (cli-skills.ts).
registerSkillCommands(program);
for (const c of program.commands) if (c.name() === "skills") grouped(c, GROUP.memory);
grouped(program.command("init"), GROUP.setup)
.description(
TRAIL
? "Wire trail into your agents: instruction files and MCP for each, plus hooks and a statusline for Claude Code"
: "Wire Graft into the AI coding agents used with this repo (instruction files + MCP server; full hooks + statusline + MCP for Claude Code)",
)
.argument("[dir]", "target repo directory", ".")
.option("--no-build", "skip building the graph (wire files only)")
.option("--agents <ids...>", `only these agents (${hostIds().join(", ")}, claude)`)
.option("--all-agents", "write instruction files for every known agent, detected or not")
.option("--no-agents", "Claude Code wiring only; skip other agents")
.option("--list-agents", "list known agent ids and exit")
.option("--no-mcp", "skip MCP server registration for other agents")
.option("--no-hooks", "skip hook installation for other agents")
.option("--no-statusline", "skip writing Claude Code statusLine (keep a user-defined one)")
.option("--dry-run", "print every file init would touch, then exit without writing")
.option("-y, --yes", "skip the picker and wire every detected agent (the pre-0.8 default)")
.option("--no-global", "skip writes outside this repo (the ~/.codex/ config + hooks)")
.option("--verbose", "print every file written, the graph build's own output and the closing banner")
.option(
"--connect <code>",
"connect this machine to your Trail workspace with the one-time code from team.trailhq.com, and send it a summary of this repo (titles, counts and names; never code)",
)
.option("--pair <code>", "the pair code from Trail's onboarding page: that page shows this run live, then you review what it found")
.option("--server <url>", "the Trail that gave the code (default: Trail cloud, https://team.trailhq.com)")
.option("--plain", "look back without asking Claude to name what it finds")
.option("--look-back", "look back at your past sessions again, for what isn't kept or closed yet")
.action(async (dir: string, opts: InitOptions) => {
if (opts.connect !== undefined && opts.pair !== undefined) {
console.error("✗ --connect and --pair are two ways in: use the one your Trail page gave you");
process.exitCode = 1;
return;
}
if (opts.connect !== undefined) await runConnectInit(dir, opts);
else await runInitCommand(dir, opts);
});
// `trail init` prints this when there was no terminal to ask on (an agent ran
// it) or with --yes: the person picks what to keep from what the look-back
// found. An agent may run it only after the person answered (pre-bash checks).
program
.command("keep", { hidden: true })
.description("keep learnings `trail init` found: trail keep 1 3, or trail keep none")
.argument("<numbers...>", "the numbers from the list init printed, or none")
.action((numbers: string[]) => {
// The CLI half of the keep check (src/init/keep.ts): it needs the receipt the PreToolUse half wrote.
const r = keepCommand(numbers, process.env);
for (const line of r.lines) console.error(line);
if (r.code) process.exitCode = r.code;
});
/** Everything on stdin, or "" when nothing is piped in. */
async function readStdin(): Promise<string> {
if (process.stdin.isTTY) return "";
const chunks: Buffer[] = [];
for await (const c of process.stdin) chunks.push(typeof c === "string" ? Buffer.from(c) : c);
return Buffer.concat(chunks).toString("utf8");
}
interface NoteOptions {
title: string;
body?: string;
touches?: string;
author?: string;
minutes?: string;
tokens?: string;
json?: boolean;
personal?: boolean;
replaces?: string;
anyway?: boolean;
}
async function runNoteCommand(repo: string, opts: NoteOptions): Promise<void> {
const body = (opts.body ?? (await readStdin())).trim();
if (!opts.title.trim() || !body) {
console.error(`✗ a learning needs a --title and a body, on stdin or with -m:`);
console.error(` ${cmd("graft note")} --title "What it was about" <<'EOF'`);
console.error(" ## Decided\n …\n ## Tried and ruled out\n …\n ## Watch out\n …\n EOF");
process.exitCode = 1;
return;
}
const wholeNumber = (raw: string | undefined, flag: string): number | undefined => {
if (raw === undefined) return undefined;
const n = Number(raw);
if (!Number.isFinite(n) || n < 0) {
console.error(`✗ ${flag} takes a number, got "${raw}"`);
process.exit(1);
}
return Math.round(n);
};
const minutes = wholeNumber(opts.minutes, "--minutes");
const tokens = wholeNumber(opts.tokens, "--tokens");
// What the session spent, from the agent's own transcript when there is one,
// counted from where the work the note names first came up; the flags win,
// since only the agent knows for sure where its task began.
const named = [...(opts.touches?.split(",").map((t) => t.trim()).filter(Boolean) ?? []), ...mentionedFiles(repo, body)];
const spent = currentSessionCost(repo, undefined, Date.now(), aboutTerms(body, named));
const cost =
minutes !== undefined || tokens !== undefined || spent
? { minutes: minutes ?? spent?.minutes, tokens: tokens ?? spent?.tokens }
: undefined;
// Which repos it goes to: the one it was saved from, plus any other the
// session edited. Explicit --touches means just this repo.
const targets = opts.touches
? [{ dir: repo, touches: opts.touches.split(",").map((t) => t.trim()).filter(Boolean) }]
: noteTargets(repo, spent?.edited ?? [], spent?.startedAt, spent ? { read: spent.read } : undefined).map((t) => ({
dir: t.dir,
// Then the files the note names, then the ones the session only read.
touches: [...new Set([...t.touches, ...mentionedFiles(t.dir, body), ...(t.read ?? [])])].slice(0, 10),
}));
// A touch is a file git tracks or one this session edited: never a file
// that was just lying around (a token, a scratch file).
const real = (dir: string, files: string[]): string[] => {
const tracked = trackedFiles(dir, files.map((f) => f.split("#")[0]!));
const edited = new Set((spent?.edited ?? []).map((f) => relative(dir, f).split("\\").join("/")));
return files.filter((f) => tracked.has(f.split("#")[0]!) || edited.has(f.split("#")[0]!));
};
for (const t of targets) t.touches = real(t.dir, t.touches);
const scope = opts.personal ? "personal" : "repo";
const primary = targets[0]!;
const existing = listNotes(primary.dir, { branches: false });
let old: Note | undefined;
if (opts.replaces) {
const want = basename(opts.replaces.trim());
old = findLearning(existing, want);
if (!old) {
console.error(`✗ --replaces: no learning named ${want} here. The names are the files in .trail/learnings/.`);
process.exitCode = 1;
return;
}
}
// What `replaces:` holds is the old learning's id (learning-fields.ts), not its file name.
const replaces = old?.id;
const text = `${opts.title}\n${body}`;
const gate = gateNote(
{
title: opts.title,
body,
personal: scope === "personal",
files: real(primary.dir, [...new Set([...mentionedFiles(primary.dir, text), ...(opts.touches ? primary.touches : [])])]),
namesSymbol: namesRepoSymbol(primary.dir, symbolCandidates(text)),
touches: primary.touches,
replaces,
},
liveLearnings(existing).filter((n) => (n.scope ?? "repo") === scope),
);
if (gate.problems.length && !opts.anyway) {
console.error("✗ not saved yet:");
for (const p of gate.problems) console.error(` · ${p}`);
console.error(`Fix it and run ${cmd("graft note")} again, or add --anyway if a check is wrong.`);
process.exitCode = 1;
return;
}
const author = opts.author?.trim() || noteAuthor(repo);
const date = new Date().toISOString().slice(0, 10);
// Saved by `trail note`, which is how an agent saves: src says so, and no flag changes it.
const earlier: Note[] = [];
const saved: Note[] = [];
for (const t of targets) {
earlier.push(...listNotes(t.dir));
saved.push(writeNote(t.dir, { title: opts.title, body, author, date, branch: currentBranch(t.dir), cost, touches: t.touches, replaces, src: "agent" }, scope));
}
const touches = targets.flatMap((t) => t.touches);
track(
"note_saved",
{ has_cost: String(cost?.tokens !== undefined || cost?.minutes !== undefined), touches_bucket: countBucket(touches.length), scope: saved[0]?.scope ?? scope },
{ repo },
);
if (opts.json) {
console.log(JSON.stringify(saved.length === 1 ? saved[0] : saved, null, 2));
return;
}
for (const n of saved) console.log(`✓ ${n.scope === "personal" ? "saved just for you" : "added to this repo"} · ${notePlace(n)}`);
console.log(savedIdLine(saved));
const note = saved[0]!;
// Name a code file if the note touches one; docs are rarely what it's about.
const about = touches.find((t) => !/\.(md|mdx|txt)$/i.test(t.split("#")[0]!)) ?? touches[0];
const first = about ? ` that touches ${basename(about.split("#")[0]!)}` : "";
const took = costLabel(note.cost);
if (took && tokensWorthSaying(note.cost?.tokens)) {
const reading = tokensLabel(readingTokens(note)).replace(" tokens", "");
console.log(`· this ${took.replace(" to work out", " to figure out")}. the next session${first} gets it for ${reading}`);
} else if (note.scope !== "personal") {
console.log(`· the next session${first} starts from this, and gets to a PR ${PR_SPEEDUP}`);
}
// Learnings about the same files, from someone else: this one builds on theirs.
const files = new Set(touches.map((t) => t.split("#")[0]));
const prior = liveLearnings(earlier).find((n) => n !== old && n.author !== note.author && n.touches.some((t) => files.has(t.split("#")[0])));
if (prior) console.log(`· builds on ${prior.author ? `${prior.author}'s` : "a"} learning from ${shortDate(prior.date)}`);
if (!SECTIONS.some((s) => sectionLead(body, s.heading) !== null))
console.log("· tip: learnings read best under ## Decided, ## Tried and ruled out and ## Watch out");
for (const w of gate.warnings) console.log(`· ${w}`);
if (old) console.log(`· takes over from ${noteName(old)}, which stays as the record`);
const repoSaved = saved.filter((n) => n.scope === "repo");
if (repoSaved.length) {
// Who else works on these files, for the case for committing it.
const lines = commitLines(note, teammatesOn(repo, [...files].filter((f): f is string => !!f)));
console.log(`${lines.uncommitted} · git add ${repoSaved.map(notePlace).join(" ")}`);
if (!process.stdout.isTTY && TRAIL)
console.log(
`[trail] Close your reply with one line, word for word. If this learning is committed by the end of your turn: ${lines.committed}\n` +
` If it isn't: ${commitAsk(note.title, about)}\n` +
" On a yes, commit it with the change: in the change's own commit when that isn't pushed yet.",
);
} else {
console.log("· just for you: kept on this machine, out of the repo");
if (!process.stdout.isTTY && TRAIL) console.log(`[trail] Close your reply with this line, word for word: ${PERSONAL_SAVED_LINE}`);
}
for (const t of targets) {
rememberRepo(t.dir);
maybeSyncInBackground(t.dir);
}
printLines(cloudLines(repo, { command: "note" }));
}
/** What the agent asks after saving a team learning it hasn't committed: who reads it, and when. */
export function commitAsk(title: string, about?: string): string {
const when = about ? `when they open ${basename(about.split("#")[0]!)}` : "on their next session here";
return `📝 Learning: "${title.replace(/"/g, "'")}" · your teammates' Claude reads it ${when}. Commit it with this change? (y/n)`;
}
/** Lines that close a command's output, with a blank line before them. */
function printLines(lines: string[]): void {
if (lines.length) console.log(`\n${lines.join("\n")}`);
}
/** `graft init`'s flags, as commander hands them over. */
interface InitOptions { build?: boolean; agents?: string[]; allAgents?: boolean; listAgents?: boolean; mcp?: boolean; hooks?: boolean; statusline?: boolean; dryRun?: boolean; yes?: boolean; global?: boolean; verbose?: boolean; connect?: string; pair?: string; server?: string; plain?: boolean; lookBack?: boolean }
/** What `init --connect` and `--pair` hear from a run of init, as it happens: the stages the web page ticks off. */
interface InitProgress {
mapped?(m: { nodes: number; edges: number; files: number }): void;
/** What init learned this run (team and personal), and how many past sessions it read; `notes` is empty when it learned nothing new. */
learned?(l: { notes: Array<{ note: Note; sessions?: number }>; sessions: number }): void;
}
/**
* `--server <url>` on `init --connect` and `--pair`: the Trail that gave the
* code, for the rest of this run (`useServer`, never the environment). False,
* after saying why, when it isn't a URL.
*/
function useServerOption(raw: string | undefined): boolean {
if (raw === undefined || !raw.trim()) return true;
const server = serverUrl(raw);
if (!server) {
console.error("✗ --server takes a URL, like https://dev.trailhq.com");
process.exitCode = 1;
return false;
}
useServer(server);
return true;
}
/**
* What `init --pair` hears from init, as the onboarding page's steps: the map
* is done when `mapped` fires, the past sessions when `learned` does. Nothing
* to say for a run that read no sessions (that step is already marked).
*/
function pairProgress(pair: PairRun): InitProgress {
return {
mapped: (m) => pair.phase("files", "done", m.files ? `${m.files.toLocaleString("en-US")} files` : "", m.files ? `Mapped ${m.files.toLocaleString("en-US")} files` : "Mapped the code"),
learned: (l) => {
if (l.sessions <= 0) return;
pair.phase("decisions", "done", `${l.sessions} sessions`, `Read ${l.sessions} past Claude sessions`);
},
};
}
/** Repo-relative with forward slashes, for printing. */
function shown(repo: string, path: string): string {
return relative(repo, path).split("\\").join("/");
}
/** Agents init knows by another id: both read AGENTS.md. */
const AGENT_ALIASES: Record<string, string> = { codex: "agents", opencode: "agents" };
/** `graft init`. */
async function runInitCommand(dir: string, opts: InitOptions, progress?: InitProgress): Promise<{ ids: string[] } | null> {
if (opts.listAgents) {
for (const id of [...hostIds(), "claude"]) console.log(id);
return null;
}
const repo = resolve(dir);
// Codex and OpenCode read AGENTS.md: `--agents codex` means that wiring.
// The name as given is kept for Trail's onboarding page.
const asked = Array.isArray(opts.agents) ? opts.agents : undefined;
const explicit = asked ? [...new Set(asked.map((id) => AGENT_ALIASES[id] ?? id))] : undefined;
// Checked before anything is written: run from the home folder, init wired
// it, mapped every code file under it, then said to commit.
const refusal = homeFolderRefusal(repo);
if (refusal) {
console.error(refusal);
process.exitCode = 1;
return null;
}
if (explicit) {
const validIds = [...hostIds(), "claude"];
const unknown = explicit.filter((id) => !validIds.includes(id));
if (unknown.length) {
console.error(`✗ unknown agent id(s): ${unknown.join(", ")}; valid: ${validIds.join(", ")}`);
process.exit(1);
}
}
// Which agents to wire, decided before anything is written. Explicit flags
// win; otherwise prompt on a TTY, and on a pipe write nothing rather than
// guessing (pre-0.8 this silently wired every agent the machine had ever
// installed — see --yes to get that back).
const home = homedir();
const plan = planInit(repo, { home });
const detectedIds = plan.filter((p) => p.detected).map((p) => p.id);
const noAgents = (opts as { agents?: unknown }).agents === false;
let ids: string[];
// The consent answer from the picker. Undefined everywhere else — a scripted
// or flag-driven init never asked, so it must not silently answer.
let consent: boolean | undefined;
if (explicit) ids = explicit;
else if (opts.allAgents) ids = plan.map((p) => p.id);
else if (noAgents) ids = ["claude"];
else if (opts.yes || opts.dryRun) ids = detectedIds;
else if (process.stdin.isTTY && process.stderr.isTTY) {
// Only offer the row when telemetry could actually run. `disabled` still
// counts: someone who turned it off should be able to turn it back on here.
const reason = offReason();
const picked = await runPicker(plan, repo, home, {
offerTelemetry: reason === null || reason === "disabled",
});
if (picked === null) {
console.error("· cancelled, nothing written");
return null;
}
ids = picked.hosts;
consent = picked.telemetry;
} else {
console.error(formatNonInteractiveHelp(detectedIds));
return null;
}
// The picker's answer, recorded before anything is wired: a user who
// unchecked the row must not have this run's init_completed sent.
if (consent !== undefined) {
patchState({ enabled: consent, noticeShownAt: new Date().toISOString() });
}
// Workspace parent: every child repo gets its OWN wiring too. A session
// opens at a repo root, not at the parent, and reads `.claude/` from there —
// wiring only the parent leaves each child with no skill, hooks, or MCP.
// The parent's own wiring stays (queries there federate across children).
const children = isWorkspaceBuildRoot(repo, program.opts<GlobalOpts>().dir)
? discoverWorkspaceChildren(repo)
: [];
// Parent FIRST: its build is the workspace build, which builds every child's
// graph, so each child's own `buildGraphIfMissing` then finds one and no-ops.
const targets = [repo, ...children.map((c) => join(repo, c))];
if (opts.dryRun) {
console.error(formatPlan(plan, ids, repo, home));
for (const child of children)
console.error(`\n· ${child}/ (workspace child)\n` + formatPlan(planInit(join(repo, child), { home }), ids, join(repo, child), home));
return null;
}
if (ids.length === 0) {
console.error("· no agents selected, nothing written");
return null;
}
// With --pair, Trail's onboarding page is waiting on this run: tell it
// first, so the person can sign up while the rest of init runs.
let pair: PairRun | null = null;
if (opts.pair !== undefined) {
if (!useServerOption(opts.server)) return null;
if (!validPairCode(opts.pair)) {
console.error(`✗ --pair takes the code from Trail's onboarding page, got "${opts.pair}"`);
process.exitCode = 1;
return null;
}
const started = await PairRun.start(repo, opts.pair, { agent: asked?.[0] ?? ids[0]!, version: currentVersion });
if ("error" in started) {
console.error(`⚠ couldn't tell Trail about this run (${started.error}); setting up here anyway`);
} else {
pair = started;
console.error(`· Trail's page is following along · ${started.url}`);
}
}
const wantClaude = ids.includes("claude");
const cliPath = fileURLToPath(import.meta.url);
// D120 (2): what each checkout holds before init writes, so its install record names only init's own changes.
const installSnaps = TRAIL ? snapInit(targets, home) : [];
// Under trail, each repo gets its `.trail/learnings/`, committed with the
// code, and its folder in ~/.trail for personal learnings and corrections.
// Before the look-back below sends its first event: that makes the repo one
// on trail, so the event's repo id lands in `.trail/cache/` and not in a
// `graft/` that nothing ignores.
const notesHome = new Map<string, { created: boolean; dir: string }>();
if (TRAIL)
for (const target of targets) {
const { place } = ensureRepoHome(target);
const created = place.git ? ensureRepoTrail(place.checkout) : false;
notesHome.set(target, { created, dir: place.git ? place.checkout : place.dir });
if (place.git) maybeRefreshBranches(place.checkout);
}
// Under trail, with Claude Code picked: look back at this repo's past
// sessions and PR reviews while the rest of init runs, and offer what came
// up at the end. Nothing is kept without a tick (see src/init/review.ts).
const tty = Boolean(process.stdin.isTTY && process.stderr.isTTY);
const lookBack = TRAIL && wantClaude ? beginLookBack(repo, { plain: opts.plain === true, again: opts.lookBack === true }) : null;
for (const line of lookBack?.lines ?? []) console.error(line);
if (pair) {
if (lookBack?.reads.lb) pair.phase("decisions", "running", "", "Reading past Claude sessions");
else pair.phase("decisions", "done", "none here");
if (lookBack?.reads.reviews) pair.phase("prs", "running", "", "Reading review comments on merged PRs");
else pair.phase("prs", "done", "none here");
}
if (children.length)
console.error(`· workspace: wiring ${repo} and ${children.length} child repo(s): ${children.join(", ")}`);
// Today's output, file by file, behind --verbose. Everything else gets one
// line per step: the graph, then one per agent.
const verbose = opts.verbose === true;
const reports: WireReport[] = [];
for (const target of targets) {
if (verbose && target !== repo) console.error(`\n· ${relative(repo, target)}/`);
reports.push(wireTarget(target, ids, { home, cliPath, plan, opts, wantClaude, quiet: !verbose }));
}
// The graph, built once after the wiring: a workspace parent's build is
// the workspace build, so it covers every child.
let graphLine: string | null = null;
if (!verbose) {
pair?.phase("files", "running", "", "Mapping the code");
const res = await buildGraphWithProgress(repo, { build: opts.build, cliPath });
for (const m of res.messages) console.error(m);
const existing = res.built ? null : loadGraphCached(contextDirFor(repo, children.length ? undefined : program.opts<GlobalOpts>().dir));
const fmt = (x: number) => x.toLocaleString("en-US");
if (res.graph) {
graphLine = `✓ graph built · ${fmt(res.graph.nodes)} nodes, ${fmt(res.graph.edges)} edges${res.graph.files ? ` from ${fmt(res.graph.files)} file${res.graph.files === 1 ? "" : "s"}` : ""}`;
} else if (res.built) {
graphLine = "✓ graph built";
} else if (res.failed) {
graphLine = `⚠ the graph build failed: run ${cmd("graft build")} to see why`;
} else if (existing) {
graphLine = `✓ graph ready · ${fmt(existing.meta.nodeCount)} nodes, ${fmt(existing.meta.edgeCount)} edges`;
} else if (hasGraftIndex(repo)) {
graphLine = "✓ graph ready";
} else {
graphLine = `· skipped the graph build: run ${cmd("graft build")}`;
}
}
// After the graph build too: it adds the map's ignore lines (`.trail/.gitignore` under trail, `.gitignore` and `.ignore`
// under graft), and those are init's writes.
recordInit(installSnaps);
// --pair hears the same stages --connect does; only the ones InitProgress
// has no slot for (a read starting, the PR read, nothing to read) stay inline.
const report: InitProgress | undefined = pair ? pairProgress(pair) : progress;
if (report?.mapped) {
const g = loadGraphCached(contextDirFor(repo, children.length ? undefined : program.opts<GlobalOpts>().dir));
report.mapped({
nodes: g?.meta.nodeCount ?? 0,
edges: g?.meta.edgeCount ?? 0,
files: g ? g.nodes.filter((n) => n.kind === "file").length : 0,
});
}
// With --pair, one lookup measured against reading the files whole: the
// page's token step. It needs the map, so it follows the build.
let tokens: ReturnType<typeof tokensOnOneLookup> = null;
if (pair) {
pair.phase("tokens", "running", "", "Measuring one lookup against reading the files");
tokens = tokensOnOneLookup(repo, { contextDir: program.opts<GlobalOpts>().dir });
pair.tokensDone(tokens);
}
if (!verbose) {
// Warnings and removals in full, whatever else is folded.
const removed = [...new Set(reports.flatMap((r) => r.retracted))];
for (const id of removed) console.error(`- removed ${id} (agent not selected)`);
for (const w of reports.flatMap((r) => r.warnings)) console.error(w);
const writesFor = (id: string) =>
(plan.find((p) => p.id === id)?.writes ?? []).filter((w) => opts.global !== false || w.scope !== "global");
if (graphLine) console.error(graphLine);
const width = Math.max(...ids.map((id) => id.length));
for (const id of ids) {
const summary = compactWrites(writesFor(id), repo, home);
console.error(`✓ ${id.padEnd(width)} ${summary}`.trimEnd());
}
}
// Under trail: what the look-back found, and #662's team rows (what
// reviewers kept flagging on merged PRs, and Claude Code's notes about the
// repo on this machine), what the person kept, where this repo's learnings
// are, and how many there already are.
let learnedNow = false;
let teamSaved = 0;
// What the look-back read, for the --pair and --connect pages, and the skills it found (--pair names them).
let sessionsRead = 0;
let skillsFound: FoundSkill[] = [];
if (lookBack) {
// With --pair the person reviews what was found on Trail's page, so no screen here, as with no terminal.
const screen = tty && !pair;
const learned = await finishLookBack(repo, lookBack.reads, { yes: opts.yes === true, verbose: opts.verbose === true, say: (l) => console.error(l), ...(screen ? { io: { stdin: process.stdin, stdout: process.stderr } } : {}) });
// #662's lines for the team rows it kept with no screen, in its words.
const { fromReviews, fromMemory } = learned.teamKept ?? { fromReviews: null, fromMemory: null };
if (fromReviews?.saved.length) {
const n = fromReviews.saved.length;
const what = n < fromReviews.offered ? `kept ${n} of the ${fromReviews.offered} things` : `learned ${n} thing${n === 1 ? "" : "s"}`;
console.error(`✓ ${what} reviewers made authors change, from the last ${fromReviews.result.prs} merged PRs here`);
// saveReviewFindings keeps the findings' order.
fromReviews.saved.forEach((note, i) => console.error(` for your team · from review on ${(fromReviews.kept[i]?.prs ?? []).map((n) => `#${n}`).join(", ")}: ${note.title}`));
}
if (fromMemory?.saved.length) {
console.error(`✓ kept ${fromMemory.saved.length} of the ${fromMemory.offered} notes your Claude keeps about this repo`);
for (const note of fromMemory.saved) console.error(` ${note.scope === "personal" ? "just for you " : "for your team"} · ${note.title}`);
}
sessionsRead = learned.read?.sessions ?? 0;
skillsFound = learned.skills ?? [];
const prs = learned.read?.prs;
if (pair && prs !== undefined && prs !== null) {
const n = fromReviews?.saved.length ?? 0;
pair.phase("prs", "done", `${prs} PRs`, `Read ${prs} merged PRs: ${n} thing${n === 1 ? "" : "s"} reviewers made authors change`);
}
// The team learnings kept with no screen, said in no past session; after a screen the page lists the repo's own.
const notes = [...(fromReviews?.saved ?? []), ...(fromMemory?.saved ?? [])].map((note) => ({ note, sessions: 0 }));
report?.learned?.({ notes, sessions: sessionsRead });
learnedNow = learned.kept > 0;
teamSaved = learned.team;
if (learnedNow) {
console.error("· Claude follows them from your next session");
if (learned.inRepo) console.error(commitLines({}, teammatesOn(repo), "repo").uncommitted);
}
}
// Not looked back (not trail, or not Claude Code): the page still gets its stage.
if (!lookBack) report?.learned?.({ notes: [], sessions: 0 });
if (TRAIL && !learnedNow) {
const home = notesHome.get(repo);
if (home) {
const learnings = liveLearnings(listNotes(repo, { branches: false })).filter((n) => n.scope === "repo");
if (learnings.length === 0) console.error(`✓ learnings ${LEARNINGS_DIR}/ · a session that fixes a bug, takes a correction or opens a PR leaves one there, for your whole team`);
else console.error(`✓ learnings ${learnings.length} in ${LEARNINGS_DIR}/, from ${new Set(learnings.map((n) => n.author || "someone")).size} ${new Set(learnings.map((n) => n.author)).size === 1 ? "person" : "people"}`);
}
}
if (!verbose) {
// What there is to commit: the top-level entries the picked agents wrote.
const tops: string[] = [];
for (const w of selectedWrites(plan, ids)) {
if (w.scope !== "repo") continue;
const rel = shown(repo, w.path);
// trail's Claude Code setup shares one file in .claude/; the rest there is personal.
if (TRAIL && rel.startsWith(".claude/") && rel !== ".claude/settings.json") continue;
const parts = rel.split("/");
const top = TRAIL && rel === ".claude/settings.json" ? rel : parts.length > 1 ? `${parts[0]}/` : parts[0]!;
if (!tops.includes(top)) tops.push(top);
}
console.error(`· restart your agents so a new session picks up ${brand()}`);
if (TRAIL && !tops.includes(".trail/")) tops.push(".trail/");
// Only what git sees as new or changed: a teammate's init over committed files has nothing to commit.
const changedTops = tops.filter((t) => {
const r = spawnSync("git", ["status", "--porcelain", "--", t], { cwd: repo, encoding: "utf8" });
return r.status !== 0 || r.stdout.trim().length > 0;
});
tops.splice(0, tops.length, ...changedTops);
// Outside git there is nothing to commit to, and `git status` failing above
// made every path look changed.
if (TRAIL && !children.length && !isGitWorkTree(repo)) console.error(NOT_GIT_LINE);
else if (tops.length)
console.error(
TRAIL
? `· commit ${tops.slice(0, 5).join(" and ")}${tops.length > 5 ? ` +${tops.length - 5} more` : ""} once: after that, teammates' Claude reads your learnings even before they install trail`
: `· commit ${tops.slice(0, 5).join(" ")}${tops.length > 5 ? ` +${tops.length - 5} more` : ""} to share it: graft/ stays local and git-ignored`,
);
}
// One epilogue for the whole run. A workspace parent holds no nodes of its
// own, so the totals come from the children — the graph the user actually got.
const globalDir = program.opts<GlobalOpts>().dir;
const graphs = (children.length ? children.map((c) => join(repo, c)) : [repo])
.map((d) => loadGraphCached(contextDirFor(d, children.length ? undefined : globalDir)))
.filter((g): g is NonNullable<typeof g> => g !== null);
if (verbose) console.error(
"\n" +
formatInitEpilogue({
graphBuilt: graphs.length > 0,
nodes: graphs.reduce((n, g) => n + g.meta.nodeCount, 0),
edges: graphs.reduce((n, g) => n + g.meta.edgeCount, 0),
}),
);
// Hand what was found to the review page, and leave a child waiting for
// the person to connect and review there.
if (pair) {
// Teammates' branches on this person's files, checked against the
// learnings just saved and the repo's own: synchronous, so the finding
// exists before the page is told the read is done.
pair.phase("team", "running", "", "Checking your team's branches");
const teamNotes = listNotes(repo, { branches: false }).filter((n) => n.scope === "repo" && !n.ref);
// No remote (or no default branch) means nothing was checked: `teammates`
// is left out, since an empty list would say "checked, none".
const teammates = teammatesChecked(repo, { learnings: teamNotes });
pair.teamDone(teammates);
pair.findings({ tokens, sessions: lookBack?.reads.lb ? sessionsRead : undefined, teammates });
await pair.finish(repo, skillsFound);
pair.handOff(repo);
console.error(`✓ Trail has what it found · review it in the browser: ${pair.url}`);
if (!process.stdout.isTTY) console.error(`[trail] Tell the user, in one line: their Trail page has moved on; review what Trail found there. If it isn't open, the link is ${pair.url}`);
}
// Run by an agent, not a person: the last line tells it to ask about the
// commit, since the person never saw the picker and Claude Code folds the rest.
// With --pair the person reviews them on the Trail page first, so no ask here.
if (teamSaved && !pair && !process.stderr.isTTY)
console.error(
`→ ${teamSaved} team learning${teamSaved === 1 ? "" : "s"} in ${LEARNINGS_DIR}/ ${teamSaved === 1 ? "isn't" : "aren't"} committed yet. Ask the user: "Commit ${teamSaved === 1 ? "it" : `the ${teamSaved}`} so your teammates' Claude starts from ${teamSaved === 1 ? "it" : "them"}? (yes / no)"`,
);
// Sorted so `claude,cursor` and `cursor,claude` aggregate as one value.
track(
"init_completed",
{ agents: [...ids].sort().join(","), consent: consent === undefined ? "unasked" : String(consent) },
{ repo },
);
return { ids };
}
/**
* `trail init --connect <CODE>`: the onboarding on team.trailhq.com. Claims the
* one-time code (a wrong or spent one stops here, before anything is written),
* saves the workspace token where `trail login` keeps it, then runs init as
* usual while the page ticks off connected, mapped and learned. At the end,
* one summary of the repo goes up (a lookup's tokens saved, the learnings'
* titles, teammates' branches from git: never code, diffs or session text),
* then `done`. Offline, init still sets the repo up and says how to connect.
*/
async function runConnectInit(dir: string, opts: InitOptions): Promise<void> {
if (opts.listAgents || opts.dryRun) {
if (opts.dryRun) console.error("· --dry-run: not connecting");
await runInitCommand(dir, opts);
return;
}
const repo = resolve(dir);
if (!useServerOption(opts.server)) return;
const base = trailUrl();
const code = normalizeCode(opts.connect ?? "");
if (!code) {
console.error(`✗ "${opts.connect ?? ""}" isn't a Trail code · it looks like TRL-7F2A-K9QD, from ${base}/welcome/code`);
process.exitCode = 1;
return;
}
const ref = repoRef(repo);
const machine = machineName();
const got = await claimConnectCode(base, code, { machine, repo: ref });
const cloud = "cloud" in got ? got.cloud : null;
if ("cloud" in got) {
const cloud = got.cloud;
writeCloud(cloud);
// A sign-in link out from before is moot now.
clearPending();
console.error(`✓ connected to workspace ${cloud.workspace.name}`);
track("brain_signup_settled", { outcome: "linked", mode: "connect", duration_bucket: durationBucket(0) }, { repo });
} else if (got.reason === "invalid") {
console.error(`✗ ${got.error} · get a new code at ${base}/welcome/code`);
process.exitCode = 1;
return;
} else {
console.error(offlineLine(got.error, base, code, cmd("graft init")));
}
const reporter = cloud ? new OnboardingReporter(cloud, ref, { machine }) : null;
void reporter?.stage("connected");
// What init learned this run, kept for the summary.
const heard: { notes: Array<{ note: Note; sessions?: number }>; sessions: number } = { notes: [], sessions: 0 };
const progress: InitProgress | undefined = reporter
? {
mapped: (m) => void reporter.stage("mapped", m),
learned: (l) => {
Object.assign(heard, l);
const team = learningsSummary(repo, l.notes);
void reporter.stage("learned", { learnings: team.length, sessions: l.sessions || Math.max(0, ...team.map((t) => t.sessions)) });
},
}
: undefined;
// The page's command is pasted into a terminal, but an agent may run it for
// them: with no terminal to pick in, wire the agents this machine has.
const interactive = process.stdin.isTTY && process.stderr.isTTY;
const res = await runInitCommand(dir, interactive ? opts : { ...opts, yes: true }, progress);
if (!reporter || !cloud) return;
if (!res) {
await reporter.flush();
return;
}
// What Trail found, for the page: route B, summaries only.
const learnings = learningsSummary(repo, heard.notes);
const sessions = heard.sessions || Math.max(0, ...learnings.map((l) => l.sessions));
const tokens = tokensOnOneLookup(repo, { contextDir: program.opts<GlobalOpts>().dir });
const teamNotes = listNotes(repo, { branches: false }).filter((n) => n.scope === "repo" && !n.ref);
const teammates = teammatesFromGit(repo, { learnings: teamNotes });
const sent = await reporter.summary({ tokens, ...(sessions ? { sessions } : {}), learnings, teammates });
await reporter.stage("done");
await reporter.flush();
// Claude Code gets the workspace's brains through one user-level `trail` entry.
const brainsEntry = res.ids.includes("claude") && opts.global !== false ? installBrainsServer(homedir()) : null;
if (sent) {
const parts = [
tokens ? `one lookup saved ${tokens.pct}% of the tokens` : null,
`${learnings.length} learning${learnings.length === 1 ? "" : "s"}`,
`${teammates.length} teammate branch${teammates.length === 1 ? "" : "es"} on your files`,
].filter(Boolean);
console.error(`✓ sent ${cloud.workspace.name} a summary: ${parts.join(", ")} · titles, counts and names only, no code`);
console.error(`· see what Trail found: ${base}/welcome/code/found`);
} else {
console.error(`· couldn't send the summary to Trail this time · with a new code from ${base}/welcome/code, ${connectAgain(cmd("graft init"), "<code>", base)} sends it again`);
}
if (brainsEntry?.action === "created" || brainsEntry?.action === "updated")
console.error(`✓ Claude Code gets your workspace's brains in every project · restart it to pick them up`);
}
/** What one target's wiring did, for the compact summary to report. */
interface WireReport {
/** Hosts whose files were removed because they were not selected. */
retracted: string[];
/** ⚠ lines, printed in full. */
warnings: string[];
}
/** One repo's worth of `init` writes — the parent, then each workspace child. */
function wireTarget(
repo: string,
ids: string[],
ctx: {
home: string;
cliPath: string;
plan: ReturnType<typeof planInit>;
wantClaude: boolean;
opts: { build?: boolean; mcp?: boolean; hooks?: boolean; global?: boolean; statusline?: boolean };
/** Collect warnings and removals instead of printing a line per file, and
* leave the graph build to the caller (see buildGraphWithProgress). */
quiet?: boolean;
},
): WireReport {
const { home, cliPath, plan, wantClaude } = ctx;
const quiet = ctx.quiet === true;
const opts = quiet ? { ...ctx.opts, build: false } : ctx.opts;
const report: WireReport = { retracted: [], warnings: [] };
// Every per-file line goes through here; in quiet mode only ⚠ lines survive.
const say = (line: string) => {
if (!quiet) console.error(line);
else if (line.startsWith("⚠")) report.warnings.push(line);
};
const wantStatusline = statuslineWanted({ statusline: opts.statusline });
// Converge, don't just add. init writes the selected hosts; without this it
// never touches the rest, so a repo wired by an older version (or by the same
// version with different --agents) keeps that run's files forever — and
// `reconcileWiring` then keeps them *up to date*, which is worse than stale.
// Retract every host NOT being written now; `exclude` spares the ones about to
// be rewritten, and the graph cache is kept (init is one step from using it).
const retracted = changed(
runRetract(repo, { home, apply: true, global: opts.global, cache: false, exclude: ids }),
).filter((r) => r.action !== "skipped-unparseable");
for (const r of retracted) say(`- removed ${r.path} (${r.what}): agent not selected`);
report.retracted = [...new Set(retracted.map((r) => r.hostId))];
if (wantClaude) {
// `global`/`home` are threaded through alongside `statusline`: the claude layer
// writes under `~/.claude` now (hosts/claude-global.ts), so --no-global has to
// reach it or the flag would silently mean "no out-of-repo writes, except three".
const res = runInit(repo, { build: opts.build, cliPath, statusline: wantStatusline, global: opts.global, home, brand: brand() });
say(`✓ wrote ${res.settingsPath}`);
for (const s of res.shims) say(`✓ wrote ${s}`);
if (res.skill) say(`✓ wrote ${res.skill}`);
if (!res.mcp) {
// trail registers no server for Claude Code: the hooks and the `trail` command cover it.
} else if (res.mcp.action === "skipped-unparseable")
say(`⚠ .mcp.json: ${res.mcp.path} left unchanged (not valid JSON); add the graft server manually`);
else if (res.mcp.action === "unchanged")
say(`· mcp claude: ${res.mcp.path} (already registered)`);
else
say(`✓ mcp claude: ${res.mcp.path} (${res.mcp.action}); restart Claude Code to load the graft MCP server`);
say(res.built ? `✓ built the graph (${cmd("graft build")})` : "· skipped graph build");
if (!wantStatusline) say("· skipped Claude Code statusLine (--no-statusline)");
for (const w of res.warnings) say(`⚠ ${w}`);
}
// `ids` is already resolved, so hosts init is always driven by an explicit
// list — never by its own detection fallback.
const others = ids.filter((id) => id !== "claude");
if (others.length > 0) {
const r = runHostsInit(repo, {
agents: others,
home,
mcp: opts.mcp,
hooks: opts.hooks,
global: opts.global,
brand: brand(),
});
for (const w of r.written) say(`✓ ${w.id}: ${w.path} (${w.action})`);
for (const m of r.mcp) say(`✓ mcp ${m.id}: ${m.path} (${m.action})`);
for (const h of r.hooks) say(`✓ hook ${h.id}: ${h.path} (${h.action})`);
// Phase 2 (4.17, Q3): Codex runs Trail's hooks only once the person trusts them in /hooks.
if (r.hooks.some((h) => h.id === "codex-hooks")) {
const trust = codexTrustLine({ ...process.env, HOME: home, CODEX_HOME: process.env.CODEX_HOME || join(home, ".codex") });
// A ⚠ line, so the short output keeps it too: until then Trail does nothing in Codex.
if (trust) say(`⚠ ${trust}`);
}
// Only worth saying when there was actually something out-of-repo to skip.
if (opts.global === false && selectedWrites(plan, ids).some((w) => w.scope === "global"))
say("· skipped out-of-repo writes (--no-global)");
}
// Record WHICH graft wrote this repo's agent files, and under which flags.
// Every entry point compares this against the running binary and re-writes
// them on a mismatch, so an `npm i -g` upgrade reaches the hooks/skill/rules
// too — not just the binary. The flags ride along so a refresh replays the
// user's choices (notably --no-global) instead of overriding them.
writeStamp(repo, currentVersion, ids, {
global: opts.global !== false,
mcp: opts.mcp !== false,
hooks: opts.hooks !== false,
statusline: wantStatusline,
});
// Every host's wiring points at graft/, so the graph is built whatever was
// selected — not only when Claude Code is in the list (runInit does its own).
if (!wantClaude) {
if (!quiet)
say(
buildGraphIfMissing(repo, { build: opts.build, cliPath })
? `✓ built the graph (${cmd("graft build")})`
: "· skipped graph build",
);
}
return report;
}
/** Group a retraction report by host, so the output reads as "what leaves each agent". */
function formatRetractions(rs: Retraction[], apply: boolean): string {
const hit = changed(rs);
if (hit.length === 0) return "· nothing to remove: no graft wiring found here";
const verb = apply ? "removed" : "would remove";
const lines: string[] = [];
const byHost = new Map<string, Retraction[]>();
for (const r of hit) {
const k = byHost.get(r.hostId) ?? [];
k.push(r);
byHost.set(r.hostId, k);
}
for (const [host, items] of byHost) {
lines.push(`\n${host}:`);
for (const r of items) {
const mark =
r.action === "skipped-unparseable"
? "⚠"
: r.action === "deleted"
? "-"
: "~";
const note =
r.action === "skipped-unparseable"
? ": not valid JSON, left untouched (remove the graft entry by hand)"
: r.action === "deleted"
? ` (${r.what}, deleted)`
: ` (${r.what})`;
const scope = r.scope === "global" ? " [machine-wide]" : "";
lines.push(` ${mark} ${verb}: ${r.path}${scope}${note}`);
}
}
return lines.join("\n").replace(/^\n/, "");
}
grouped(program.command("uninstall"), GROUP.setup)
.description(`Remove every file and config entry ${TRAIL ? "trail or graft" : "graft"} has written to this repo (the inverse of init)`)
.argument("[dir]", "target repo directory", ".")
.option("-y, --yes", "actually remove (without this, prints what it would remove and exits)")
.option("--keep-cache", "keep graft/ and the .gitignore entries: wiring only")
.option("--no-global", "leave out-of-repo files alone (~/.codex, ~/.gemini)")
.action((dir: string, opts: { yes?: boolean; keepCache?: boolean; global?: boolean }) => {
const repo = resolve(dir);
const home = homedir();
const common = { home, global: opts.global, cache: opts.keepCache ? false : true };
if (!opts.yes) {
console.error(formatRetractions(planRetract(repo, common), false));
console.error("\nDry run: nothing was touched. Re-run with -y to remove.");
if (opts.global !== false)
console.error("Entries marked [machine-wide] affect every project; --no-global skips them.");
return;
}
const done = runRetract(repo, { ...common, apply: true });
console.error(formatRetractions(done, true));
const bad = changed(done).filter((r) => r.action === "skipped-unparseable");
console.error(
bad.length
? `\n⚠ ${bad.length} file(s) could not be parsed and were left as-is: see above.`
: `\n✓ ${brand()} fully removed. \`${cmd("graft init")}\` re-wires from scratch.`,
);
});
/* -------------------------------------------------------------------------- */
/* trail login · logout · workspace */
/* -------------------------------------------------------------------------- */
/**
* `trail login`: connect this machine to a Trail workspace by hand. Normally
* nobody runs it: Claude offers the same link once there's a learning to
* share. Prints the link, opens it, and waits for the person to sign in and
* add the repo they're in, then uploads its committed learnings. Other repos
* are added one at a time afterwards (`trail workspace add`).
*/
function loginCommand(name = "login"): Command {
return new Command(name)
.description("Connect this machine to a Trail workspace: sign in, add this repo, invite your team")
.argument("[dir]", "the repo to add", ".")
.option("--server <url>", "a self-hosted Trail, e.g. https://trail.acme.internal (default: Trail cloud, https://team.trailhq.com)")
.action(async (dir: string, opts: { server?: string }) => {
const repo = resolve(dir);
// Saved on the link, so its sign-in and every upload after go there; nothing in the environment.
const server = opts.server === undefined ? undefined : serverUrl(opts.server);
if (server === null) {
console.error(`✗ --server takes a URL, like https://trail.acme.internal`);
process.exitCode = 1;
return;
}
const cloud = readCloud();
if (cloud) {
console.error(`✓ already connected to workspace ${cloud.workspace.name} · ${cloud.workspace.url}`);
return;
}
rememberRepo(repo);
const url = loginLink(repo, process.env, Date.now(), server);
console.error(`· sign in and add this repo to your workspace:\n ${url}`);
if (process.stdout.isTTY) openBrowser(url);
console.error("· waiting for you to finish in the browser (ctrl-c stops; Claude picks it up later too)");
const got = await waitForConnect({ waitMs: 10 * 60 * 1000 });
if (got && "cloud" in got) printLines(cloudLines(repo, { command: "note", agent: false }));
else if (got && "error" in got) {
console.error(`✗ ${got.error} · run ${cmd("graft login")} again for a new link`);
process.exitCode = 1;
} else console.error(`· not connected yet · the link stays good for a day`);
});
}
function logoutCommand(name = "logout"): Command {
return new Command(name)
.description("Disconnect this machine from its Trail workspace (learnings stay in your repos)")
.action(() => {
const cloud = readCloud();
clearPending();
removeBrainsServer(homedir());
if (!clearCloud()) {
console.error("· not connected to a workspace");
return;
}
console.error(`✓ disconnected from workspace ${cloud?.workspace.name ?? ""} · learnings stay in your repos' .trail/`.replace(" ", " "));
});
}
/** The repo at `repo`, as the workspace names it. */
function workspaceRepo(repo: string): { key: string; name: string; checkout: string; git: boolean } {
const place = repoPlace(repo);
return { key: place.key, name: repoName(place.key, place.checkout), checkout: place.checkout, git: place.git };
}
function workspaceCommand(name = "workspace"): Command {
const ws = new Command(name)
.description("Your Trail workspace: its repos, the team page and the invite link")
.argument("[dir]", "repository root", ".")
.option("--json", "output as JSON")
.action(async (dir: string, opts: { json?: boolean }) => {
const repo = resolve(dir);
const cloud = readCloud();
if (!cloud) {
console.log("· not connected to a workspace");
console.log(`· Claude offers a link once this repo has learnings, or run ${cmd("graft login")}`);
return;
}
const me = await fetchMe(cloud);
if (isError(me)) {
console.error(`✗ ${me.error}`);
process.exitCode = 1;
return;
}
// What the workspace has now, for every command that reads cloud.json.
writeCloud({ ...cloud, workspace: me.workspace, repos: me.repos.map((r) => r.key) });
if (opts.json) {
console.log(JSON.stringify(me, null, 2));
return;
}
console.log(`${me.workspace.name} · ${me.workspace.url}`);
console.log(`invite ${me.workspace.invite_url}`);
console.log("");
const here = workspaceRepo(repo);
const width = Math.max(...me.repos.map((r) => r.name.length), here.name.length) + 3;
for (const r of me.repos) {
const by = r.added_by ? ` · added by ${r.added_by}` : "";
console.log(` ✓ ${r.name.padEnd(width)}${r.learnings} learning${r.learnings === 1 ? "" : "s"}${by}`);
}
if (here.git && !me.repos.some((r) => r.key === here.key)) {
console.log(` · ${here.name.padEnd(width)}not in the workspace · ${cmd("graft workspace add")} shares its learnings`);
} else if (here.git) printLines(leftOutLines(here.checkout));
});
ws.command("add")
.description("Add this repo to your workspace and share its learnings")
.argument("[dir]", "repository root", ".")
.action(async (dir: string) => {
const repo = resolve(dir);
const cloud = readCloud();
if (!cloud) {
console.error(`✗ not connected to a workspace · run ${cmd("graft login")}`);
process.exitCode = 1;
return;
}
const here = workspaceRepo(repo);
if (!here.git) {
console.error("✗ not a git repository");
process.exitCode = 1;
return;
}
const added = await addRepo(cloud, { key: here.key, name: here.name });
if (isError(added)) {
console.error(`✗ ${added.error}`);
process.exitCode = 1;
return;
}
const next: Cloud = { ...cloud, repos: added.repos.map((r) => r.key) };
writeCloud(next);
rememberRepo(repo);
const res = await syncRepo(here.checkout, next);
if (isError(res)) {
console.error(`✓ added ${here.name} to ${cloud.workspace.name} · its learnings go up in the background (${res.error})`);
return;
}
console.error(`✓ added ${here.name} to ${cloud.workspace.name} · shared ${res.learnings} learning${res.learnings === 1 ? "" : "s"}`);
for (const l of leftOutLines(here.checkout)) console.error(l);
console.error(`· ${cloud.workspace.url}`);
});
return ws;
}
/**
* One line per learning of this repo's that the workspace doesn't get because
* it looks like it holds a secret: named, with what was seen, never the
* secret. Nothing when there are none or git can't read the repo.
*/
function leftOutLines(checkout: string): string[] {
const out = workspaceLearnings(checkout)?.leftOut ?? [];
return out.map((l) => ` · left out: ${flatLine(l.name, 200)}${l.ref ? ` (on ${flatLine(l.ref, 120)})` : ""}: looks like it holds a secret (${l.why}). Take the secret out and commit, and it goes up with the next sync`);
}
/* -------------------------------------------------------------------------- */
/* trail team · trail check */
/* -------------------------------------------------------------------------- */
/**
* Fold a long line at `width`, indenting what wraps. The text holds a
* learning's or a teammate's words, and any word can start a line, so it's
* one line first and no word starts with a `[trail]`-style marker (flatten.ts).
*/
function wrap(text: string, width: number, indent: string): string[] {
const out: string[] = [];
let line = "";
for (const word of unmarkedWords(text)) {
if (line && line.length + 1 + word.length > width) {
out.push(line);
line = indent + word;
} else line = line ? `${line} ${word}` : word;
}
if (line) out.push(line);
return out;
}
function teamCommand(name = "team"): Command {
return new Command(name)
.description("What the team learned this week, who's working on what, and where work overlaps")
.argument("[dir]", "repository root", ".")
.option("--days <n>", "how far back to look", "7")
.option("--json", "output as JSON")
.action(async (dir: string, opts: { days: string; json?: boolean }) => {
const repo = resolve(dir);
const days = Math.max(1, Math.min(90, Number(opts.days) || 7));
const cloud = readCloud();
if (!cloud) {
localTeam(repo, days, opts.json === true);
return;
}
maybeSyncInBackground(repo);
const here = workspaceRepo(repo);
const t = await fetchTeam(cloud, { repo: cloud.repos.includes(here.key) ? here.key : undefined, days });
if (isError(t)) {
console.error(`✗ ${t.error}`);
process.exitCode = 1;
return;
}
if (opts.json) {
console.log(JSON.stringify(t, null, 2));
return;
}
const period = days === 7 ? "this week" : `the last ${days} days`;
console.log(`${period} in ${t.repo || t.workspace}`);
console.log(
`${t.people} ${t.people === 1 ? "person" : "people"} · ${t.sessions} session${t.sessions === 1 ? "" : "s"} · ` +
`${t.new_learnings} new learning${t.new_learnings === 1 ? "" : "s"} · reused ${t.reused}×`,
);
if (t.members.length) {
console.log("");
const nameW = Math.max(...t.members.map((m) => m.name.length)) + 3;
const topicW = Math.min(36, Math.max(...t.members.map((m) => m.topics.join(", ").length)) + 3);
for (const m of t.members) {
const learnings = m.learnings ? `${m.learnings} learning${m.learnings === 1 ? "" : "s"}` : "";
const reused = m.reused ? ` reused ${m.reused}×` : "";
console.log(` ${m.name.padEnd(nameW)}${m.topics.join(", ").padEnd(topicW)}${learnings.padEnd(12)}${reused}`.trimEnd());
}
}
const overlaps = [...t.overlaps.map((o) => o.text), ...branchOverlapTexts(repo)];
if (overlaps.length) {
console.log("\noverlap");
for (const o of overlaps) for (const [i, l] of wrap(o, 66, " ").entries()) console.log(i === 0 ? ` ● ${l}` : l);
}
if (t.url) console.log(`\n team page: ${t.url}`);
});
}
/** Pairs of teammates' pushed branches that change the same files, from this clone's branch cache. */
function branchOverlapTexts(repo: string, now = Date.now()): string[] {
const branches = readBranchCache(repo)?.branches ?? [];
const out: string[] = [];
for (let i = 0; i < branches.length; i++) {
for (let j = i + 1; j < branches.length; j++) {
const a = branches[i]!;
const b = branches[j]!;
if (!a.author || !b.author || a.author === b.author) continue;
const shared = a.files.filter((f) => !f.startsWith(".trail/") && b.files.includes(f));
if (!shared.length) continue;
const files = shared.length <= 2 ? shared.join(" and ") : `${shared.slice(0, 2).join(", ")} and ${shared.length - 2} more`;
out.push(
`${a.author}'s ${a.ref.replace(/^origin\//, "")} (pushed ${pushedWhen(a.at, now)}) and ${b.author}'s ${b.ref.replace(/^origin\//, "")} (pushed ${pushedWhen(b.at, now)}) both change ${files}`,
);
if (out.length >= 5) return out;
}
}
return out;
}
/**
* `trail team` before this machine is connected: what this clone can see on
* its own. Who wrote which learnings lately, and where teammates' pushed
* branches overlap. Reuse and the team page need the workspace.
*/
function localTeam(repo: string, days: number, json: boolean): void {
maybeRefreshBranches(repo);
const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
const recent = listNotes(repo).filter((n) => n.scope === "repo" && n.date >= since);
const byAuthor = new Map<string, Note[]>();
for (const n of recent) byAuthor.set(n.author || "someone", [...(byAuthor.get(n.author || "someone") ?? []), n]);
const overlaps = branchOverlapTexts(repo);
if (json) {
console.log(JSON.stringify({ days, learnings: recent.length, members: [...byAuthor].map(([name, ns]) => ({ name, learnings: ns.length, titles: ns.map((n) => n.title) })), overlaps }, null, 2));
return;
}
const here = workspaceRepo(repo);
console.log(`${days === 7 ? "this week" : `the last ${days} days`} in ${here.name} · from this clone`);
console.log(`${byAuthor.size} ${byAuthor.size === 1 ? "person" : "people"} · ${recent.length} new learning${recent.length === 1 ? "" : "s"}`);
if (byAuthor.size) {
console.log("");
const nameW = Math.max(...[...byAuthor.keys()].map((k) => k.length)) + 3;
for (const [name, ns] of byAuthor) {
const latest = ns[0]!.title.length > 40 ? `${ns[0]!.title.slice(0, 39)}…` : ns[0]!.title;
console.log(` ${name.padEnd(nameW)}${latest.padEnd(42)}${ns.length} learning${ns.length === 1 ? "" : "s"}`);
}
}
if (overlaps.length) {
console.log("\noverlap");
for (const o of overlaps) for (const [i, l] of wrap(o, 66, " ").entries()) console.log(i === 0 ? ` ● ${l}` : l);
}
console.log("\n· reuse and the team page, across your repos, are in a Trail workspace");
printLines(cloudLines(repo, { command: "check" }));
}
function teamCheckCommand(name = "check"): Command {
return new Command(name)
.description("Check your branch's diff against the learnings that bear on it: this repo's, yours, and the skills")
.argument("[dir]", "repository root", ".")
.option("--base <ref>", "compare against where the branch left this ref (default: origin's default branch)")
.option("--json", "output as JSON")
.action(async (dir: string, opts: { base?: string; json?: boolean }) => {
await runTeamCheck(resolve(dir), opts);
});
}
/** A unified diff without the sections for `.trail/` files: a learning is never the change being checked. */
function withoutTrailFiles(diff: string): string {
return diff
.split(/(?=^diff --git )/m)
.filter((part) => !/^diff --git a\/\.trail\//.test(part))
.join("");
}
/**
* `trail check`, on this machine: the branch's diff against the learnings in
* the repo's `.trail/` (teammates' pushed branches included), this person's
* own, and the repo's skills. No sign-in, no server. Exits 1 on a conflict.
*/
async function runTeamCheck(dir: string, opts: { base?: string; json?: boolean }): Promise<void> {
// From the top of the checkout: git names changed files from there, and a learning's touches have to
// line up with them exactly to fail the check. From a folder inside, none ever would.
const repo = checkoutRoot(dir) ?? dir;
const d = branchDiff(repo, opts.base);
if (!d) {
console.error("✗ not a git repository");
process.exitCode = 1;
return;
}
const files = d.files.filter((f) => !f.startsWith(".trail/"));
const me = noteAuthor(repo);
// Learnings this branch changed, as they were before it: the check reads those,
// and changing a teammate's is a finding of its own.
const atBase = learningsAtBase(repo, d.from, d.files);
const edits = teammateEdits(repo, atBase, me);
if (files.length === 0 && edits.length === 0) {
console.log(`· nothing to check: no changes against ${d.base}`);
return;
}
maybeRefreshBranches(repo);
if (d.truncated) console.error("⚠ the diff is over 400 KB; only the first 400 KB is checked");
// Replaced and retired learnings are left out after the swap, so a branch can't retire a learning by editing it.
const notes = withBaseLearnings(listNotes(repo), atBase);
const r = checkLocally({ diff: withoutTrailFiles(d.diff), files, notes, skills: listSkills(repo), asker: me, committed: committedAtBase(repo, d.from) });
r.findings.unshift(...edits);
// Only learnings the workspace gets: a personal one's file name carries its title.
const personal = new Set(notes.filter((n) => n.scope === "personal").map((n) => n.path));
const sources = r.findings.map((f) => f.source).filter((s) => s.path && !personal.has(s.path));
recordActivity({
repo: repoPlace(repo).key,
kind: "check",
asker: me,
session: sessionKey(repo) ?? `${me}-${new Date().toISOString().slice(0, 10)}`,
file_count: files.length,
shown_paths: [...new Set(sources.map((s) => learningFileName(s.path!)))],
shown_authors: [...new Set(sources.map((s) => s.author ?? ""))],
at: new Date().toISOString(),
});
const overlaps = overlapsWith(repo, files, me).slice(0, 3);
if (opts.json) {
console.log(JSON.stringify({ ...r, overlaps }, null, 2));
} else {
printCheck(r);
if (overlaps.length) console.log(`\n${overlaps.map((o) => formatOverlap(o)).join("\n")}`);
printLines(cloudLines(repo, { command: "check" }));
}
maybeSyncInBackground(repo);
if (r.findings.some((f) => f.verdict === "conflict")) process.exitCode = 1;
}
function printCheck(r: CheckResult): void {
console.log(
`checking ${r.files} changed file${r.files === 1 ? "" : "s"} against ${r.notes} learning${r.notes === 1 ? "" : "s"} and ${r.skills} skill${r.skills === 1 ? "" : "s"}\n`,
);
const conflicts = r.findings.filter((f) => f.verdict === "conflict");
const leads = r.findings.filter((f) => f.verdict === "lead");
for (const f of [...conflicts, ...leads, ...r.findings.filter((x) => x.verdict === "follows")]) {
const mark = f.verdict === "conflict" ? "✗" : f.verdict === "lead" ? "●" : "✓";
console.log(`${mark} ${f.file}${f.line ? `:${f.line}` : ""}`);
console.log(` ${f.summary}`);
if (f.why) console.log(` worth a look, can't fail the check: ${f.why}`);
if (f.replacedBy) console.log(` this branch replaces it with ${f.replacedBy.id} ("${f.replacedBy.title}"), which counts once it's on the base branch: until then, say why in the PR`);
const s = f.source;
if (f.verdict !== "follows" && s.quote) {
const who = [s.author, s.date ? shortDate(s.date) : ""].filter(Boolean).join(" · ");
for (const l of wrap(`${who ? `${who}: ` : ""}${s.quote}`, 70, " ")) console.log(` ${l.trimStart()}`);
}
}
if (r.findings.length === 0) console.log("✓ no learning bears on this change");
console.log("");
console.log(
conflicts.length
? `· ${conflicts.length} conflict${conflicts.length === 1 ? "" : "s"} · fix ${conflicts.length === 1 ? "it" : "them"}, or say why in the commit message or PR description`
: `· no conflicts${leads.length ? ` · ${leads.length} worth a look` : ""}`,
);
}
/** Tokens saved by this repo's agent sessions touched in the last 7 days. */
function savedThisWeek(repo: string, now = Date.now()): number {
const since = now - 7 * 24 * 60 * 60 * 1000;
let total = 0;
for (const id of listSessionIds(repo)) {
try {
if (statSync(join(sessionDir(repo), `${id}.json`)).mtimeMs < since) continue;
} catch {
continue;
}
total += readSession(repo, id).savedTokens ?? 0;
}
return total;
}
/** 212345 → `212k`, 1_250_000 → `1.3M`. */
function shortCount(n: number): string {
if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
if (n >= 1_000) return `${Math.round(n / 1_000)}k`;
return String(n);
}
/**
* `trail status`: what was `graft stats`, on one
* screen. The code map and whether it matches the code, the learnings for
* this repo, the workspace, and what the agents saved this week.
*/
function statusCommand(name = "status"): Command {
return new Command(name)
.description("Code map, learnings and tokens saved, on one screen")
.argument(...DIR_ARG)
.option("--json", "machine-readable output")
.action(async (dirArg: string | undefined, opts: { json?: boolean }) => {
const repo = queryRoot(dirArg);
const graph = loadGraphCached(contextDirFor(repo, program.opts<GlobalOpts>().dir));
const g = graph ? await engineFrom().checkGraph(repo) : null;
const fresh = g && !g.missing ? g.ok : null;
const kept = keepsNotes(repo);
// Only what still holds: a retired, held or replaced learning reaches no agent.
const all = kept ? liveLearnings(listNotes(repo)) : [];
const inRepo = all.filter((n) => n.scope === "repo" && !n.ref).length;
const onBranches = all.filter((n) => n.ref).length;
const personal = all.filter((n) => n.scope === "personal").length;
const cloud = readCloud();
const shared = cloud ? inWorkspace(repo, cloud) : false;
const saved = savedThisWeek(repo);
if (opts.json) {
console.log(
JSON.stringify(
{
codeMap: graph ? { nodes: graph.meta.nodeCount, inSync: fresh } : null,
learnings: kept ? { repo: inRepo, branches: onBranches, personal } : null,
workspace: cloud ? { name: cloud.workspace.name, url: cloud.workspace.url, repos: cloud.repos.length, thisRepo: shared } : null,
week: { savedTokens: saved },
},
null,
2,
),
);
return;
}
const fmt = (x: number) => x.toLocaleString("en-US");
const row = (k: string, v: string) => console.log(`${k.padEnd(11)} ${v}`);
if (!graph) row("code map", `✗ not built · run ${cmd("graft build")}`);
else if (fresh === false) row("code map", `⚠ ${fmt(graph.meta.nodeCount)} nodes · behind the code, refreshed on the next query`);
else row("code map", `✓ ${fmt(graph.meta.nodeCount)} nodes · in sync with the code`);
if (kept) {
const parts = [`${inRepo} added to this repo, in ${LEARNINGS_DIR}/`];
if (onBranches) parts.push(`${onBranches} on teammates' branches`);
if (personal) parts.push(`${personal} just for you, on this machine`);
row("learnings", parts.join(" · "));
}
if (!cloud) {
if (cloudEnabled()) row("workspace", "not connected · Claude offers a link once there are learnings to share");
} else if (cloud.via === "connect") {
row("workspace", `${cloud.workspace.name} · gets a summary of the repos you run ${cmd("graft init")} --connect in · ${cloud.workspace.url}`);
} else
row(
"workspace",
`${cloud.workspace.name} · ${cloud.repos.length} repo${cloud.repos.length === 1 ? "" : "s"}${shared ? ", this one included" : `, not this one (${cmd("graft workspace add")})`} · ${cloud.workspace.url}`,
);
row("this week", saved > 0 ? `~${shortCount(saved)} tokens saved` : "nothing saved yet");
// Phase 2 (4.17, D137): Codex's trust of Trail's hooks, and why it keeps nothing new there yet.
for (const l of codexStatusLines()) row("codex", l);
});
}
if (TRAIL) {
for (const c of [teamCheckCommand(), teamCommand()]) program.addCommand(c.helpGroup(GROUP.memory));
// Signing in waits until it gives a team more than committing .trail/ does.
for (const c of [workspaceCommand(), loginCommand(), logoutCommand()]) program.addCommand(c.helpGroup(GROUP.cloud), { hidden: !cloudEnabled() });
program.addCommand(statusCommand().helpGroup(GROUP.setup));
// Help lists the groups in this order, and the commands within each.
const order = ["ask", "grep", "skeleton", "callers", "map", "note", "check", "team", "skills", "init", "build", "status", "upgrade", "uninstall", "telemetry", "workspace", "login", "logout", "blast"];
const rank = (c: Command) => {
const i = order.indexOf(c.name());
return i === -1 ? order.length : i;
};
(program.commands as Command[]).sort((a, b) => rank(a) - rank(b));
// One line each in the list; `trail <command> --help` keeps the long text.
const summaries: Record<string, string> = {
ask: "ranked answer, with the code inlined at each file:line",
grep: "every occurrence, grouped by enclosing symbol",
skeleton: "a file's whole API in ~200 tokens",
callers: "who calls it, or what it calls with --direction out",
map: "directory clusters, hubs and hotspots",
note: "save what this session worked out, as a learning in .trail/",
skills: "the steps that worked, kept as skills when you say so · on, off, show, forget",
init: "wire trail into your agents",
build: "rebuild the code map · --check fails if it's stale",
status: "code map, learnings and tokens saved",
upgrade: "install the latest trail",
uninstall: "remove everything trail or graft wrote to this repo",
telemetry: "show or turn off the anonymous usage stats",
check: "check your diff against this repo's learnings and yours",
team: "what the team learned this week, and where work overlaps",
workspace: "your workspace's repos, team page and invite link",
login: "connect a Trail workspace (Claude offers you the link)",
logout: "disconnect this machine from its workspace",
blast: "what depends on the lines this diff touched",
};
for (const c of program.commands) if (summaries[c.name()]) c.summary(summaries[c.name()]!);
program.addHelpText("after", "\ntrail <command> --help for flags · every graft command still works");
}
program.parseAsync(process.argv).catch((err) => {
console.error(err instanceof Error ? err.message : err);
process.exit(1);
});