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
feat(cli): rename graft brain to graft trail, keeping the old spelling working (#468)
anirudhkumar-nanonetsfe4b941c15c7
diff --git a/TELEMETRY.md b/TELEMETRY.mdindex 110df85b..3736ac0d 100644--- a/TELEMETRY.md+++ b/TELEMETRY.md@@ -46,7 +46,7 @@ The events:| `build_completed` | `files_bucket`, `langs`, `mode` (`fast`/`deep`), `duration_bucket`, `incremental` | A build succeeds || `build_failed` | `stage`, `code` — both fixed enums | A build throws || `query` | `command`, `surface` (`cli`/`mcp`/`hook`), `hit` (`ask` only) | Any query command |-| `brain_signup_opened` | — | `graft brain push` on a repo with no brain opens your browser to make one |+| `brain_signup_opened` | — | `graft trail push` on a repo with no brain opens your browser to make one || `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`no_tty`/`bad_callback`), `duration_bucket` | That handoff ends, one way or the other || `session_summary` | `graft_reads_bucket`, `source_reads_bucket`, `saved_tokens_bucket`, `graft_turns_bucket`, `reported_turns_bucket` | Once, after an agent session ends |diff --git a/docs/github-app.md b/docs/github-app.mdindex 0170b5f7..b76bdc70 100644--- a/docs/github-app.md+++ b/docs/github-app.md@@ -123,7 +123,7 @@ back would mean minting a credential per build for nothing.`404` with an `error` means the App is not installed on the repository — theexpected answer for "someone pasted a repo we cannot see", not a failure. The-caller turns it into a choice: install the App, or run `graft init --brain`+caller turns it into a choice: install the App, or run `graft init --trail`locally, where the code never leaves the machine.| Variable | Meaning |diff --git a/src/ask/ask.ts b/src/ask/ask.tsindex 7c3450ff..a8469747 100644--- a/src/ask/ask.ts+++ b/src/ask/ask.ts@@ -1392,7 +1392,7 @@ export function ask(dir: string, query: string, opts: AskOptions = {}): AskResulresult.saved = baselineFor(result.hits, corpus.graph);// What the team decided about the code this pack just inlined. Read from the// local cache only — `ask` is on the agent's hot path and must never wait on- // the network; `graft brain pull` and `init` are what refresh it.+ // the network; `graft trail pull` and `init` are what refresh it.const applied = attachBrainRules(root, result.hits, corpus.graph);if (applied.length) result.rules = applied;}diff --git a/src/brain/connect.ts b/src/brain/connect.tsindex 534f1ca4..4cd81d4d 100644--- a/src/brain/connect.ts+++ b/src/brain/connect.ts@@ -15,7 +15,7 @@ import { writeBrainSections, type BrainWrite } from './wire.js';import { basename } from 'node:path';/**- * Parse the `--brain` value.+ * Parse the `--trail` value.** The onboarding page hands over one string so there is one thing to copy. Two* accepted shapes:@@ -29,19 +29,19 @@ import { basename } from 'node:path';*/export function parseBrainArg(value: string): BrainLink | { error: string } {const raw = value.trim();- if (!raw) return { error: 'empty --brain value' };+ if (!raw) return { error: 'empty --trail value' };const cut = raw.indexOf(':');if (cut > 0) {const brainId = raw.slice(0, cut).trim();const token = raw.slice(cut + 1).trim();- if (!brainId || !token) return { error: 'expected --brain <brainId>:<token>' };+ if (!brainId || !token) return { error: 'expected --trail <brainId>:<token>' };return { brainId, token };}const envToken = process.env.GRAFT_BRAIN_TOKEN;if (!envToken) {return {error:- 'expected --brain <brainId>:<token>, or a bare brain id with the token in GRAFT_BRAIN_TOKEN',+ 'expected --trail <brainId>:<token>, or a bare brain id with the token in GRAFT_BRAIN_TOKEN',};}return { brainId: raw, token: envToken };@@ -61,7 +61,7 @@ export interface ConnectResult {** The link is stored even when the pull fails. That is deliberate: a token* typed correctly against a brain that is momentarily unreachable should not- * have to be pasted again — `graft brain pull` retries, and `ask` degrades to+ * have to be pasted again — `graft trail pull` retries, and `ask` degrades to* the code-only answer meanwhile.*/export async function connectBrain(@@ -77,7 +77,7 @@ export async function connectBrain(ruleCount: 0,writes: [],warning:- 'could not reach the brain to pull its rules — the link is saved; run `graft brain pull` to retry',+ 'could not reach the brain to pull its rules — the link is saved; run `graft trail pull` to retry',};}writeRulesCache(repo, { brainId: link.brainId, fetchedAt: Date.now(), rules });@@ -98,7 +98,7 @@ export async function pullBrain(return connectBrain(repo, link, opts);}-/** The linked brain and its cached rule set, for `graft brain status`. */+/** The linked brain and its cached rule set, for `graft trail status`. */export function brainStatus(repo: string): {link: BrainLink | null;rules: BrainRule[];diff --git a/src/brain/link.ts b/src/brain/link.tsindex a432e605..b6992ffd 100644--- a/src/brain/link.ts+++ b/src/brain/link.ts@@ -91,7 +91,7 @@ export function readLink(dir: string): BrainLink | null {* token — which is exactly why this is also where it gets ignored. The comment* on {@link BrainLink} has claimed `.graft/` was "git-ignored" since the day it* was written, and nothing ever made it true: `ensureGitignored` only ever ran- * for the graph cache. Every repository anyone ran `graft brain connect` in was+ * for the graph cache. Every repository anyone ran `graft trail connect` in was* therefore one `git add -A` away from publishing a credential. */export function writeLink(dir: string, link: BrainLink): void {patchBuildConfig(dir, { brain: link });diff --git a/src/brain/signup.ts b/src/brain/signup.tsindex d27faf28..d9da4952 100644--- a/src/brain/signup.ts+++ b/src/brain/signup.ts@@ -2,12 +2,12 @@* Getting a brain without leaving the terminal.** Until now a brain could only begin in the browser. You signed up on Trail, it- * created the brain, and handed you a `graft init --brain <id>:<token>` line to+ * created the brain, and handed you a `graft init --trail <id>:<token>` line to* paste. That is the right way round when the website is where you already are,* and the wrong way round when you are standing in a repository with graft* already installed — which is where most people meet graft first.*- * So `graft brain push` on an unlinked repo starts here instead of stopping.+ * So `graft trail push` on an unlinked repo starts here instead of stopping.* Graft opens a listener on loopback, sends the browser to Trail carrying the* repository it is standing in and the port to answer on, and waits. Trail does* the signing up, makes a brain for that repository, and redirects back to the@@ -77,7 +77,7 @@ function sameState(got: string, want: string): boolean {function donePage(ok: boolean): string {const msg = ok? "Your brain is connected. Return to your terminal — the push is already running."- : "That handoff did not match this terminal. Run `graft brain push` again.";+ : "That handoff did not match this terminal. Run `graft trail push` again.";return `<!doctype html><meta charset="utf-8"><title>graft</title><body style="font:15px/1.5 system-ui,sans-serif;margin:3rem auto;max-width:32rem;color:#1F2129"><p>${msg}</p><p style="color:#676767">You can close this tab.</p>`;}@@ -155,7 +155,7 @@ export async function startHandoff(): Promise<Handoff> {let timer: NodeJS.Timeout | undefined;const timeout = new Promise<HandoffResult>((resolve) => {timer = setTimeout(- () => resolve({ error: "timed out waiting for the browser — run `graft brain push` again, or use the link above", reason: "timed_out" }),+ () => resolve({ error: "timed out waiting for the browser — run `graft trail push` again, or use the link above", reason: "timed_out" }),timeoutMs,);// The timer must not hold the process open once the browser has answered.diff --git a/src/brain/watch.ts b/src/brain/watch.tsindex 0e32b8c0..43e3ab57 100644--- a/src/brain/watch.ts+++ b/src/brain/watch.ts@@ -1,7 +1,7 @@/*** Watching a brain being built, from the terminal.*- * `graft brain push` used to end at "it is being mined into rules now — a few+ * `graft trail push` used to end at "it is being mined into rules now — a few* minutes. Watch it finish in your browser." and hand the prompt straight back.* That sentence is the last thing this process ever says about the work, and it* is said BEFORE the part that actually fails: of the repo brains attempted indiff --git a/src/cli.ts b/src/cli.tsindex a28f9dce..594115ac 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -31,6 +31,7 @@ import {} from "./brain/push.js";import type { HistoryThread } from "./app/history.js";import { readLink, writeLink } from "./brain/link.js";+import { withLegacyNames } from "./legacy-args.js";import { applyChanges, fetchAcceptedChanges, markApplied } from "./brain/claude-md.js";import { watchBuild } from "./brain/watch.js";import { openBrowser, signupUrl, startHandoff } from "./brain/signup.js";@@ -958,8 +959,8 @@ program.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("--brain <handoff>", "attach a Trail brain: <brainId>:<token> (or a bare brain id with GRAFT_BRAIN_TOKEN set)")- .action(async (dir: string, opts: { build?: boolean; agents?: string[]; allAgents?: boolean; listAgents?: boolean; mcp?: boolean; hooks?: boolean; statusline?: boolean; dryRun?: boolean; yes?: boolean; global?: boolean; brain?: string }) => {+ .option("--trail <handoff>", "attach a Trail: <brainId>:<token> (or a bare id with GRAFT_BRAIN_TOKEN set)")+ .action(async (dir: string, opts: { build?: boolean; agents?: string[]; allAgents?: boolean; listAgents?: boolean; mcp?: boolean; hooks?: boolean; statusline?: boolean; dryRun?: boolean; yes?: boolean; global?: boolean; trail?: string }) => {if (opts.listAgents) {for (const id of [...hostIds(), "claude"]) console.log(id);return;@@ -967,10 +968,10 @@ program// Parsed before anything is written: a mistyped handoff should cost the user// an error, not a half-wired repo they have to `graft uninstall` out of.let brainLink: BrainLink | undefined;- if (opts.brain) {- const parsed = parseBrainArg(opts.brain);+ if (opts.trail) {+ const parsed = parseBrainArg(opts.trail);if ("error" in parsed) {- console.error(`✗ --brain: ${parsed.error}`);+ console.error(`✗ --trail: ${parsed.error}`);process.exitCode = 1;return;}@@ -1063,7 +1064,7 @@ program}// The brain comes last, after the graph exists: its rules are anchored to- // symbols, and `graft brain status` can only report how many of them resolve+ // symbols, and `graft trail status` can only report how many of them resolve// once there is a graph to resolve them against.if (brainLink) {const res = await connectBrain(repo, brainLink, { home, ids });@@ -1247,9 +1248,10 @@ program);});+// `graft trail …` still works: see legacy-args.ts.const brain = program- .command("brain")- .description("The Trail brain attached to this repo: the rules mined from its own history");+ .command("trail")+ .description("The Trail attached to this repo: the rules mined from its own history");/*** Get this repo a brain from the terminal, by sending the user through signup@@ -1279,7 +1281,7 @@ async function signUpForBrain(repo: string, slug: string): Promise<BrainLink | n// A non-interactive shell has nobody to click anything, so waiting five// minutes for a browser that will never come is worse than saying so now.if (!process.stderr.isTTY) {- console.error("· not a terminal — open that link, then run `graft brain connect <brainId>:<token>` here");+ console.error("· not a terminal — open that link, then run `graft trail connect <brainId>:<token>` here");// Its own outcome, not a timeout: nothing here could have opened a browser,// so folding the two together would read as people abandoning signup when// it is only a remote shell doing what it has to.@@ -1327,7 +1329,7 @@ brain// read the repo yet. Saying "0 rules" without saying why reads as a// failure, and the next step is the whole point.console.error("✓ attached this repo to the brain — it has no rules yet");- console.error("· run `graft brain push` to read this repository into it");+ console.error("· run `graft trail push` to read this repository into it");return;}console.error(`✓ pulled ${res.ruleCount} rule(s) from ${parsed.brainId}`);@@ -1342,7 +1344,7 @@ brainconst repo = resolve(dir);const res = await pullBrain(repo, { home: homedir() });if (!res) {- console.error("· no brain attached — run `graft brain connect <brainId>:<token>`");+ console.error("· no brain attached — run `graft trail connect <brainId>:<token>`");return;}if (res.warning) {@@ -1471,7 +1473,7 @@ brain// A non-zero exit, unlike every other ending here: this is the one case// where the work did not produce a brain, and a CI step that ran the push// should hear about it the way it hears about any other failure.- console.error(" Nothing was lost — the brain is still there. Run `graft brain push` again to retry the read.");+ console.error(" Nothing was lost — the brain is still there. Run `graft trail push` again to retry the read.");process.exitCode = 1;return;}@@ -1495,7 +1497,7 @@ claudeMdconst repo = resolve(dir);const link = readLink(repo);if (!link) {- console.error("✗ this repo has no brain attached — run `graft brain push` first");+ console.error("✗ this repo has no brain attached — run `graft trail push` first");process.exitCode = 1;return;}@@ -1565,7 +1567,7 @@ brainreturn;}if (!link) {- console.error("· no brain attached — run `graft brain connect <brainId>:<token>`");+ console.error("· no brain attached — run `graft trail connect <brainId>:<token>`");return;}console.error(`brain ${link.brainId}`);@@ -1594,7 +1596,7 @@ brainconsole.error(`✓ detached the brain from ${repo}`);});-program.parseAsync().catch((err) => {+program.parseAsync(withLegacyNames(process.argv)).catch((err) => {console.error(err instanceof Error ? err.message : err);process.exit(1);});diff --git a/src/legacy-args.ts b/src/legacy-args.tsnew file mode 100644index 00000000..00bd4aa0--- /dev/null+++ b/src/legacy-args.ts@@ -0,0 +1,29 @@+/**+ * The old spellings of renamed commands, still accepted.+ *+ * `graft brain …` became `graft trail …`, and `init --brain` became+ * `init --trail`, to match the product's name. The old ones are in docs, in+ * scripts, in shell history and on Trail pages already open in someone's+ * browser, so they keep working. They are rewritten before parsing rather than+ * registered as aliases, so help lists only the new names.+ */++/** Global options that take a value: their value is never the command. */+const VALUE_OPTIONS = new Set(["--dir", "--provider", "--model", "--api-key", "--base-url"]);++/** `process.argv` with the old spellings replaced by the new ones. */+export function withLegacyNames(argv: readonly string[]): string[] {+ const out = [...argv];+ // The command is the first word after the global options.+ for (let i = 2; i < out.length; i++) {+ const a = out[i]!;+ if (a === "--") break;+ if (a.startsWith("-")) {+ if (VALUE_OPTIONS.has(a)) i++;+ continue;+ }+ if (a === "brain") out[i] = "trail";+ break;+ }+ return out.map((a) => (a === "--brain" ? "--trail" : a.startsWith("--brain=") ? `--trail=${a.slice("--brain=".length)}` : a));+}diff --git a/src/telemetry/contract.ts b/src/telemetry/contract.tsindex 386ef139..2933b1af 100644--- a/src/telemetry/contract.ts+++ b/src/telemetry/contract.ts@@ -51,7 +51,7 @@ export const EVENTS: Record<string, ReadonlySet<string>> = {build_failed: new Set<string>(['stage', 'code']),/** One query, from any surface. The DAU backbone and the dead-command detector. */query: new Set<string>(['command', 'surface', 'hit']),- /** `graft brain push` in a repo with no brain, sending the user to Trail to+ /** `graft trail push` in a repo with no brain, sending the user to Trail to* make one. Queued the moment the link is printed, so a signup somebody* walked away from is still counted — the settle below never fires for those,* and abandonment is exactly the thing a terminal handoff loses silently. */@@ -107,7 +107,7 @@ export function isTrackedCommand(name: string): name is TrackedCommand {}/**- * How a `graft brain push` signup ended.+ * How a `graft trail push` signup ended.** Four categories and nothing else, because the alternative — the error string* the CLI already prints — carries a repo slug and a URL. `timed_out` anddiff --git a/src/upkeep.ts b/src/upkeep.tsindex 5856f61c..132fb287 100644--- a/src/upkeep.ts+++ b/src/upkeep.ts@@ -152,7 +152,7 @@ export function maybeRefreshInBackground(home?: string, now = Date.now()): boole* stalled first turn. So nothing here blocks — the child does the fetch and* this call returns immediately.*- * Without it a brain is pulled exactly once, at `graft brain connect`, and+ * Without it a brain is pulled exactly once, at `graft trail connect`, and* never again. That was survivable when connecting happened after the brain* finished building; it is not survivable now that onboarding connects DURING* the build, because the one pull returns an empty rulebook and nothing woulddiff --git a/test/legacy-args.test.ts b/test/legacy-args.test.tsnew file mode 100644index 00000000..b62c17e6--- /dev/null+++ b/test/legacy-args.test.ts@@ -0,0 +1,30 @@+/**+ * `graft brain …` and `init --brain` were renamed to `trail`. The old spellings+ * are in docs, scripts and Trail pages already open, so they must keep working+ * — and only where they are the command, never as someone's argument.+ */+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { withLegacyNames } from '../src/legacy-args.js';++const run = (...args: string[]) => withLegacyNames(['node', 'graft', ...args]).slice(2);++test('graft brain … runs graft trail …', () => {+ assert.deepEqual(run('brain', 'push'), ['trail', 'push']);+ assert.deepEqual(run('trail', 'push'), ['trail', 'push']);+});++test('the command is found after global options, including ones that take a value', () => {+ assert.deepEqual(run('--dir', 'brain', 'brain', 'status'), ['--dir', 'brain', 'trail', 'status'], 'a --dir named brain stays');+ assert.deepEqual(run('--model', 'x', 'brain', 'pull'), ['--model', 'x', 'trail', 'pull']);+});++test('only the command word is renamed', () => {+ assert.deepEqual(run('ask', 'how does the brain work'), ['ask', 'how does the brain work']);+ assert.deepEqual(run('grep', 'brain'), ['grep', 'brain']);+});++test('init --brain runs init --trail, in both forms', () => {+ assert.deepEqual(run('init', '--brain', 'id:tok'), ['init', '--trail', 'id:tok']);+ assert.deepEqual(run('init', '--brain=id:tok'), ['init', '--trail=id:tok']);+});diff --git a/test/telemetry-contract.test.ts b/test/telemetry-contract.test.tsindex e31a13ca..cd5886cb 100644--- a/test/telemetry-contract.test.ts+++ b/test/telemetry-contract.test.ts@@ -186,7 +186,7 @@ test('brain signup: the outcome is a category, never the sentence the user saw',{outcome: 'timed_out',duration_bucket: durationBucket(5 * 60 * 1000),- error: 'timed out waiting for the browser — run `graft brain push` again',+ error: 'timed out waiting for the browser — run `graft trail push` again',},{ home, env: OPEN },);