Skip to content

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

22.1 KB
Raw Blame
/**
 * The first-run read of past Claude sessions: which transcripts are the repo's,
 * what counts as the person's own words, and that a finding survives only
 * when the quotes it cites really are in two or more sessions.
 */
import { test } from "node:test";
import assert from "node:assert/strict";
import { spawnSync } from "node:child_process";
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { basename, dirname, join } from "node:path";
import { claudeBin, ownWords, readSession, scrub, sessionFiles, verify, withoutSecrets, type PastSession } from "../src/notes/cold-start.js";
import { ensureRepoHome } from "../src/notes/home.js";
import { standingDirective } from "../src/claude/format.js";
import { commitLines, namesLabel, parseNote, PERSONAL_SAVED_LINE, standingLearnings } from "../src/notes/notes.js";
import { teammatesOn } from "../src/notes/git-facts.js";
import { claudeProjectDir } from "../src/notes/session-cost.js";
import { tmpRepo } from "./helpers.js";

// Days are local dates (init-days.test.ts); these fixtures are written in UTC.
process.env.TZ = "UTC";

function transcript(entries: object[]): string {
  return entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
}

const user = (content: unknown, extra: object = {}) => ({ type: "user", cwd: "/r", timestamp: "2026-10-01T10:00:00Z", message: { role: "user", content }, ...extra });
const said = (text: string) => ({ type: "assistant", message: { content: [{ type: "text", text }] } });

test("only the person's own words count: wrappers, hand-backs and pasted text are dropped", () => {
  assert.equal(ownWords("<command-name>/plan-my-work</command-name>"), null);
  assert.equal(ownWords("Caveat: the messages below were generated by the user"), null);
  assert.equal(ownWords("Another Claude session sent a message: done"), null);
  assert.equal(ownWords("<system-reminder>x</system-reminder>"), null);
  assert.equal(ownWords('use a worktree <pasted_content id="1">lots</pasted_content id="1">'), "use a worktree [pasted text]");
  assert.equal(ownWords("no, open the PR against dev"), "no, open the PR against dev");
});

test("a session keeps the person's messages with the end of what Claude said before each", () => {
  const dir = mkdtempSync(join(tmpdir(), "cold-read-"));
  const f = join(dir, "s1.jsonl");
  writeFileSync(
    f,
    transcript([
      user("fix the login bug"),
      said("I pushed the fix to main."),
      user("no, never push to main, open a PR against dev"),
      user([{ type: "tool_result", content: "ok" }]),
      user("<task-notification>done</task-notification>", { origin: { kind: "task-notification" } }),
      user("hand-back", { isSidechain: true }),
    ]),
  );
  const s = readSession(f)!;
  assert.equal(s.id, "s1");
  assert.deepEqual(s.prompts.map((p) => p.text), ["fix the login bug", "no, never push to main, open a PR against dev"]);
  assert.equal(s.prompts[1]!.before, "I pushed the fix to main.");
});

test("a headless run is skipped whole: its prompt was written once and replayed", () => {
  const dir = mkdtempSync(join(tmpdir(), "cold-sdk-"));
  const f = join(dir, "s.jsonl");
  writeFileSync(f, transcript([user("summarise the repo", { entrypoint: "sdk-cli" })]));
  assert.equal(readSession(f), null);
});

test("a repo's sessions are its own and its worktrees', not a sibling's with the same prefix", () => {
  const home = mkdtempSync(join(tmpdir(), "cold-home-"));
  const repo = "/work/assign";
  const write = (folderOf: string, cwd: string, name: string) => {
    const d = claudeProjectDir(folderOf, home);
    mkdirSync(d, { recursive: true });
    writeFileSync(join(d, `${name}.jsonl`), transcript([user("hi", { cwd })]));
  };
  write(repo, repo, "main");
  write(`${repo}/.claude/worktrees/x`, `${repo}/.claude/worktrees/x`, "worktree");
  write("/work/assign-old", "/work/assign-old", "sibling");
  const names = sessionFiles([repo], home).map((p) => basename(p)).sort();
  assert.deepEqual(names, ["main.jsonl", "worktree.jsonl"]);
});

