Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(cli): rename graft brain to graft trail, keeping the old spelling working (#468)

anirudhkumar-nanonetsfe4b941c15c7
diff --git a/TELEMETRY.md b/TELEMETRY.md
index 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.md
index 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 — the
expected 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.ts
index 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 = {}): AskResul
result.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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 in
diff --git a/src/cli.ts b/src/cli.ts
index 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 @@ brain
const 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 @@ claudeMd
const 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 @@ brain
return;
}
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 @@ brain
console.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.ts
new file mode 100644
index 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.ts
index 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` and
diff --git a/src/upkeep.ts b/src/upkeep.ts
index 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 would
diff --git a/test/legacy-args.test.ts b/test/legacy-args.test.ts
new file mode 100644
index 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.ts
index 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 },
);