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
/**
* `trail` and `graft`: one program under two names.
*
* Under graft every command keeps its old name, meaning and output, because
* agents, hooks and CI already parse it. Under trail the layout changes: the
* `graft trail …` group moves to the top level, `check` hands its name to the
* team check, and the freshness check becomes `build --check`.
*/
import { test } from "node:test";
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { chmodSync, existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { brand, cmd, graftNotice, handoverStampPath, noticeStampPath, strandedRepoNotice, tag, trailHandoverLine } from "../src/brand.js";
import { track } from "../src/telemetry/track.js";
import { commandInvokesGraft } from "../src/claude/session-metrics.js";
import { savingsLine, sumSavingsFooters } from "../src/context/savings.js";
import { homeEnv, tmpRepo } from "./helpers.js";
// --- the name itself ---
test("unset means graft: anything that loads cli.js directly was wired by an older graft", () => {
assert.equal(brand({}), "graft");
assert.equal(brand({ TRAIL_INVOKED_AS: "trail" }), "trail");
assert.equal(brand({ TRAIL_INVOKED_AS: "something-else" }), "graft");
assert.equal(tag({ TRAIL_INVOKED_AS: "trail" }), "[trail]");
assert.equal(tag({}), "[graft]");
});
test("cmd spells a graft command the way the running name does", () => {
for (const s of ["graft ask", "graft check", "graft build --deep"]) assert.equal(cmd(s, "graft"), s);
assert.equal(cmd("graft ask", "trail"), "trail ask");
assert.equal(cmd("graft build --deep", "trail"), "trail build --deep");
assert.equal(cmd("graft check", "trail"), "trail build --check");
assert.equal(cmd("graft stats", "trail"), "trail status");
// A prefix only matches a whole word: `graft checkout` is not `graft check`.
assert.equal(cmd("graft checkout", "trail"), "trail checkout");
});
// --- the once-a-day line for people still typing graft ---
function scratchHome(): string {
return mkdtempSync(join(tmpdir(), "graft-notice-"));
}
test("a person typing graft sees the new name once a day, with what it ran", () => {
const home = scratchHome();
const env = { PATH: "" };
const now = Date.parse("2026-10-07T10:00:00Z");
const first = graftNotice({ ran: "graft ask", tty: true, env, home, now });
assert.equal(
first,
"· graft is now trail. this ran trail ask, and graft keeps working (shown once a day)\n" +
"· run graft upgrade to get the trail command too",
);
assert.equal(graftNotice({ ran: "graft ask", tty: true, env, home, now: now + 60_000 }), null, "not twice in a day");
assert.ok(graftNotice({ ran: "graft ask", tty: true, env, home, now: now + 25 * 3600_000 }), "again the next day");
});
test("the notice names the trail spelling of a renamed command", () => {
const out = graftNotice({ ran: "graft check", tty: true, env: { PATH: "" }, home: scratchHome() });
assert.match(out ?? "", /this ran trail build --check,/);
});
test("no upgrade hint once a trail command is on PATH", () => {
const bin = mkdtempSync(join(tmpdir(), "graft-bin-"));
const exe = join(bin, process.platform === "win32" ? "trail.cmd" : "trail");
writeFileSync(exe, "");
chmodSync(exe, 0o755);
const out = graftNotice({ ran: "graft grep", tty: true, env: { PATH: bin }, home: scratchHome() });
assert.equal(out, "· graft is now trail. this ran trail grep, and graft keeps working (shown once a day)");
});
test("agents, pipes, CI and trail itself never see the notice, and it isn't stamped for them", () => {
const home = scratchHome();
assert.equal(graftNotice({ ran: "graft ask", tty: false, env: {}, home }), null, "no terminal");
assert.equal(graftNotice({ ran: "graft ask", tty: true, env: { CLAUDECODE: "1" }, home }), null, "Claude Code");
assert.equal(graftNotice({ ran: "graft ask", tty: true, env: { CI: "true" }, home }), null, "CI");
assert.equal(graftNotice({ ran: "graft ask", tty: true, env: { TRAIL_INVOKED_AS: "trail" }, home }), null, "trail");
assert.equal(graftNotice({ ran: "graft ask", tty: true, env: { GRAFT_NO_RENAME_NOTICE: "1" }, home }), null, "opted out");
assert.equal(existsSync(noticeStampPath(home)), false, "nothing stamped");
});
// --- a repo whose graft-era hooks can't reach trail ---
/** A repo wired by graft 0.21: a hook shim that looks for @nanonets/graft alone. */
function graftEraRepo(shim = "require.resolve('@nanonets/graft/package.json')"): string {
const repo = mkdtempSync(join(tmpdir(), "graft-era-"));
mkdirSync(join(repo, ".git"));
mkdirSync(join(repo, ".claude", "helpers"), { recursive: true });
writeFileSync(join(repo, ".claude", "helpers", "graft-hooks.cjs"), shim);
return repo;
}
const TRAIL = { TRAIL_INVOKED_AS: "trail", PATH: "" };
const STRANDED =
"· this repo's agent hooks were set up by an older graft and can't find trail. run trail init here once to move the repo over";
test("trail in a graft-era repo, with no graft to answer its hooks, says how to move the repo", () => {
const repo = graftEraRepo();
assert.equal(strandedRepoNotice({ cwd: repo, tty: true, env: TRAIL }), STRANDED);
mkdirSync(join(repo, "src", "deep"), { recursive: true });
assert.equal(strandedRepoNotice({ cwd: join(repo, "src", "deep"), tty: true, env: TRAIL }), STRANDED, "from a subfolder too");
});
test("no stranded line once something can answer the hooks, or the repo already moved", () => {
const bin = mkdtempSync(join(tmpdir(), "graft-bin-"));
const exe = join(bin, process.platform === "win32" ? "graft.cmd" : "graft");
writeFileSync(exe, "");
chmodSync(exe, 0o755);
assert.equal(strandedRepoNotice({ cwd: graftEraRepo(), tty: true, env: { ...TRAIL, PATH: bin } }), null, "graft installed");
assert.equal(strandedRepoNotice({ cwd: graftEraRepo("const PKGS = ['@trailhq/trail-code', '@nanonets/graft'];"), tty: true, env: TRAIL }), null, "a shim that looks for trail");
const moved = graftEraRepo();
writeFileSync(join(moved, ".claude", "helpers", "trail-hooks.cjs"), "");
assert.equal(strandedRepoNotice({ cwd: moved, tty: true, env: TRAIL }), null, "already on trail");
assert.equal(strandedRepoNotice({ cwd: tmpRepo(), tty: true, env: TRAIL }), null, "never wired");
});
test("agents, pipes, CI and graft itself never see the stranded line", () => {
const repo = graftEraRepo();
assert.equal(strandedRepoNotice({ cwd: repo, tty: false, env: TRAIL }), null, "no terminal");
assert.equal(strandedRepoNotice({ cwd: repo, tty: true, env: { ...TRAIL, CLAUDECODE: "1" } }), null, "Claude Code");
assert.equal(strandedRepoNotice({ cwd: repo, tty: true, env: { ...TRAIL, CI: "true" } }), null, "CI");
assert.equal(strandedRepoNotice({ cwd: repo, tty: true, env: { PATH: "" } }), null, "graft");
});
// --- what parses the output ---
test("the savings footer is read under either name", () => {
assert.equal(sumSavingsFooters("[graft] tokens saved ≈ 1,200 (80%)\n[trail] tokens saved ≈ 300 (50%)"), 1500);
});
test("a shell command running trail counts as a retrieval, like graft", () => {
assert.equal(commandInvokesGraft('trail ask "auth" --source'), true);
assert.equal(commandInvokesGraft("npx -y @trailhq/trail-code grep foo"), true);
assert.equal(commandInvokesGraft("cd x && trail callers run"), true);
assert.equal(commandInvokesGraft("node dist/bin/trail.js ask x"), true);
assert.equal(commandInvokesGraft("graft ask x"), true);
assert.equal(commandInvokesGraft("mytrail ask x"), false);
assert.equal(commandInvokesGraft("echo trail"), false);
});
test("every telemetry event says which name ran it", () => {
process.env.GRAFT_POSTHOG_KEY = "phc_test_key";
const home = scratchHome();
const open = { HOME: home, USERPROFILE: home } as NodeJS.ProcessEnv;
const viaTrail = track("first_run", {}, { home, env: { ...open, TRAIL_INVOKED_AS: "trail" } });
const other = scratchHome();
const viaGraft = track("first_run", {}, { home: other, env: { HOME: other, USERPROFILE: other } });
assert.equal(viaTrail?.properties.cli_name, "trail");
assert.equal(viaGraft?.properties.cli_name, "graft");
});
// --- the two command layouts, end to end ---
function run(name: "trail" | "graft", args: string[], home: string, cwd = process.cwd(), extra: NodeJS.ProcessEnv = {}) {
const r = spawnSync(process.execPath, ["--import", "tsx", join(process.cwd(), "src", "bin", `${name}.ts`), ...args], {
cwd,
encoding: "utf8",
env: { ...process.env, ...homeEnv(home), DO_NOT_TRACK: "1", CLAUDECODE: undefined, TRAIL_INVOKED_AS: undefined, TRAIL_CLOUD: undefined, ...extra },
});
return { status: r.status, out: r.stdout, err: r.stderr };
}
function builtRepo(): string {
const d = tmpRepo("trailname");
mkdirSync(join(d, "src"), { recursive: true });
writeFileSync(join(d, "src", "a.ts"), "export function alpha(): number {\n return beta();\n}\n");
writeFileSync(join(d, "src", "b.ts"), "export function beta(): number {\n return 1;\n}\n");
spawnSync("git", ["init", "-q"], { cwd: d });
return d;
}
test("trail --help groups the commands, and lists the workspace ones only once signing in is on", () => {
const home = scratchHome();
const r = run("trail", ["--help"], home);
assert.equal(r.status, 0);
for (const heading of ["Find code", "Learnings:", "Setup:", "CI:"]) assert.ok(r.out.includes(heading), heading);
assert.doesNotMatch(r.out, /\bmemory\b/i, "learnings, never memory");
for (const c of ["note", "check", "team", "skills", "status"]) assert.match(r.out, new RegExp(`^ ${c} `, "m"), c);
// Still run, just not listed: the brain's commands, skills' undo (also under trail skills), and signing in.
for (const c of ["viz", "mcp", "stats", "watch", "connect", "trail", "push", "pull", "learn", "forget", "workspace", "login", "logout"])
assert.doesNotMatch(r.out, new RegExp(`^ ${c} `, "m"), c);
const on = run("trail", ["--help"], home, process.cwd(), { TRAIL_CLOUD: "1" });
assert.ok(on.out.includes("Workspace"));
for (const c of ["workspace", "login", "logout"]) assert.match(on.out, new RegExp(`^ ${c} `, "m"), c);
});
test("graft --help keeps its old flat list, including check, without the trail group", () => {
const r = run("graft", ["--help"], scratchHome());
assert.equal(r.status, 0);
assert.match(r.out, /^Usage: graft /m);
for (const c of ["check", "stats", "viz"]) assert.match(r.out, new RegExp(`^ ${c} `, "m"), c);
assert.doesNotMatch(r.out, /^ trail /m);
assert.ok(!r.out.includes("Workspace ·"));
});
test("the freshness check is graft check under graft and trail build --check under trail", () => {
const home = scratchHome();
const d = builtRepo();
assert.equal(run("graft", ["build", d], home).status, 0);
const g = run("graft", ["check", d], home);
assert.equal(g.status, 0, g.err);
assert.match(g.out, /graph check: OK/);
assert.match(g.out, /Run `graft build --deep` to summarize them/);
const t = run("trail", ["build", "--check", d], home);
assert.equal(t.status, 0, t.err);
assert.match(t.out, /graph check: OK/);
assert.match(t.out, /Run `trail build --deep` to summarize them/);
assert.equal(run("graft", ["build", "--check", d], home).status, 0, "graft build --check works too");
// Stale: a new function the graph has never seen fails both, the same way.
writeFileSync(join(d, "src", "c.ts"), "export function gamma(): number {\n return 2;\n}\n");
assert.equal(run("graft", ["check", d, "--json"], home).status, 1);
assert.equal(run("trail", ["build", "--check", d, "--json"], home).status, 1);
});
test("trail check is the team check, not the freshness check", () => {
// Outside a git repo there is no diff to check; the freshness check is build --check.
const r = run("trail", ["check", mkdtempSync(join(tmpdir(), "not-git-"))], scratchHome());
assert.equal(r.status, 1);
assert.match(r.err, /not a git repository/);
});
test("trail status puts the code map on one screen, and the workspace only once signing in is on", () => {
const home = scratchHome();
const d = builtRepo();
run("trail", ["build", d], home);
const r = run("trail", ["status", d], home);
assert.equal(r.status, 0, r.err);
assert.match(r.out, /^code map {4}✓ \d+ nodes · in sync with the code$/m);
assert.doesNotMatch(r.out, /^workspace/m);
const on = run("trail", ["status", d], home, process.cwd(), { TRAIL_CLOUD: "1" });
assert.match(on.out, /^workspace {3}not connected · Claude offers a link once there are learnings to share$/m);
const json = JSON.parse(run("trail", ["status", d, "--json"], home).out);
assert.equal(json.workspace, null);
});
test("trail stats still works under trail", () => {
const home = scratchHome();
const d = builtRepo();
run("trail", ["build", d], home);
const r = run("trail", ["stats", d], home);
assert.equal(r.status, 0, r.err);
});
test("the savings footer says [trail] under trail and [graft] under graft", () => {
const saved = { baselineChars: 40_000, files: 3 } as Parameters<typeof savingsLine>[1];
const before = process.env.TRAIL_INVOKED_AS;
try {
delete process.env.TRAIL_INVOKED_AS;
assert.match(savingsLine("short pack", saved), /^\[graft\] tokens saved ≈ /);
process.env.TRAIL_INVOKED_AS = "trail";
assert.match(savingsLine("short pack", saved), /^\[trail\] tokens saved ≈ /);
} finally {
if (before === undefined) delete process.env.TRAIL_INVOKED_AS;
else process.env.TRAIL_INVOKED_AS = before;
}
});
// --- MCP: trail's tool names, graft's still answered ---
async function mcpRpc(name: "trail" | "graft", dir: string, messages: object[], expected: number): Promise<any[]> {
const { spawn } = await import("node:child_process");
const child = spawn(process.execPath, ["--import", "tsx", join(process.cwd(), "src", "bin", `${name}.ts`), "mcp", dir], {
stdio: ["pipe", "pipe", "pipe"],
env: { ...process.env, DO_NOT_TRACK: "1", TRAIL_INVOKED_AS: undefined },
});
const out: any[] = [];
let buf = "";
child.stdout.on("data", (d) => {
buf += d.toString();
let i;
while ((i = buf.indexOf("\n")) !== -1) {
const line = buf.slice(0, i).trim();
buf = buf.slice(i + 1);
if (line) out.push(JSON.parse(line));
}
});
for (const m of messages) child.stdin.write(`${JSON.stringify(m)}\n`);
const deadline = Date.now() + 20000;
while (out.length < expected && Date.now() < deadline) await new Promise((r) => setTimeout(r, 50));
child.kill();
return out;
}
test("trail mcp advertises trail_* tools and answers graft_* calls too; graft mcp is unchanged", async () => {
const d = builtRepo();
run("graft", ["build", d], scratchHome());
const init = { jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-03-26", capabilities: {}, clientInfo: { name: "t", version: "0" } } };
const list = { jsonrpc: "2.0", id: 2, method: "tools/list" };
const call = (id: number, tool: string) => ({ jsonrpc: "2.0", id, method: "tools/call", params: { name: tool, arguments: { query: "beta" } } });
const t = await mcpRpc("trail", d, [init, list, call(3, "trail_find_code"), call(4, "graft_find_code")], 4);
assert.equal(t.find((r) => r.id === 1)?.result.serverInfo.name, "trail");
assert.match(t.find((r) => r.id === 1)?.result.instructions, /select:mcp__trail__trail_find_code,/);
const names = t.find((r) => r.id === 2)?.result.tools.map((x: { name: string }) => x.name);
assert.ok(names.includes("trail_find_code") && !names.some((n: string) => n.startsWith("graft_")), String(names));
for (const id of [3, 4]) assert.equal(t.find((r) => r.id === id)?.result.isError, false, `call ${id}`);
const g = await mcpRpc("graft", d, [init, list], 2);
assert.equal(g.find((r) => r.id === 1)?.result.serverInfo.name, "graft");
assert.ok(g.find((r) => r.id === 2)?.result.tools.some((x: { name: string }) => x.name === "graft_find_code"));
});
test("both tool vocabularies count as retrievals", async () => {
const { canonicalToolName } = await import("../src/mcp/tool-names.js");
const { isGraftMcpTool } = await import("../src/claude/session-metrics.js");
assert.equal(canonicalToolName("trail_find_code"), "graft_find_code");
assert.equal(canonicalToolName("graft_ask"), "graft_find_code");
assert.equal(isGraftMcpTool("mcp__trail__trail_trace_calls"), true);
assert.equal(isGraftMcpTool("mcp__graft__graft_find_all"), true);
});
// --- the agent's line on a machine with graft and no trail ---
test("on graft without trail, the agent is told once a week how to get trail", () => {
const home = scratchHome();
const now = Date.parse("2026-10-14T10:00:00Z");
const line = trailHandoverLine({ env: { PATH: "" }, home, now });
assert.match(line ?? "", /graft is now Trail-code/);
assert.match(line ?? "", /`graft upgrade` adds it and graft keeps working/);
assert.equal(trailHandoverLine({ env: { PATH: "" }, home, now: now + 3 * 86400_000 }), null, "not again that week");
assert.ok(trailHandoverLine({ env: { PATH: "" }, home, now: now + 8 * 86400_000 }), "again the next week");
});
test("no handover line once trail is installed, under trail, in CI, or opted out", () => {
const bin = mkdtempSync(join(tmpdir(), "graft-bin-"));
const exe = join(bin, process.platform === "win32" ? "trail.cmd" : "trail");
writeFileSync(exe, "");
chmodSync(exe, 0o755);
const home = scratchHome();
assert.equal(trailHandoverLine({ env: { PATH: bin }, home }), null, "trail on PATH");
assert.equal(trailHandoverLine({ env: { PATH: "", TRAIL_INVOKED_AS: "trail" }, home }), null, "trail");
assert.equal(trailHandoverLine({ env: { PATH: "", CI: "true" }, home }), null, "CI");
assert.equal(trailHandoverLine({ env: { PATH: "", GRAFT_NO_RENAME_NOTICE: "1" }, home }), null, "opted out");
assert.equal(existsSync(handoverStampPath(home)), false, "nothing stamped");
});