function session(id: string, at: string, ...texts: string[]): PastSession {
  return { id, at, prompts: texts.map((text) => ({ text })) };
}

test("a finding is kept only when its quotes are in two sessions, and they're counted by trail", () => {
  const sessions = [
    session("aaaaaaaa-1", "2026-10-09T12:00:00Z", "no, open the PR against the dev branch please"),
    session("bbbbbbbb-2", "2026-10-01T12:00:00Z", "again: open the PR against the dev branch"),
    session("cccccccc-3", "2026-09-20T12:00:00Z", "something else entirely"),
  ];
  const out = verify(
    [
      {
        title: "Open PRs against dev",
        for: "team",
        body: "## Decided\n- PRs go to dev.",
        evidence: [
          { session: "aaaaaaaa", quote: "open the PR against the dev branch" },
          // Filed under the wrong session: still counts for the one it's in.
          { session: "cccccccc", quote: "Open the PR against the DEV branch" },
        ],
      },
      { title: "Made up", for: "you", body: "## Decided\n- x", evidence: [{ session: "aaaaaaaa", quote: "never said anything like this" }, { session: "bbbbbbbb", quote: "nor this one either" }] },
      { title: "Only once", for: "you", body: "## Decided\n- y", evidence: [{ session: "cccccccc", quote: "something else entirely" }] },
    ],
    sessions,
  );
  assert.equal(out.length, 1);
  assert.equal(out[0]!.title, "Open PRs against dev");
  assert.deepEqual(out[0]!.sessions, ["aaaaaaaa-1", "bbbbbbbb-2"]);
  assert.equal(out[0]!.last, "2026-10-09");
});

test("a finding needs its quotes on two different days: two restarts one morning are one, a long session typed into on two days is two", () => {
  const ask = "write the reddit post about the launch";
  const restarts = [
    { id: "r1111111-a", at: "2026-10-09T09:00:00Z", prompts: [{ text: ask, at: "2026-10-09T09:00:00Z" }] },
    { id: "r2222222-b", at: "2026-10-09T09:05:00Z", prompts: [{ text: ask, at: "2026-10-09T09:05:00Z" }] },
  ];
  const raw = [{ title: "Write the launch post", for: "you", body: "## Decided\n- x", evidence: [{ session: "r1111111", quote: ask }, { session: "r2222222", quote: ask }] }];
  assert.deepEqual(verify(raw, restarts), [], "one morning's restart is one occasion");

  const long = [{ id: "l3333333-c", at: "2026-10-01T10:00:00Z", prompts: [{ text: "remove the em dash please", at: "2026-10-01T10:00:00Z" }, { text: "again, remove the em dash", at: "2026-10-04T10:00:00Z" }] }];
  const kept = verify([{ title: "No em dashes", for: "you", body: "## Decided\n- y", evidence: [{ session: "l3333333", quote: "remove the em dash" }, { session: "l3333333", quote: "remove the em dash please" }] }], long);
  assert.equal(kept.length, 1);
  assert.equal(kept[0]!.days, 2);
  assert.deepEqual(kept[0]!.sessions, ["l3333333-c"]);
  assert.equal(kept[0]!.last, "2026-10-04");
});

test("anything like a credential or an email is scrubbed before a learning is written", () => {
  const out = scrub("use ghp_abcdefghijklmnopqrstuvwxyz1234 and password: hunter2 for [email protected], key AKIAABCDEFGHIJKLMNOP");
  assert.ok(!out.includes("ghp_"));
  assert.ok(!out.includes("hunter2"));
  assert.ok(!out.includes("[email protected]"));
  assert.ok(!out.includes("AKIA"));
});

