Skip to content

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

feat(trail): show how many changes were suggested in graft trail pull (#507)

anirudhkumar-nanonets5c3a67465732
diff --git a/TELEMETRY.md b/TELEMETRY.md
index 2ec25284..166788ee 100644
--- a/TELEMETRY.md
+++ b/TELEMETRY.md
@@ -48,7 +48,7 @@ The events:
| `query` | `command`, `surface` (`cli`/`mcp`/`hook`), `hit` (`ask` only) | Any query command |
| `brain_signup_opened` | `mode` (`terminal`/`agent`) | `graft trail push` on a repo with no brain opens your browser to make one |
| `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`bad_callback`/`stopped`, and for an agent-run push `agent_link_opened`/`still_waiting`/`expired`/`unsupported`), `mode` (`terminal`/`agent`), `duration_bucket` | That handoff ends, one way or the other — for an agent-run push, each of its runs |
-| `trail_pulled` | `outcome` (`written`/`already_present`/`nothing_accepted`/`skipped`/`error`/`dry_run`), `kinds` (which kinds of context file were written: `claude_md`, `folder_claude_md`, `agents_md`, `cursor_rule`, `skill`), `files_bucket`, `changes_bucket`, `skipped_bucket` | `graft trail pull` (or `graft claude-md pull`) finishes |
+| `trail_pulled` | `outcome` (`written`/`already_present`/`nothing_accepted`/`skipped`/`error`/`dry_run`), `kinds` (which kinds of context file were written: `claude_md`, `folder_claude_md`, `agents_md`, `cursor_rule`, `skill`), `files_bucket`, `changes_bucket`, `skipped_bucket`, `suggested_bucket` (every change Trail has suggested for the wired agents' files, whatever became of it) | `graft trail pull` (or `graft claude-md pull`) finishes |
| `session_summary` | `graft_reads_bucket`, `source_reads_bucket`, `saved_tokens_bucket`, `graft_turns_bucket`, `reported_turns_bucket` | Once, after an agent session ends |
Two rules govern every value above, and both are enforced in code rather than by
diff --git a/src/brain/pull.ts b/src/brain/pull.ts
index 09b3319d..f91ba6e8 100644
--- a/src/brain/pull.ts
+++ b/src/brain/pull.ts
@@ -19,12 +19,14 @@ import {
markContextFilesApplied,
planContextFile,
readByWired,
+ readersOf,
writePlannedFile,
type ContextFile,
type FilePlan,
} from "./context-files.js";
import type { BrainLink } from "./link.js";
import { reviewUrl } from "./signup.js";
+import { fetchRepoState, type Suggestions } from "./watch.js";
import { CONTEXT_FILE_KINDS, countBucket, type TrailPullOutcome } from "../telemetry/contract.js";
import { track } from "../telemetry/track.js";
@@ -55,6 +57,71 @@ export function rulesLine(repo: string, res: ConnectResult): string | null {
return `✓ ${rules} refreshed in ${where}`;
}
+/** `a, b and c`. */
+function joinAnd(items: string[]): string {
+ if (items.length <= 1) return items.join("");
+ return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+
+/**
+ * Trail's suggestions, cut to the files the wired agents read: how many, and
+ * whose files they are (`the files claude and cursor read`).
+ *
+ * Every suggestion Trail has made, whatever became of it — the counts it sends
+ * do not say which are still waiting for review and which were dismissed.
+ */
+export function suggestedFor(s: Suggestions | undefined, wired: string[]): { count: number; whose: string } {
+ if (!s) return { count: 0, whose: "" };
+ let count = 0;
+ const kinds = new Set<string>();
+ if (s.claudeMd > 0 && readByWired("claude_md", wired)) {
+ count += s.claudeMd;
+ kinds.add("claude_md");
+ }
+ if (s.files) {
+ for (const f of s.files) {
+ if (f.changes <= 0 || !readByWired(f.kind, wired)) continue;
+ count += f.changes;
+ kinds.add(f.kind);
+ }
+ } else if (s.contextFiles > 0) {
+ // No per-file list from this Trail, so no way to cut it to the wired agents'
+ // files: the count is Trail's total.
+ count += s.contextFiles;
+ for (const k of ["agents_md", "folder_claude_md", "cursor_rule", "skill"]) kinds.add(k);
+ }
+ const readers = wired.length
+ ? wired.filter((w) => [...kinds].some((k) => readersOf(k, [w]).length > 0))
+ : [];
+ return { count, whose: readers.length ? `the files ${joinAnd(readers)} read` : "this repo's context files" };
+}
+
+/**
+ * The suggestions line after a build:
+ * `● 18 suggestions for the files claude, agents and cursor read`. Null when
+ * there are none to mention.
+ */
+export function suggestionsLine(s: Suggestions | undefined, wired: string[], again: boolean): string | null {
+ const { count, whose } = suggestedFor(s, wired);
+ if (count === 0) return null;
+ return `● ${count.toLocaleString("en-US")} ${again ? "new " : ""}suggestion${count === 1 ? "" : "s"} for ${whose}`;
+}
+
+/**
+ * What a pull says about the suggestions it did not write:
+ * `● 20 suggested so far for the files claude read, 2 of them accepted`.
+ *
+ * This is what lets an agent watching the trail say "there are suggestions
+ * waiting for you" before anything has been accepted. "So far", because the
+ * build keeps adding them after the push returns. Null when Trail sent no
+ * counts, or counts that cannot hold what was accepted.
+ */
+export function suggestedLine(suggested: { count: number; whose: string }, accepted: number): string | null {
+ if (suggested.count === 0 || suggested.count < accepted) return null;
+ const taken = accepted === 0 ? "none accepted yet" : `${accepted.toLocaleString("en-US")} of them accepted`;
+ return `● ${suggested.count.toLocaleString("en-US")} suggested so far for ${suggested.whose}, ${taken}`;
+}
+
/** Everything the pull will write, file by file, with where each change came from. */
interface Planned {
plan: FilePlan;
@@ -66,7 +133,7 @@ interface Planned {
* The `trail_pulled` event for one pull. Only the outcome, which kinds of file
* were written, and bucketed counts leave the machine — see TELEMETRY.md.
*/
-function trackPull(repo: string, home: string | undefined, outcome: TrailPullOutcome, planned: Planned[] = []): void {
+function trackPull(repo: string, home: string | undefined, outcome: TrailPullOutcome, planned: Planned[] = [], suggested = 0): void {
const wrote = planned.filter((p) => p.plan.status && p.plan.written.length > 0);
const kinds = [...new Set(wrote.map((p) => p.kind))]
.filter((k) => (CONTEXT_FILE_KINDS as readonly string[]).includes(k))
@@ -80,6 +147,7 @@ function trackPull(repo: string, home: string | undefined, outcome: TrailPullOut
files_bucket: countBucket(wrote.length),
changes_bucket: countBucket(wrote.reduce((n, p) => n + p.plan.written.length, 0)),
skipped_bucket: countBucket(planned.reduce((n, p) => n + p.plan.skipped.length, 0)),
+ suggested_bucket: countBucket(suggested),
},
{ repo, home },
);
@@ -92,6 +160,9 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOpti
const write = opts.write ?? ((l: string) => console.error(l));
const fetchImpl = opts.fetchImpl ?? fetch;
let code = 0;
+ // Read beside everything else: it only adds a line, and a Trail that cannot
+ // answer it costs the pull nothing.
+ const repoState = fetchRepoState(link, fetchImpl);
// 1. The rules. Skipped on a dry run, which writes nothing at all.
if (!opts.dryRun) {
@@ -135,12 +206,20 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOpti
}
}
+ const suggested = suggestedFor((await repoState)?.suggestions, opts.wired);
+ const waiting = suggestedLine(suggested, accepted);
+
if (accepted === 0) {
if (code === 0) {
- write("· nothing accepted in Trail yet — review:");
- write(` ${reviewUrl(link.brainId)}`);
+ if (waiting) {
+ write(waiting);
+ write(` review: ${reviewUrl(link.brainId)}`);
+ } else {
+ write("· nothing accepted in Trail yet — review:");
+ write(` ${reviewUrl(link.brainId)}`);
+ }
}
- trackPull(repo, opts.home, code === 0 ? "nothing_accepted" : "error");
+ trackPull(repo, opts.home, code === 0 ? "nothing_accepted" : "error", [], suggested.count);
return code;
}
@@ -165,9 +244,14 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOpti
}
}
+ if (waiting) {
+ write(waiting);
+ write(` review: ${reviewUrl(link.brainId)}`);
+ }
+
if (opts.dryRun) {
write("· dry run — nothing written, and Trail was not told");
- trackPull(repo, opts.home, "dry_run", planned);
+ trackPull(repo, opts.home, "dry_run", planned, suggested.count);
return code;
}
@@ -199,6 +283,6 @@ export async function runTrailPull(repo: string, link: BrainLink, opts: PullOpti
: anySkipped
? "skipped"
: "error";
- trackPull(repo, opts.home, outcome, planned);
+ trackPull(repo, opts.home, outcome, planned, suggested.count);
return code;
}
diff --git a/src/brain/watch.ts b/src/brain/watch.ts
index c72066ff..eaf072b2 100644
--- a/src/brain/watch.ts
+++ b/src/brain/watch.ts
@@ -177,7 +177,10 @@ interface RepoBody {
// the finished row, exactly as it did before.
build?: { found_so_far?: number; filed_so_far?: number } | null;
claude_md?: { status?: string; quick_ready?: boolean; full_ready?: boolean; changes?: unknown } | null;
- context_files?: { files?: unknown; changes?: unknown } | null;
+ // An object on every SSE frame. On the polled GET it is the `true` that says
+ // the routes exist, and the counts ride in `context_files_progress` instead.
+ context_files?: { files?: unknown; changes?: unknown } | boolean | null;
+ context_files_progress?: { files?: unknown; changes?: unknown } | null;
}
/**
@@ -196,15 +199,16 @@ export function parseRepoBody(body: unknown): RepoState | null {
filedSoFar: num(b.build?.filed_so_far),
foundSoFar: num(b.build?.found_so_far),
};
- if (b.claude_md || b.context_files) {
- const files = Array.isArray(b.context_files?.files)
- ? (b.context_files!.files as Array<{ kind?: unknown; path?: unknown; changes?: unknown }>)
+ const cf = b.context_files && typeof b.context_files === "object" ? b.context_files : b.context_files_progress;
+ if (b.claude_md || cf) {
+ const files = Array.isArray(cf?.files)
+ ? (cf!.files as Array<{ kind?: unknown; path?: unknown; changes?: unknown }>)
.filter((f) => f && typeof f === "object")
.map((f) => ({ kind: String(f.kind ?? ""), path: String(f.path ?? ""), changes: countOf(f.changes) }))
: undefined;
state.suggestions = {
claudeMd: countOf(b.claude_md?.changes),
- contextFiles: b.context_files?.changes !== undefined ? countOf(b.context_files.changes) : (files ?? []).reduce((n, f) => n + f.changes, 0),
+ contextFiles: cf?.changes !== undefined ? countOf(cf.changes) : (files ?? []).reduce((n, f) => n + f.changes, 0),
...(files ? { files } : {}),
};
}
diff --git a/src/cli.ts b/src/cli.ts
index d95fdb5c..9b674b65 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -33,7 +33,7 @@ import {
} from "./brain/push.js";
import { apiBaseUrl, clearPendingSignup, readLink, readPendingSignup, writeLink, writePendingSignup } from "./brain/link.js";
import { withLegacyNames } from "./legacy-args.js";
-import { currentStage, DOING_LABEL, rulesSoFar, watchBuild, type RepoState, type Suggestions } from "./brain/watch.js";
+import { currentStage, DOING_LABEL, rulesSoFar, watchBuild, type RepoState } from "./brain/watch.js";
import {
AGENT_WAIT_MS,
brainUrl,
@@ -45,8 +45,7 @@ import {
startHandoff,
waitForSignup,
} from "./brain/signup.js";
-import { runTrailPull } from "./brain/pull.js";
-import { readByWired, readersOf } from "./brain/context-files.js";
+import { runTrailPull, suggestionsLine } from "./brain/pull.js";
import { startSpinner } from "./util/spinner.js";
import { contextDirFor } from "./context/node-file.js";
import { loadGraphCached } from "./graph/load.js";
@@ -1570,39 +1569,6 @@ async function runTrailPullCommand(dir: string, opts: { dryRun?: boolean }): Pro
if (code !== 0) process.exitCode = code;
}
-/**
- * The suggestions line after a build, cut to the files the wired agents read:
- * `● 18 suggestions for the files claude, agents and cursor read`. Null when
- * there are none to mention.
- */
-function suggestionsLine(s: Suggestions | undefined, wired: string[], again: boolean): string | null {
- if (!s) return null;
- let count = 0;
- const kinds = new Set<string>();
- if (s.claudeMd > 0 && readByWired("claude_md", wired)) {
- count += s.claudeMd;
- kinds.add("claude_md");
- }
- if (s.files) {
- for (const f of s.files) {
- if (f.changes <= 0 || !readByWired(f.kind, wired)) continue;
- count += f.changes;
- kinds.add(f.kind);
- }
- } else if (s.contextFiles > 0) {
- // No per-file list from this Trail, so no way to cut it to the wired agents'
- // files: the count is Trail's total.
- count += s.contextFiles;
- for (const k of ["agents_md", "folder_claude_md", "cursor_rule", "skill"]) kinds.add(k);
- }
- if (count === 0) return null;
- const readers = wired.length
- ? wired.filter((w) => [...kinds].some((k) => readersOf(k, [w]).length > 0))
- : [];
- const whose = readers.length ? `the files ${joinAnd(readers)} read` : "this repo's context files";
- return `● ${count.toLocaleString("en-US")} ${again ? "new " : ""}suggestion${count === 1 ? "" : "s"} for ${whose}`;
-}
-
brain
.command("push")
.description("Read THIS repo on your machine and build its trail — no GitHub App, works on private repos")
diff --git a/src/telemetry/contract.ts b/src/telemetry/contract.ts
index c423adc4..e44d6e11 100644
--- a/src/telemetry/contract.ts
+++ b/src/telemetry/contract.ts
@@ -64,7 +64,7 @@ export const EVENTS: Record<string, ReadonlySet<string>> = {
* written (a fixed set, sorted); every count is a bucket. Paths, headings and
* the changes' text never travel. The adoption number for Trail's context
* files: how many people actually take a suggestion home. */
- trail_pulled: new Set<string>(['outcome', 'kinds', 'files_bucket', 'changes_bucket', 'skipped_bucket']),
+ trail_pulled: new Set<string>(['outcome', 'kinds', 'files_bucket', 'changes_bucket', 'skipped_bucket', 'suggested_bucket']),
/** One closed agent session, summarised. `graft_reads` vs `source_reads` is
* the single number that says whether an agent prefers graft to grep; the two
* `*_turns` buckets are the follow-up question — of the turns that used graft,
diff --git a/test/brain-context-files-pull.test.ts b/test/brain-context-files-pull.test.ts
index 6449429b..c38cf8a7 100644
--- a/test/brain-context-files-pull.test.ts
+++ b/test/brain-context-files-pull.test.ts
@@ -141,14 +141,15 @@ const link = { brainId: 'b1', token: 'gbt_1.x', baseUrl: 'http://trail.test' } a
const json = (body: unknown, status = 200) =>
new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
-function fakeTrail(files: ContextFile[], opts: { contextFiles?: 'ok' | 'missing' } = {}) {
+function fakeTrail(files: ContextFile[], opts: { contextFiles?: 'ok' | 'missing'; repo?: unknown; claudeMd?: unknown[] } = {}) {
const applied: Record<string, string[]> = {};
const f = (async (u: string, init?: RequestInit) => {
const path = new URL(u).pathname;
if (path.endsWith('/rules/anchors')) return json({ anchors: [] });
if (path.endsWith('/claude-md')) {
- return json({ path: 'CLAUDE.md', head_sha: 'abc', changes: [{ id: 'm1', kind: 'add', heading: 'Money', after_heading: '', text: 'Integer cents.' }] });
+ return json({ path: 'CLAUDE.md', head_sha: 'abc', changes: opts.claudeMd ?? [{ id: 'm1', kind: 'add', heading: 'Money', after_heading: '', text: 'Integer cents.' }] });
}
+ if (path.endsWith('/repo') && opts.repo) return json(opts.repo);
if (path.endsWith('/context-files')) {
return opts.contextFiles === 'missing' ? json({ error: 'not found' }, 404) : json({ head_sha: 'abc', files });
}
@@ -213,3 +214,48 @@ test('a Trail without context files still pulls CLAUDE.md, silently', async () =
assert.match(lines.join('\n'), /✓ wrote 1 accepted change\n A CLAUDE\.md +\+ Money/);
assert.doesNotMatch(lines.join('\n'), /✗/);
});
+
+/** Trail's GET /repo mid-review: 3 CLAUDE.md suggestions, 2 skills, 4 Cursor rules. */
+const REVIEWING = {
+ repo: { status: 'completed', rule_count: 75 },
+ claude_md: { status: 'ready', changes: 3 },
+ context_files: true,
+ context_files_progress: {
+ changes: 6,
+ files: [
+ { kind: 'skill', path: '.claude/skills/a/SKILL.md', changes: 2 },
+ { kind: 'cursor_rule', path: '.cursor/rules/a.mdc', changes: 4 },
+ ],
+ },
+};
+
+test('with nothing accepted, a pull says how many suggestions are waiting for the wired agents', async () => {
+ const root = tmpRepo('ctx-waiting');
+ const { f } = fakeTrail([], { repo: REVIEWING, claudeMd: [] });
+ const lines: string[] = [];
+ const code = await runTrailPull(root, link, { home: root, wired: ['claude'], dryRun: true, fetchImpl: f, write: (l) => lines.push(l) });
+ const out = lines.join('\n');
+ assert.equal(code, 0);
+ assert.match(out, /● 5 suggested so far for the files claude read, none accepted yet\n review: \S+\/brain\/b1\/context-files/);
+ assert.doesNotMatch(out, /nothing accepted in Trail yet/);
+});
+
+test('a dry run with accepted changes also says how many were suggested, and where to review', async () => {
+ const root = tmpRepo('ctx-waiting-dry');
+ const { f } = fakeTrail([], { repo: REVIEWING });
+ const lines: string[] = [];
+ await runTrailPull(root, link, { home: root, wired: ['claude', 'cursor'], dryRun: true, fetchImpl: f, write: (l) => lines.push(l) });
+ const out = lines.join('\n');
+ assert.match(out, /✓ would write 1 accepted change/);
+ assert.match(out, /● 9 suggested so far for the files claude and cursor read, 1 of them accepted\n review: /);
+ assert.match(out, /dry run — nothing written/);
+});
+
+test('a Trail that sends no counts leaves the pull as it was', async () => {
+ const root = tmpRepo('ctx-no-counts');
+ const { f } = fakeTrail([], { claudeMd: [] });
+ const lines: string[] = [];
+ await runTrailPull(root, link, { home: root, wired: ['claude'], fetchImpl: f, write: (l) => lines.push(l) });
+ assert.match(lines.join('\n'), /· nothing accepted in Trail yet — review:/);
+ assert.doesNotMatch(lines.join('\n'), /suggested so far/);
+});
diff --git a/test/brain-watch-events.test.ts b/test/brain-watch-events.test.ts
index 3ee65fe9..c14e223b 100644
--- a/test/brain-watch-events.test.ts
+++ b/test/brain-watch-events.test.ts
@@ -52,6 +52,21 @@ test('the suggestion counts are read whether Trail sends numbers or lists', () =
assert.equal(parseRepoBody({ repo: { status: 'ingesting' } })?.suggestions, undefined, 'an older Trail sends none');
});
+test('the polled GET carries the context-file counts in context_files_progress', () => {
+ // On GET /repo, `context_files` is the flag that says the routes exist.
+ const polled = parseRepoBody({
+ repo: { status: 'completed' },
+ claude_md: { status: 'analyzing', changes: 3 },
+ context_files: true,
+ context_files_progress: { changes: 2, files: [{ kind: 'skill', path: '.claude/skills/a/SKILL.md', changes: 2 }] },
+ });
+ assert.deepEqual(polled?.suggestions, {
+ claudeMd: 3,
+ contextFiles: 2,
+ files: [{ kind: 'skill', path: '.claude/skills/a/SKILL.md', changes: 2 }],
+ });
+});
+
// --- the stream ---------------------------------------------------------------
/** A text/event-stream response that sends each part in turn, then ends (or not). */
diff --git a/test/telemetry-contract.test.ts b/test/telemetry-contract.test.ts
index af27f271..1d32b823 100644
--- a/test/telemetry-contract.test.ts
+++ b/test/telemetry-contract.test.ts
@@ -217,11 +217,12 @@ test('trail pull: counts travel as buckets, and a path never rides along', () =>
const home = sandbox('tel-trail-pulled');
const ev = track(
'trail_pulled',
- { outcome: 'written', kinds: 'agents_md,claude_md', files_bucket: '1-4', changes_bucket: '5-19', skipped_bucket: '0', path: 'web/CLAUDE.md' },
+ { outcome: 'written', kinds: 'agents_md,claude_md', files_bucket: '1-4', changes_bucket: '5-19', skipped_bucket: '0', suggested_bucket: '20-49', path: 'web/CLAUDE.md' },
{ home, env: OPEN },
);
assert.equal(ev?.properties.outcome, 'written');
assert.equal(ev?.properties.kinds, 'agents_md,claude_md');
assert.equal(ev?.properties.changes_bucket, '5-19');
+ assert.equal(ev?.properties.suggested_bucket, '20-49');
assert.equal(ev?.properties.path, undefined);
});