Skip to content

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

feat(brain): send CLAUDE.md and the newest PRs first so suggestions start early (#466)

anirudhkumar-nanonets6d0ecc2e58c7
diff --git a/src/app/history.ts b/src/app/history.ts
index de192ba1..b2677e06 100644
--- a/src/app/history.ts
+++ b/src/app/history.ts
@@ -169,6 +169,9 @@ export async function readThreads(
fetchImpl: Fetch,
api = "https://api.github.com",
max = MAX_THREADS,
+ // Threads already read (the early upload's newest ones), reused rather than
+ // fetched a second time.
+ known: ReadonlyMap<number, HistoryThread> = new Map(),
): Promise<HistoryThread[]> {
const headers = ghHeaders(token);
@@ -197,6 +200,8 @@ export async function readThreads(
const slice = candidates.slice(i, i + THREAD_FETCH_CONCURRENCY);
const fetched = await Promise.all(
slice.map(async (p) => {
+ const seen = known.get(p.number);
+ if (seen) return seen;
const [issueComments, reviewComments] = await Promise.all([
readComments(`${api}/repos/${owner}/${repo}/issues/${p.number}/comments`, headers, fetchImpl),
readComments(`${api}/repos/${owner}/${repo}/pulls/${p.number}/comments`, headers, fetchImpl),
diff --git a/src/brain/push.ts b/src/brain/push.ts
index d641cfec..9cbf5d01 100644
--- a/src/brain/push.ts
+++ b/src/brain/push.ts
@@ -20,6 +20,7 @@ import {
readCommits,
readSymbols,
readThreads,
+ type HistoryThread,
type RepoDigest,
} from "../app/history.js";
import {
@@ -114,6 +115,8 @@ export interface ExpectedRepo {
slug: string;
status: string;
brainName: string;
+ /** The brain accepts an early upload (see pushEarlyDigest). */
+ earlyUpload: boolean;
}
/**
@@ -135,9 +138,18 @@ export async function fetchExpectedRepo(link: BrainLink, fetchImpl: typeof fetch
signal: AbortSignal.timeout(5000),
});
if (!res.ok) return null;
- const body = (await res.json()) as { repo?: { slug?: string; status?: string } | null; brain_name?: string };
+ const body = (await res.json()) as {
+ repo?: { slug?: string; status?: string } | null;
+ brain_name?: string;
+ early_upload?: boolean;
+ };
if (!body.repo?.slug) return null;
- return { slug: body.repo.slug, status: String(body.repo.status ?? ""), brainName: String(body.brain_name ?? "") };
+ return {
+ slug: body.repo.slug,
+ status: String(body.repo.status ?? ""),
+ brainName: String(body.brain_name ?? ""),
+ earlyUpload: body.early_upload === true,
+ };
} catch {
return null;
}
@@ -148,11 +160,84 @@ export function sameRepo(a: string, b: string): boolean {
return a.trim().toLowerCase() === b.trim().toLowerCase();
}
+/** How many of the newest pull requests and commits the early upload carries —
+ * what Trail's quick CLAUDE.md pass reads, and no more. */
+export const EARLY_THREADS = 30;
+export const EARLY_COMMITS = 80;
+
+/**
+ * The early upload: the instruction files, the newest pull requests and the
+ * newest commits, read before the rest of the history.
+ *
+ * Reading the history is most of a push's wait — up to 200 pull requests at two
+ * GitHub calls each — and Trail's first CLAUDE.md suggestions need none of it
+ * beyond the newest few. Sent first, they start while the full read is still
+ * going here, and the full upload that follows mines as before.
+ *
+ * Returns the threads it read, so the full read reuses them instead of asking
+ * GitHub twice. Null when there is nothing worth sending early.
+ */
+export async function buildEarlyDigest(
+ root: string,
+ opts: { fetchImpl?: typeof fetch } = {},
+): Promise<{ digest: RepoDigest; threads: HistoryThread[] } | null> {
+ const slug = repoSlugFromGit(root);
+ if (!slug) return null;
+ const fetchImpl = opts.fetchImpl ?? fetch;
+ const token = githubToken();
+ // Oldest first, like the full read, so the newest are the tail.
+ const commits = readCommits(root).slice(-EARLY_COMMITS);
+ if (commits.length === 0) return null;
+ let threads: HistoryThread[] = [];
+ if (token) {
+ try {
+ threads = await readThreads(slug.owner, slug.name, token, fetchImpl as never, undefined, EARLY_THREADS);
+ } catch {
+ threads = [];
+ }
+ }
+ const digest = buildDigest({
+ owner: slug.owner,
+ name: slug.name,
+ headSha: git(root, ["rev-parse", "HEAD"]) ?? "",
+ defaultBranch: currentBranch(root),
+ isPrivate: await isPrivate(slug.owner, slug.name, token, fetchImpl),
+ commits,
+ threads,
+ symbols: [],
+ sources: budgetSources(readAgentInstructions(root)),
+ autoApprove: true,
+ });
+ return { digest, threads };
+}
+
+/** Send the early upload. Best-effort: false on any failure, and the full
+ * upload still does everything. */
+export async function pushEarlyDigest(link: BrainLink, digest: RepoDigest, fetchImpl: typeof fetch = fetch): Promise<boolean> {
+ const url = `${baseUrlFor(link)}/api/public/brains/${encodeURIComponent(link.brainId)}/repo?stage=early`;
+ try {
+ const res = await fetchImpl(url, {
+ method: "POST",
+ headers: {
+ authorization: `Bearer ${link.token}`,
+ "content-type": "application/json",
+ accept: "application/json",
+ },
+ body: JSON.stringify(digest),
+ signal: AbortSignal.timeout(15_000),
+ });
+ if (!res.ok) return false;
+ return ((await res.json()) as { early?: boolean }).early === true;
+ } catch {
+ return false;
+ }
+}
+
/** Build the digest for the checkout at `root`. Reads nothing but text. */
export async function buildLocalDigest(
root: string,
graph: GraphV1 | null,
- opts: { autoApprove?: boolean; fetchImpl?: typeof fetch } = {},
+ opts: { autoApprove?: boolean; fetchImpl?: typeof fetch; knownThreads?: HistoryThread[] } = {},
): Promise<{ digest: RepoDigest; warning?: string } | { error: string }> {
const slug = repoSlugFromGit(root);
if (!slug) {
@@ -171,7 +256,8 @@ export async function buildLocalDigest(
let warning: string | undefined;
if (token) {
try {
- threads = await readThreads(slug.owner, slug.name, token, fetchImpl as never);
+ const known = new Map((opts.knownThreads ?? []).map((t) => [t.number, t]));
+ threads = await readThreads(slug.owner, slug.name, token, fetchImpl as never, undefined, undefined, known);
} catch {
warning = "could not read pull-request discussion; mining commits and repo files only";
}
diff --git a/src/cli.ts b/src/cli.ts
index 4ca77ff1..c1037526 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -20,7 +20,16 @@ import { hostIds } from "./hosts/registry.js";
import { parseBrainArg, connectBrain, pullBrain, brainStatus } from "./brain/connect.js";
import { rulesForPointers } from "./brain/attach.js";
import { clearLink, type BrainLink } from "./brain/link.js";
-import { buildLocalDigest, fetchExpectedRepo, pushDigest, repoSlugFromGit, sameRepo } from "./brain/push.js";
+import {
+ buildEarlyDigest,
+ buildLocalDigest,
+ fetchExpectedRepo,
+ pushDigest,
+ pushEarlyDigest,
+ repoSlugFromGit,
+ sameRepo,
+} from "./brain/push.js";
+import type { HistoryThread } from "./app/history.js";
import { readLink, writeLink } from "./brain/link.js";
import { watchBuild } from "./brain/watch.js";
import { openBrowser, signupUrl, startHandoff } from "./brain/signup.js";
@@ -1392,7 +1401,23 @@ brain
const label = expected?.slug ?? (here ? `${here.owner}/${here.name}` : "this repository");
console.error(`· reading ${label} — commit messages, pull-request discussion and the docs in the tree.`);
console.error(" No file contents leave this machine.");
- const built = await buildLocalDigest(repo, graph, { autoApprove: opts.approve !== false });
+ // The instruction file and the newest pull requests go first, when the brain
+ // takes them: its CLAUDE.md suggestions start from those while the rest of
+ // the history is still being read here. Not awaited — the full read starts
+ // at once, reusing the threads the early one already fetched.
+ let early: Promise<unknown> = Promise.resolve();
+ let knownThreads: HistoryThread[] = [];
+ if (expected?.earlyUpload) {
+ const first = await buildEarlyDigest(repo);
+ if (first) {
+ knownThreads = first.threads;
+ early = pushEarlyDigest(link, first.digest).then((ok) => {
+ if (ok) console.error("· CLAUDE.md suggestions are on their way in your browser, from the newest pull requests");
+ });
+ }
+ }
+ const built = await buildLocalDigest(repo, graph, { autoApprove: opts.approve !== false, knownThreads });
+ await early;
if ("error" in built) {
console.error(`✗ ${built.error}`);
process.exitCode = 1;
diff --git a/test/brain-early-upload.test.ts b/test/brain-early-upload.test.ts
new file mode 100644
index 00000000..52613dd3
--- /dev/null
+++ b/test/brain-early-upload.test.ts
@@ -0,0 +1,73 @@
+/**
+ * The early upload sends the instruction file and the newest pull requests
+ * before the rest of the history, so Trail's first CLAUDE.md suggestions start
+ * while the full read is still on this machine. Two things make that safe, and
+ * both are tested here: it is only sent to a brain that says it takes it, and
+ * the full read does not ask GitHub again for threads the early one read.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { fetchExpectedRepo, pushEarlyDigest } from '../src/brain/push.js';
+import { readThreads, type HistoryThread, type RepoDigest } from '../src/app/history.js';
+import type { BrainLink } from '../src/brain/link.js';
+
+const link = { brainId: 'b1', token: 'gbt_1.x', baseUrl: 'http://trail.test' } as unknown as BrainLink;
+
+const json = (body: unknown, status = 200) =>
+ new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+
+// --- only to a brain that takes it -------------------------------------------
+
+// An older Trail ignores ?stage=early and would read the partial history as a
+// whole ingest, then refuse the real one as already running. So the flag is
+// read, and absent means no.
+test('a brain that does not say it takes the early upload is not sent one', async () => {
+ const older = await fetchExpectedRepo(link, (async () => json({ repo: { slug: 'chalk/chalk', status: 'pending' } })) as typeof fetch);
+ assert.equal(older?.earlyUpload, false);
+
+ const newer = await fetchExpectedRepo(link, (async () =>
+ json({ repo: { slug: 'chalk/chalk', status: 'pending' }, early_upload: true })) as typeof fetch);
+ assert.equal(newer?.earlyUpload, true);
+});
+
+test('the early upload is posted with ?stage=early and reports whether Trail took it', async () => {
+ let url = '';
+ const took = await pushEarlyDigest(link, { owner: 'chalk', name: 'chalk' } as RepoDigest, (async (u: string) => {
+ url = u;
+ return json({ early: true }, 202);
+ }) as typeof fetch);
+ assert.equal(took, true);
+ assert.match(url, /\/api\/public\/brains\/b1\/repo\?stage=early$/);
+
+ const ignored = await pushEarlyDigest(link, {} as RepoDigest, (async () => json({ early: false }, 202)) as typeof fetch);
+ assert.equal(ignored, false, 'a brain without the CLAUDE.md step accepts and ignores it');
+
+ const refused = await pushEarlyDigest(link, {} as RepoDigest, (async () => json({ error: 'no' }, 409)) as typeof fetch);
+ assert.equal(refused, false);
+
+ const down = await pushEarlyDigest(link, {} as RepoDigest, (async () => {
+ throw new Error('ECONNREFUSED');
+ }) as typeof fetch);
+ assert.equal(down, false, 'best-effort: the full upload still does everything');
+});
+
+// --- no second read of the same threads --------------------------------------
+
+test('the full read reuses threads the early upload already fetched', async () => {
+ const fetched: string[] = [];
+ const fake = (async (u: string) => {
+ fetched.push(u);
+ if (u.includes('/pulls?state=closed')) {
+ return json(u.includes('page=1') ? [{ number: 2, title: 'two' }, { number: 1, title: 'one' }] : []);
+ }
+ return json([{ body: 'use the whole test script', user: { login: 'dev', type: 'User' } }]);
+ }) as never;
+
+ const early: HistoryThread = { number: 2, title: 'two', body: '', mergeSha: '', comments: [{ body: 'from the early read' }] };
+ const threads = await readThreads('chalk', 'chalk', 'tok', fake, 'https://api.test', 200, new Map([[2, early]]));
+
+ assert.equal(threads.find((t) => t.number === 2)?.comments[0]?.body, 'from the early read');
+ assert.ok(threads.some((t) => t.number === 1), 'the rest is still read');
+ assert.ok(!fetched.some((u) => /\/(issues|pulls)\/2\/comments/.test(u)), 'no comment request for #2');
+ assert.ok(fetched.some((u) => /\/(issues|pulls)\/1\/comments/.test(u)));
+});