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
/**
* The Trail workspace this machine is connected to, and the calls that talk
* to it (trail-cloud's `/api/cli/…`).
*
* One connection per machine, not per repo: a person signs in once, through
* the link their agent offers, and picks which of their repos the workspace
* gets. It lives in `~/.trail/cloud.json` next to their notes, never in a
* repo. Learnings themselves travel through git (`.trail/` is committed);
* the workspace adds what one clone can't see: who is learning what across
* the team's repos, how often a learning is reused, and the team page.
*
* Every call is bounded and never throws: a failure comes back as
* `{ error }`, so a command still answers when Trail is unreachable.
*/
import { existsSync, rmSync } from "node:fs";
import { join } from "node:path";
import { trailHome } from "../notes/home.js";
import { ensurePrivateDir, PRIVATE_FILE_MODE } from "../util/private-file.js";
import { readJson, writeJsonAtomic } from "../util/state.js";
/** Trail's own front end and API: Trail cloud, which serves the CLI routes at team.trailhq.com. */
export const DEFAULT_TRAIL_URL = "https://team.trailhq.com";
/**
* TEST ONLY. Points sign-in at a stand-in Trail, for tests and local demos.
* Taken only for a host on this machine (localhost, 127.0.0.1, [::1]) or a
* `.test` one, which nothing on the internet answers, so an export left in a
* shell can't send a sign-in, and the learnings uploaded after it, anywhere
* else. Never documented for users: a self-hosted Trail is `trail login
* --server <url>`, which the link itself carries.
*/
export const TEST_SERVER_ENV = "TRAIL_TEST_SERVER";
/** `url` as a server address (http or https, no trailing slash), or null when it isn't one. */
export function serverUrl(url: string | undefined): string | null {
const t = url?.trim().replace(/\/+$/, "");
if (!t || !/^https?:\/\//i.test(t)) return null;
try {
new URL(t);
return t;
} catch {
return null;
}
}
function testServer(env: NodeJS.ProcessEnv): string | null {
const url = serverUrl(env[TEST_SERVER_ENV]);
if (!url) return null;
const host = new URL(url).hostname.toLowerCase();
const local = host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host.endsWith(".localhost") || host.endsWith(".test");
return local ? url : null;
}
/** The Trail `init --connect` or `--pair` was told with `--server`, for the rest of this process. */
let runServer: string | null = null;
/**
* Where a sign-in goes when nothing chose otherwise: Trail cloud. The
* connection then keeps the address it signed in at in cloud.json, and every
* later call goes there. No variable a shell might still export moves it
* (TRAIL_URL, or GRAFT_BRAIN_URL for the old brain API): a self-hosted Trail
* comes from `trail login --server`, saved on the link, or from `--server`
* on `init --connect` and `--pair` for that run (`useServer`); tests use
* TEST_SERVER_ENV.
*/
export function trailUrl(env: NodeJS.ProcessEnv = process.env): string {
return runServer ?? testServer(env) ?? DEFAULT_TRAIL_URL;
}
/**
* `--server <url>` on `init --connect` and `--pair` (and the `_trail-pair`
* child they start): the Trail that gave the code, for every call this
* process makes. Set by the command line, never read from the environment;
* null puts it back to Trail cloud.
*/
export function useServer(url: string | null): void {
runServer = url;
}
export interface WorkspaceInfo {
id: string;
name: string;
slug: string;
url: string;
invite_url: string;
}
export interface Cloud {
/** The Trail it's connected to. */
url: string;
/** `trl_…`: this machine's token for the workspace. */
token: string;
user: { name: string; email: string };
workspace: WorkspaceInfo;
/** Repo keys in the workspace (`github.com/owner/name`), as of the last look. */
repos: string[];
linkedAt: number;
/**
* `connect`: connected by `trail init --connect <code>` from the onboarding
* on the web. Such a machine sends a repo summary (titles, counts, names)
* and never the full learnings sync, so it's never asked to add repos.
*/
via?: "connect";
}
function cloudPath(env: NodeJS.ProcessEnv = process.env): string {
return join(trailHome(env), "cloud.json");
}
/** The connection, or null when this machine hasn't connected a workspace. */
export function readCloud(env: NodeJS.ProcessEnv = process.env): Cloud | null {
const c = readJson<Cloud>(cloudPath(env));
return c?.token && c.workspace?.slug ? c : null;
}
/**
* Whether the workspace side of trail is on: the sign-in link at the end of a
* reply, and `login`, `logout` and `workspace`. Committing `.trail/` already
* shares learnings with a team, so it stays off until signing in gives more
* than that. TRAIL_CLOUD=1 turns it on; a machine already connected keeps it.
*/
export function cloudEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
return env.TRAIL_CLOUD === "1" || readCloud(env) !== null;
}
/** Owner-only: the file holds the workspace token. */
export const SECRET_FILE_MODE = PRIVATE_FILE_MODE;
/** Owner-only, in an owner-only folder: the file holds the workspace token. */
export function writeCloud(c: Cloud, env: NodeJS.ProcessEnv = process.env): void {
ensurePrivateDir(trailHome(env));
writeJsonAtomic(cloudPath(env), c, false, SECRET_FILE_MODE);
}
export function clearCloud(env: NodeJS.ProcessEnv = process.env): boolean {
const p = cloudPath(env);
if (!existsSync(p)) return false;
rmSync(p, { force: true });
return true;
}
/* -------------------------------------------------------------------------- */
/* calls */
/* -------------------------------------------------------------------------- */
type Fetch = typeof fetch;
export interface ApiError {
error: string;
/** HTTP status, when Trail answered at all. */
status?: number;
}
export function isError(x: unknown): x is ApiError {
return typeof x === "object" && x !== null && typeof (x as ApiError).error === "string";
}
async function call<T>(
base: string,
method: "GET" | "POST" | "PUT",
path: string,
body: unknown,
opts: { token?: string; timeoutMs?: number; fetchImpl?: Fetch } = {},
): Promise<{ status: number; body: T } | ApiError> {
const f = opts.fetchImpl ?? fetch;
try {
const headers: Record<string, string> = { "content-type": "application/json", accept: "application/json" };
if (opts.token) headers.authorization = `Bearer ${opts.token}`;
const res = await f(`${base}${path}`, {
method,
headers,
body: method === "GET" ? undefined : JSON.stringify(body),
signal: AbortSignal.timeout(opts.timeoutMs ?? 15_000),
});
const text = await res.text();
let json: unknown = null;
try {
json = text ? JSON.parse(text) : null;
} catch {
/* not JSON */
}
if (!res.ok) {
const msg = (json as { error?: unknown } | null)?.error;
return { error: typeof msg === "string" ? msg : `Trail answered ${res.status}`, status: res.status };
}
return { status: res.status, body: json as T };
} catch (err) {
const timedOut = err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
return { error: timedOut ? "Trail didn't answer in time" : "couldn't reach Trail" };
}
}
async function authed<T>(c: Cloud, method: "GET" | "POST" | "PUT", path: string, body: unknown, opts: { timeoutMs?: number; fetchImpl?: Fetch } = {}): Promise<T | ApiError> {
const r = await call<T>(c.url, method, path, body, { ...opts, token: c.token });
return isError(r) ? r : r.body;
}
/* sign-in handoff ----------------------------------------------------------- */
export interface HandoffRepo {
key: string;
name: string;
learnings: number;
}
/**
* Tell Trail about a sign-in link before anyone opens it: the repo the agent
* was in, which is what the workspace's repo picker lists. Its name and
* learning count only; no learning, no other repo and no person's name travels.
*/
export async function registerHandoff(
base: string,
req: { state: string; repo: { key: string; name: string } | null; repos: HandoffRepo[]; author: string; pair?: string },
fetchImpl?: Fetch,
): Promise<{ url: string } | ApiError> {
const r = await call<{ url: string }>(base, "POST", "/api/cli/handoffs", req, { fetchImpl });
return isError(r) ? r : r.body;
}
/**
* Report how a `trail init --pair` run is going, for the onboarding page that
* shows it live. "reviewed" once the person has kept or dropped what it found
* (Trail takes no more), "gone" when the link expired or Trail doesn't know it.
*/
export async function postHandoffProgress(base: string, body: { state: string } & Record<string, unknown>, fetchImpl?: Fetch): Promise<"ok" | "reviewed" | "gone" | "error"> {
const r = await call(base, "POST", "/api/cli/handoffs/progress", body, { fetchImpl, timeoutMs: 15_000 });
if (!isError(r)) return "ok";
if (r.status === 409) return "reviewed";
if (r.status === 404 || r.status === 410) return "gone";
return "error";
}
export type ClaimResult =
| { cloud: Omit<Cloud, "url" | "linkedAt"> }
| { pending: true }
| { error: string; reason: "expired" | "unsupported" };
/** Ask once whether the person finished in the browser. A network or server error counts as "not yet". */
export async function claimHandoff(base: string, state: string, fetchImpl?: Fetch): Promise<ClaimResult> {
const r = await call<{ token?: string; user?: Cloud["user"]; workspace?: WorkspaceInfo; repos?: string[]; pending?: boolean }>(
base,
"POST",
"/api/cli/handoffs/claim",
{ state },
{ fetchImpl, timeoutMs: 10_000 },
);
if (isError(r)) {
if (r.status === 410) return { error: "that sign-in link was already used or has expired", reason: "expired" };
if (r.status === 404 || r.status === 405) return { error: "this Trail doesn't take sign-ins from the CLI yet", reason: "unsupported" };
return { pending: true };
}
const b = r.body;
if (r.status === 200 && b?.token && b.workspace?.slug) {
return { cloud: { token: b.token, user: b.user ?? { name: "", email: "" }, workspace: b.workspace, repos: b.repos ?? [] } };
}
return { pending: true };
}
/* the workspace ------------------------------------------------------------- */
export interface WorkspaceRepo {
key: string;
name: string;
learnings: number;
added_by: string;
}
export interface Me {
user: Cloud["user"];
workspace: WorkspaceInfo;
repos: WorkspaceRepo[];
}
export function fetchMe(c: Cloud, fetchImpl?: Fetch): Promise<Me | ApiError> {
return authed<Me>(c, "GET", "/api/cli/me", undefined, { fetchImpl });
}
export function addRepo(c: Cloud, repo: { key: string; name: string }, fetchImpl?: Fetch): Promise<{ repos: WorkspaceRepo[] } | ApiError> {
return authed<{ repos: WorkspaceRepo[] }>(c, "POST", "/api/cli/repos", repo, { fetchImpl });
}
/** The laptop's other repos, by name only, for the onboarding page to offer. */
export function sendMachineRepos(c: Cloud, state: string, repos: { key: string; name: string; last_used?: string; sessions: number }[], fetchImpl?: Fetch): Promise<object | ApiError> {
return authed<object>(c, "POST", "/api/cli/handoffs/repos", { state, repos }, { fetchImpl });
}
/** Which of them the person picked: null until they choose. */
export function fetchMachinePicks(c: Cloud, state: string, fetchImpl?: Fetch): Promise<{ picks: string[] | null } | ApiError> {
return authed<{ picks: string[] | null }>(c, "POST", "/api/cli/handoffs/picks", { state }, { fetchImpl });
}
/** How setting up one picked repo is going, for the page. */
export function postRepoSetup(c: Cloud, state: string, key: string, status: "setting_up" | "done" | "failed", learnings = 0, fetchImpl?: Fetch): Promise<object | ApiError> {
return authed<object>(c, "POST", "/api/cli/handoffs/repos/status", { state, key, status, learnings }, { fetchImpl });
}
export interface UploadedLearning {
/** `.trail/learnings/<name>`, or `.claude/skills/<name>/SKILL.md` for a skill. */
path: string;
/** "skill" for a skill of the repo; a plain learning leaves it out. */
kind?: "skill";
/** "" when committed at HEAD, or the pushed branch it was found on (`origin/kumar/x`). */
ref: string;
branch?: string;
title: string;
author: string;
date: string;
minutes?: number;
tokens?: number;
touches: string[];
body: string;
hash: string;
/** A skill's description: what it does and when to use it. */
why?: string;
/** A skill's other files: everything git tracks in its folder besides SKILL.md. */
files?: SkillFileUpload[];
}
export interface SkillFileUpload {
/** Relative to the skill's folder: `references/forms.md`, `scripts/fill.py`. */
path: string;
/** The file as text, or base64 when `encoding` says so. */
content: string;
encoding?: "base64";
executable?: boolean;
}
/** Most of one upload request: skills bring their folders, so a big set goes up in parts. */
export const UPLOAD_PART_BYTES = 12 * 1024 * 1024;
export async function uploadLearnings(
c: Cloud,
req: { repo: { key: string; name: string }; learnings: UploadedLearning[] },
fetchImpl?: Fetch,
): Promise<{ repo: string; learnings: number; added: number } | ApiError> {
const parts: UploadedLearning[][] = [[]];
let bytes = 0;
for (const l of req.learnings) {
const size = JSON.stringify(l).length;
if (bytes + size > UPLOAD_PART_BYTES && parts.at(-1)!.length) {
parts.push([]);
bytes = 0;
}
parts.at(-1)!.push(l);
bytes += size;
}
let added = 0;
let last: { repo: string; learnings: number; added: number } | ApiError | null = null;
for (const learnings of parts) {
last = await authed<{ repo: string; learnings: number; added: number }>(c, "PUT", "/api/cli/learnings", { ...req, learnings }, { timeoutMs: 60_000, fetchImpl });
if (isError(last)) return last;
added += last.added;
}
return { ...last!, added };
}
/**
* One use of the learnings: a search that showed some, a check against them,
* or a coding agent using one of the repo's skills. Counts and which
* learnings, never content: no query (for the prompt hook that is the
* person's prompt), no file paths and no task.
*/
export interface ActivityEvent {
repo: string;
kind: "search" | "check" | "skill";
/** For a skill use: the skill's folder name under `.claude/skills/`. */
skill?: string;
asker: string;
session: string;
/** How many files the answer pointed into, or the check covered. */
file_count: number;
/** File names of the learnings it showed: the name is what the workspace knows a learning by. */
shown_paths: string[];
shown_authors: string[];
/** Tokens the map saved on this lookup (what `ask` prints as "tokens saved"); absent when unknown. */
saved_tokens?: number;
at: string;
}
export function postActivity(c: Cloud, events: ActivityEvent[], fetchImpl?: Fetch): Promise<{ stored: number } | ApiError> {
return authed(c, "POST", "/api/cli/activity", { events }, { fetchImpl });
}
export interface TeamView {
workspace: string;
repo: string;
days: number;
people: number;
sessions: number;
new_learnings: number;
reused: number;
members: Array<{ name: string; topics: string[]; learnings: number; reused: number }>;
overlaps: Array<{ kind: string; text: string }>;
url?: string;
}
export function fetchTeam(c: Cloud, opts: { repo?: string; days?: number } = {}, fetchImpl?: Fetch): Promise<TeamView | ApiError> {
const q = new URLSearchParams({ days: String(opts.days ?? 7) });
if (opts.repo) q.set("repo", opts.repo);
return authed<TeamView>(c, "GET", `/api/cli/team?${q.toString()}`, undefined, { fetchImpl });
}