test("a finding whose title, body or quotes hold a secret is left out whole, and counted, not scrubbed and kept", () => {
  const day = (d: number) => `2026-10-0${d}T10:00:00Z`;
  const sessions = [
    { id: "s1111111-a", at: day(1), prompts: [{ text: "push with ghp_abcdefghijklmnopqrstuvwxyz0123456789 when https fails", at: day(1) }, { text: "always run go test with -race first", at: day(1) }] },
    { id: "s2222222-b", at: day(3), prompts: [{ text: "again push with ghp_abcdefghijklmnopqrstuvwxyz0123456789 when https fails", at: day(3) }, { text: "please always run go test with -race first", at: day(3) }] },
  ];
  const ev = (quote: string) => [{ session: "s1111111", quote }, { session: "s2222222", quote }];
  const found = verify(
    [
      { title: "Push with the saved token", for: "you", body: "## Decided\n- Push over HTTPS.", evidence: ev("ghp_abcdefghijklmnopqrstuvwxyz0123456789 when https fails") },
      { title: "Set the key", for: "you", body: "## Decided\n- export TRAIL_API_KEY=nn3f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8", evidence: ev("always run go test with -race first") },
      { title: "Run go test with -race", for: "team", body: "## Decided\n- Run `go test -race ./...` first.", evidence: ev("always run go test with -race first") },
    ],
    sessions,
  );
  assert.equal(found.length, 3, "verify only checks the quotes are there");
  assert.ok(found[1]!.body.includes("TRAIL_API_KEY=nn3f9a"), "nothing is scrubbed in place");
  const { findings, leftOut } = withoutSecrets(found);
  assert.deepEqual(findings.map((f) => f.title), ["Run go test with -race"]);
  assert.equal(leftOut, 2);
});

test("a quote Claude copied without its punctuation still carries the secret it came from: the finding is left out", () => {
  // The typed words hold a key; the cited quote matches them once punctuation and case are set aside, and looks clean.
  const day = (d: number) => `2026-10-0${d}T10:00:00Z`;
  const key = "export TRAIL_API_KEY=Zk3q9XvB2mN8pL4tR7wY1sD6 before the deploy";
  const sessions = [
    { id: "s1111111-a", at: day(1), prompts: [{ text: key, at: day(1) }] },
    { id: "s2222222-b", at: day(3), prompts: [{ text: `again: ${key}`, at: day(3) }] },
  ];
  const quote = "export trail api key zk3q9xvb2mn8pl4tr7wy1sd6 before the deploy";
  const found = verify([{ title: "Set the key before deploying", for: "you", body: "## Decided\n- Set the key first.", evidence: [{ session: "s1111111", quote }, { session: "s2222222", quote }] }], sessions);
  assert.equal(found.length, 1, "the quote is really there");
  const { findings, leftOut } = withoutSecrets(found);
  assert.deepEqual(findings, []);
  assert.equal(leftOut, 1);
});

test("the closing lines name who works there and the head start, or a faster PR when it's under 80k tokens", () => {
  assert.equal(PERSONAL_SAVED_LINE, "📝 Saved just for you · stays on this machine, out of the repo");
  const five = commitLines({ cost: { tokens: 96000 } }, ["Anay", "Rushil", "Ritika", "Rohan", "Kumar"]);
  assert.equal(five.uncommitted, "🌱 Anay, Rushil and 3 others work in this part of the codebase. Commit what you learned and give their agents a 96k-token head start");
  assert.equal(five.committed, "📝 Committed · Anay, Rushil and 3 others work in this part of the codebase, and their agents now get a 96k-token head start");
  assert.equal(commitLines({ cost: { tokens: 80_000 } }, []).uncommitted, "🌱 Commit what you learned and give your teammates' agents an 80k-token head start");
  const small = commitLines({ cost: { tokens: 79_999 } }, ["Anay", "Rushil", "Ritika", "Rohan", "Kumar"]);
  assert.equal(small.uncommitted, "🌱 Anay, Rushil and 3 others work in this part of the codebase. Commit what you learned and their agents get to a PR 3x faster");
  assert.equal(small.committed, "📝 Committed · Anay, Rushil and 3 others work in this part of the codebase, and their agents now get to a PR 3x faster");
  assert.equal(commitLines({}, [], "repo").uncommitted, "🌱 Commit what you learned and your teammates' agents get to a PR 3x faster");
  assert.equal(commitLines({}, ["Anay"], "repo").uncommitted, "🌱 Anay works in this repo. Commit what you learned and their agents get to a PR 3x faster");
  assert.equal(namesLabel(["Anay", "Rushil", "Ritika"]), "Anay, Rushil and Ritika");
});

test("teammates are the recent authors of the files, most commits first, never you or a bot", () => {
  const d = tmpRepo("teammates");
  const g = (...args: string[]) => spawnSync("git", ["-c", "commit.gpgsign=false", ...args], { cwd: d });
  g("init", "-q");
  g("config", "user.name", "Priya Raman");
  g("config", "user.email", "[email protected]");
  const commit = (who: string, email: string, file: string, n: number) => {
    for (let i = 0; i < n; i++) {
      writeFileSync(join(d, file), `${who} ${i}\n`);
      g("add", file);
      g("-c", `user.name=${who}`, "-c", `user.email=${email}`, "commit", "-qm", `${who} ${i}`);
    }
  };
  commit("Priya Raman", "[email protected]", "a.go", 3);
  commit("Rushil Jain", "[email protected]", "a.go", 1);
  commit("Anay Shah", "[email protected]", "a.go", 2);
  commit("dependabot[bot]", "49699333+dependabot[bot]@users.noreply.github.com", "a.go", 4);
  commit("Kumar", "[email protected]", "b.go", 1);
  assert.deepEqual(teammatesOn(d, ["a.go"]), ["Anay", "Rushil"]);
  const all = teammatesOn(d);
  assert.equal(all[0], "Anay", "most commits first");
  assert.deepEqual([...all].sort(), ["Anay", "Kumar", "Rushil"], "the whole repo when no files are named");
});

/* ---- trail init, end to end, with a stand-in for Claude Code on PATH ---- */

/** A `claude` that answers --version, and answers -p with two findings citing the transcripts below. */
function fakeClaude(): string {
  const bin = mkdtempSync(join(tmpdir(), "fake-claude-"));
  const answer = {
    is_error: false,
    total_cost_usd: 0.01,
    structured_output: {
      findings: [
        {
          title: "Run go test with -race before pushing",
          for: "team",
          body: "## Decided\n- Run `go test -race ./...` before every push; CI runs it too.",
          evidence: [
            { session: "aaaaaaaa", quote: "always run go test with -race before pushing" },
            { session: "bbbbbbbb", quote: "always run go test with -race before pushing" },
          ],
        },
        {
          title: "Say what you understood before building",
          for: "you",
          body: "## Decided\n- Restate the task in a few lines and wait for a yes.",
          evidence: [
            { session: "aaaaaaaa", quote: "tell me what you understood first" },
            { session: "bbbbbbbb", quote: "tell me what you understood first" },
          ],
        },
      ],
    },
  };
  writeFileSync(
    join(bin, "claude"),
    `#!/usr/bin/env node\nif (process.argv.includes("--version")) { require("fs").appendFileSync(${JSON.stringify(join(bin, "version-calls"))}, "v\\n"); console.log("9.9.9"); process.exit(0); }\nrequire("fs").appendFileSync(${JSON.stringify(join(bin, "calls"))}, "-p\\n");\nprocess.stdin.resume(); process.stdin.on("end", () => console.log(${JSON.stringify(JSON.stringify(answer))}));\n`,
  );
  chmodSync(join(bin, "claude"), 0o755);
  return bin;
}

/** How many times the stand-in was asked. */
const calls = (bin: string) => (existsSync(join(bin, "calls")) ? readFileSync(join(bin, "calls"), "utf8").split("\n").filter(Boolean).length : 0);

/** The repo's folder under a test HOME's ~/.trail, without touching this process's TRAIL_HOME. */
function ensureRepoHomeAt(home: string, repo: string): string {
  const saved = process.env.TRAIL_HOME;
  process.env.TRAIL_HOME = join(home, ".trail");
  try {
    return ensureRepoHome(repo).place.dir;
  } finally {
    if (saved === undefined) delete process.env.TRAIL_HOME;
    else process.env.TRAIL_HOME = saved;
  }
}

function initRun(repo: string, home: string, bin: string, args: string[] = [], env: NodeJS.ProcessEnv = {}) {
  return trailRun(repo, home, bin, ["init", repo, "--agents", "claude", "--no-build", "--no-global", ...args], env);
}

function trailRun(repo: string, home: string, bin: string, args: string[], env: NodeJS.ProcessEnv = {}) {
  // tsx by its full address: the command runs from inside the repo.
  const r = spawnSync(process.execPath, ["--import", import.meta.resolve("tsx"), join(process.cwd(), "src", "bin", "trail.ts"), ...args], {
    encoding: "utf8",
    cwd: repo,
    env: {
      ...process.env,
      HOME: home,
      USERPROFILE: home,
      TRAIL_HOME: join(home, ".trail"),
      PATH: `${bin}:${process.env.PATH}`,
      DO_NOT_TRACK: "1",
      TRAIL_NO_FETCH: undefined,
      TRAIL_NO_LOOK_BACK: undefined,
      CLAUDECODE: undefined,
      TRAIL_INVOKED_AS: undefined,
      ...env,
    },
  });
  return { status: r.status, err: r.stderr };
}

/** A repo with two past sessions, on two days, each telling Claude the same two things. */
function repoWithHistory(tag: string, home: string): string {
  const repo = tmpRepo(tag);
  spawnSync("git", ["init", "-q"], { cwd: repo });
  const projects = claudeProjectDir(repo, home);
  mkdirSync(projects, { recursive: true });
  // Two sessions on two different days: a restart the same morning would count once.
  for (const [id, at] of [["aaaaaaaa-1111", "2026-10-01T10:00:00Z"], ["bbbbbbbb-2222", "2026-10-03T10:00:00Z"]]) {
    writeFileSync(
      join(projects, `${id}.jsonl`),
      transcript([
        user("tell me what you understood first", { cwd: repo, timestamp: at }),
        said("I pushed it."),
        user("never use em dashes in the copy", { cwd: repo, timestamp: at }),
      ]),
    );
  }
  return repo;
}

const learningFiles = (repo: string) => (existsSync(join(repo, ".trail", "learnings")) ? readdirSync(join(repo, ".trail", "learnings")).filter((f) => f.endsWith(".md")) : []);

// The stand-in for Claude Code is a shebang script, which Windows won't run as `claude`.
// 1b (R60, P2, R23): no find call any more. A run with no terminal relays what the no-model look-back found; an
// agent's init never starts claude; `trail keep` keeps nothing without the receipt its PreToolUse check writes.
// (Whether a spawned run with no TTY is the person's script or an agent depends on the process tree the suite runs
// in, so these runs set CLAUDECODE; init-run.test.ts covers the script and the screen in process.)
test("run by an agent, trail init looks back with no model and relays the person's own line once; claude is never started", { skip: process.platform === "win32" }, () => {
  const home = mkdtempSync(join(tmpdir(), "cold-agent-home-"));
  const repo = repoWithHistory("cold-agent", home);
  const bin = fakeClaude();
  const r = initRun(repo, home, bin, [], { CLAUDECODE: "1" });
  assert.equal(r.status, 0, r.err);
  assert.match(r.err, /· looking back at your past Claude Code sessions here \(about a minute\)/);
  assert.match(r.err, /✓ looked back at 2 Claude Code sessions about this repo, typed into on 2 days \(Oct 1 to Oct 3\)/);
  assert.equal(r.err.match(/Show the list as written/g)?.length, 1, "printed once");
  assert.match(r.err, /\n1\. "never use em dashes in the copy" \(preference, your own words\) · You said this on 2 days · just for you, in every repo\n/);
  assert.match(r.err, /Keep: trail keep <numbers> · none: trail keep none\n/);
  assert.doesNotMatch(r.err, /skills are off/, "skills are on by default: no line saying how to turn them on");
  assert.doesNotMatch(r.err, /—|for your team|\bnotes?\b|\brules?\b|\bmemory\b|\bworkflows?\b/i, "init's words: learnings, no em dashes");
  assert.equal(calls(bin), 0, "Claude Code was never asked");
  assert.ok(!existsSync(join(bin, "version-calls")), "no claude process at all, not even claude --version");
  assert.deepEqual(learningFiles(repo), [], "nothing in the repo");

  const kept = trailRun(repo, home, bin, ["keep", "1"], { CLAUDECODE: "1" });
  assert.equal(kept.status, 1, kept.err);
  assert.match(kept.err, /Nothing kept: Trail couldn't find the person's answer after the list\./);
  assert.ok(!existsSync(join(home, ".trail", "learnings")), "no receipt, nothing kept");
});

test("an agent's trail init --yes keeps nothing (R25)", { skip: process.platform === "win32" }, () => {
  const home = mkdtempSync(join(tmpdir(), "cold-yes-home-"));
  const repo = repoWithHistory("cold-yes", home);
  const r = initRun(repo, home, fakeClaude(), ["--yes"], { CLAUDECODE: "1" });
  assert.equal(r.status, 0, r.err);
  assert.match(r.err, /found 0 skills, 0 guardrails and 1 preference\. Kept nothing: an agent ran this\./);
  assert.ok(!existsSync(join(home, ".trail", "learnings")));
  assert.deepEqual(learningFiles(repo), []);
});

test("TRAIL_NO_FETCH leaves the look-back on (nothing is fetched); TRAIL_NO_LOOK_BACK turns it off", { skip: process.platform === "win32" }, () => {
  const home = mkdtempSync(join(tmpdir(), "cold-switch-home-"));
  const off = repoWithHistory("cold-switch-off", home);
  const bin = fakeClaude();
  const r = initRun(off, home, bin, [], { TRAIL_NO_LOOK_BACK: "1", CLAUDECODE: "1" });
  assert.equal(r.status, 0, r.err);
  assert.doesNotMatch(r.err, /looking back/);
  const on = repoWithHistory("cold-switch-on", home);
  const r2 = initRun(on, home, bin, [], { TRAIL_NO_FETCH: "1", CLAUDECODE: "1" });
  assert.match(r2.err, /looking back at your past Claude Code sessions/);
  assert.equal(calls(bin), 0);
});

/* ---- finding Claude Code when it isn't on PATH ---- */

const exe = process.platform === "win32" ? "claude.exe" : "claude";
const extCopy = (editor: string, folder: string) => join(editor, "extensions", folder, "resources", "native-binary", exe);

/** A fake home with an empty file at each of `paths`. */
function homeWith(...paths: string[]): string {
  const home = mkdtempSync(join(tmpdir(), "claude-bin-home-"));
  for (const p of paths) {
    mkdirSync(join(home, dirname(p)), { recursive: true });
    writeFileSync(join(home, p), "");
  }
  return home;
}

test("claudeBin uses claude on PATH when it's there", () => {
  assert.equal(claudeBin(homeWith(extCopy(".vscode", "anthropic.claude-code-2.1.289-darwin-arm64")), () => true), "claude");
});

test("claudeBin finds the newest VS Code or Cursor extension copy when claude isn't on PATH", () => {
  const newest = extCopy(".cursor", "anthropic.claude-code-2.1.296-darwin-arm64");
  const home = homeWith(
    extCopy(".vscode", "anthropic.claude-code-2.1.99-darwin-arm64"),
    extCopy(".vscode", "anthropic.claude-code-2.1.289-darwin-arm64"),
    newest,
  );
  assert.equal(claudeBin(home, () => false), join(home, newest));
});

test("claudeBin prefers a standalone install to an extension's copy", () => {
  const home = homeWith(join(".local", "bin", exe), extCopy(".vscode", "anthropic.claude-code-2.1.289-darwin-arm64"));
  assert.equal(claudeBin(home, () => false), join(home, ".local", "bin", exe));
});

test("claudeBin skips an extension folder without the binary, and is null with nothing to run", () => {
  const home = homeWith();
  mkdirSync(join(home, ".vscode", "extensions", "anthropic.claude-code-2.1.300-darwin-arm64"), { recursive: true });
  assert.equal(claudeBin(home, () => false), null);
});

/* ---- ticking which learnings to keep ---- */