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 skills` and its subcommands (design 1.7), plus the top-level
* `trail forget`. Every command that changes something prints one plain line
* and the command that undoes it. `skills on`, `offers on` and `keep` are the
* person's: run by an agent (`personAtTerminal` says no), they print who may
* run them and exit 1. This is the only module that imports the person-only
* setters of settings.ts (a static test pins it).
*
* `add` is g5's CLI half (`cliAdd`): this file only prints what it returns
* and sends `skill_saved`, because the save gate's import closure may not load
* telemetry. Telemetry carries closed-set values only, never a name.
*/
import { homedir } from 'node:os';
import { Argument, InvalidArgumentError, type Command } from 'commander';
import { repoPlace } from '../notes/home.js';
import { flatLine } from '../notes/flatten.js';
import { track as sendEvent } from '../telemetry/track.js';
import { findPriorSheet, readRunSheet } from '../trace/runs.js';
import { compileRun, refusalWords } from './compile.js';
import { draftText, repoName } from './compile-words.js';
import { cliAdd } from './save-gate.js';
import { readSettings, setOffers, setSkillOff, setSkills, trailNow } from './settings.js';
import { forgetSkill, keepHeld, listAllPersonal, listHeld, nameTaken, personAtTerminal, restoreSkill, type PersonCheck, type PersonDeps } from './store.js';
import { readCapped } from './store-fs.js';
import { heldWords, reportLines, skillsReport, statusWords, whereWords, type SkillRow1b } from './cli-skills-report.js';
import { extrasWords, fidelityLine } from './cli-skills-report-1b.js';
import { lessonLine, readLessons } from './lessons.js';
import { runCheckout } from './run-checkout.js';
import { forgetLearning, initDraftCommand, lessonCommand, type CliOut } from './cli-skills-1b.js';
import { noteAgentForget, type Dropped } from './forget-notice.js';
import { draftFoldText, liftRestoreVersion, restoreVersionCommand, updateCommand, versionsLine } from './cli-skills-2.js';
import { stepLearnings } from './follow-learnings.js';
/** Seams for tests; production passes nothing. */
export interface SkillCliDeps {
env?: NodeJS.ProcessEnv;
/** The clock: default `trailNow(env)` (TRAIL_TEST_NOW in a test home only). */
now?: () => Date;
cwd?: () => string;
/** Passed to the real `personAtTerminal` (TTYs, the process table), as g4's tests do. */
personDeps?: PersonDeps;
track?: (event: string, props: Record<string, string>) => void;
out?: (line: string) => void;
err?: (line: string) => void;
exit?: (code: number) => void;
}
/** `trail skills on` says this, word for word (1.7). */
export const SKILLS_ON_LINES = [
'✓ skills on · Trail now counts jobs you ask for on more than one day: job words and dates only, kept on this machine, nothing uploaded.',
' When one checks out on its 3rd day, it offers once to keep the commands that worked (at most 1 offer per session, 3 a week).',
' See what it counts: trail skills · stop offers: trail skills offers off · all off: trail skills off',
] as const;
export const OFFERS_OFF_LINE = 'Skill offers are off. Turn them back on: trail skills offers on';
/** 1b (R59): numbers are init's; `trail keep` keeps them, after the person typed them. */
export const KEEP_NUMBERS_LINE = 'trail keep <numbers> keeps items from trail init.';
/** A person-only command run by an agent (1.7). */
export const personOnly = (command: string) => `Only the person can run this, in their own terminal: trail ${command}`;
const one = (t: string, max = 60) => flatLine(t, max);
/** Every line break a terminal or an agent might honour. */
const BREAKS = /\r\n|[\n\r\u000b\u000c\u0085\u2028\u2029]/;
/** Controls but tab (ESC, BEL, C1) and characters nobody sees: they can rewrite a terminal or hide a marker. */
const UNSEEN = /[\u0000-\u0008\u000e-\u001f\u007f-\u009f]|[\p{Cf}\ufe00-\ufe0f]/gu;
const MARKER = /^(\s*)(?:\[(?:trail|graft|trail-code)\]\s*)+/i;
/**
* A SKILL.md as `show` prints it: anyone can edit the file by hand, so no line of it may read as Trail's own
* (`[trail] ...`) or carry terminal escapes. Indentation stays (it's markdown).
*/
export function shownText(text: string): string {
return text.split(BREAKS).map((l) => l.replace(UNSEEN, '').replace(MARKER, '$1')).join('\n').trimEnd();
}
const unknownSkill = (name: string) => `✗ no skill called ${one(name)} · trail skills lists them`;
const errText = (e: unknown) => `✗ ${one(e instanceof Error ? e.message : String(e), 200).replace(/^trail:\s*/, '')}`;
interface Io {
env: NodeJS.ProcessEnv; now: () => Date; cwd: () => string; person: () => PersonCheck;
track: (event: string, props: Record<string, string>) => void; out: (l: string) => void; err: (l: string) => void; exit: (c: number) => void;
}
function io(d: SkillCliDeps): Io {
const env = d.env ?? process.env;
return {
env,
now: d.now ?? (() => trailNow(env)),
cwd: d.cwd ?? (() => process.cwd()),
person: () => personAtTerminal(env, d.personDeps ?? {}),
track: d.track ?? ((e, p) => { sendEvent(e, p); }),
out: d.out ?? ((l) => console.log(l)),
err: d.err ?? ((l) => console.error(l)),
exit: d.exit ?? ((c) => { process.exitCode = c; }),
};
}
/** Runs a command body; a thrown store or settings error (busy, a planted link) prints and exits 1. */
const guarded = (x: Io, fn: () => void) => () => {
try {
fn();
} catch (e) {
x.err(errText(e));
x.exit(1);
}
};
const fail = (x: Io, line: string) => {
x.err(line);
x.exit(1);
};
/** Is the person at the keyboard? Otherwise print who may run `command` and exit 1. */
function personOr(x: Io, command: string): boolean {
if (x.person().ok) return true;
fail(x, personOnly(command));
return false;
}
/** A personal skill by name (any repo), or a name the person turned off. */
const knownSkill = (name: string, env: NodeJS.ProcessEnv) =>
listAllPersonal(env).some((r) => r.name === name) || readSettings(env).skillsOff.includes(name);
/** Prints a 1b command's lines (to stdout on 0, stderr on 1) and its exit code. */
function said(x: Io, r: CliOut): void {
for (const l of r.lines) (r.code === 0 ? x.out : x.err)(l);
if (r.code !== 0) x.exit(r.code);
}
function forget(x: Io, name: string): void {
// 1b: a lesson or learning id, or a kept guardrail's name, before a skill's name (1.7).
const learning = forgetLearning(name, x.cwd(), x.env);
if (learning) {
if (learning.code === 0 && learning.dropped) agentForgot(x, learning.dropped);
return said(x, learning);
}
const r = forgetSkill(name, x.env, x.now());
if (!r.ok) return fail(x, unknownSkill(name));
agentForgot(x, { what: 'skill', name, back: `trail skills restore ${one(name)}` });
x.out(`✓ ${one(name)} forgotten · bring it back: trail skills restore ${one(name)}`);
}
/** D117 (2): an agent's forget (CLAUDECODE, or a claude or pty-wrapper ancestor, as R17) is told to the person at the next Stop. */
function agentForgot(x: Io, d: Omit<Dropped, 'at'>): void {
try {
if (x.env.CLAUDECODE === undefined && !x.person().claudeAncestor) return;
} catch { /* can't tell: note it, telling the person is the safe side */ }
noteAgentForget(d, x.env, x.now());
}
function list(x: Io, json: boolean): void {
const r = skillsReport(x.env, x.now(), x.cwd());
if (json) x.out(JSON.stringify(r, null, 2));
else for (const l of reportLines(r)) x.out(l);
// Phase 2 (P27): whether the value line went out, and how; no number from it.
if (r.value) x.track('skill_value', { channel: 'list' });
}
function show(x: Io, name: string): void {
const ref = listAllPersonal(x.env).find((r) => r.name === name);
if (ref) {
const text = readCapped(ref.file);
if (text === null) return fail(x, unknownSkill(name));
const row = skillsReportRow(x, ref.name);
x.out(shownText(text));
x.out('');
x.out(row ? `· ${whereWords(row.applies)} · ${statusWords(row)}${extrasWords(row)}` : `· ${whereWords(ref.applies)}`);
// Phase 2 (3.6): how its last uses followed it, when the ledger has the counts.
const fid = fidelityLine(ref.id, x.env);
if (fid) x.out(`· ${fid}`);
// Phase 2 (3.6): the versions it keeps, and a change waiting beside a hand-edited file.
const versions = versionsLine(ref, x.env);
if (versions) x.out(`· ${versions}`);
// 1b (2.12): every lesson kept with it, oldest first.
for (const l of readLessons(ref.dir)) x.out(` ${lessonLine(l)}`);
return;
}
const held = listHeld(x.env, x.now()).find((h) => h.name === name);
const text = held ? readCapped(`${held.dir}/SKILL.md`) : null;
if (!held || text === null) return fail(x, unknownSkill(name));
x.out(shownText(text));
x.out('');
x.out(`· ${heldWords(held)}`);
}
function skillsReportRow(x: Io, name: string): SkillRow1b | null {
return skillsReport(x.env, x.now(), x.cwd()).skills.find((s) => s.name === name) ?? null;
}
/** "show me" (2.1): the run compiled as an offer would keep it, printed. Writes nothing. */
function draft(x: Io, runId: string, print: boolean): void {
if (!print) return fail(x, `✗ use --print: trail skills draft ${one(runId, 40)} --print`);
// 1b: init's pending skill n, compiled again from its source (R24, R37).
const init = /^init-(\d{1,2})$/.exec(runId);
if (init) return said(x, initDraftCommand(Number(init[1]), x.cwd(), x.env, x.now()));
// Phase 2 (4.7): a run whose change to a skill is offered prints that change as a diff.
const fold = draftFoldText(runId, x.env);
if (fold) return x.out(fold);
const sheet = readRunSheet(runId, x.env);
if (!sheet) return fail(x, `✗ no run called ${one(runId, 40)} (runs are kept 7 days)`);
// D93: the run's own checkout, as an offer compiles it (an older sheet: the folder it is shown in, when that is it).
const place = repoPlace(x.cwd(), x.env);
const root = runCheckout(sheet, x.env, place.git && place.key === sheet.repoKey ? place.checkout : '');
const scope = { repoKeys: [sheet.repoKey], checkout: root, env: x.env };
const opts = {
repoRoot: root, home: x.env.HOME || homedir(), platform: process.platform,
prior: findPriorSheet(sheet, x.env), applies: sheet.repoKey, now: x.now(), readSheet: (id: string) => readRunSheet(id, x.env),
taken: (n: string) => nameTaken(n, scope) !== null,
learnings: stepLearnings({ repoKeys: [sheet.repoKey], checkout: root, env: x.env }),
};
// An offer keeps a repeated job; a run with no check (an asked save) is shown the way an ask keeps it.
let c = compileRun(sheet, { ...opts, moment: 'repeated' });
if (!c.ok && (c.reason === 'no-check' || c.reason === 'trivial')) c = compileRun(sheet, { ...opts, moment: 'asked' });
if (!c.ok) return fail(x, `✗ Trail can't keep that run as a skill: ${refusalWords(c.reason, c.detail)}`);
x.out(draftText(c.skill, sheet));
}
/**
* 4.9 step 1 for the CLI: `add` takes a name and `--run` only. Commander gives an option a parent knows (`--json` of
* `trail skills`, a root option) to that parent wherever it is typed, so add refuses any option a parent got from the
* command line, the same way as an unknown one: an error, nothing saved.
*/
function onlyRun(cmd: Command): void {
for (let c = cmd.parent; c; c = c.parent) {
for (const o of c.options) {
if (c.getOptionValueSource(o.attributeName()) === 'cli') cmd.error(`error: unknown option '${o.long ?? o.flags}'`, { exitCode: 1, code: 'commander.unknownOption' });
}
}
}
function add(x: Io, name: string, runId: string): void {
const r = cliAdd(name, runId, x.env, x.now(), x.cwd());
for (const l of r.lines) (r.exit === 0 ? x.out : x.err)(l);
if (r.saved) x.track('skill_saved', { from: r.saved.from, scope: r.saved.scope });
if (r.changed) x.track('skill_changed', { op: r.changed });
if (r.exit !== 0) x.exit(r.exit);
}
function keep(x: Io, names: string[]): void {
if (names.every((n) => /^\d+$/.test(n))) return fail(x, KEEP_NUMBERS_LINE);
if (names.length !== 1) return fail(x, '✗ keep one skill at a time: trail skills keep <name>');
const name = names[0]!;
if (!personOr(x, `skills keep ${one(name)}`)) return;
const r = keepHeld(name, x.person(), x.env, x.now());
if (r.ok) {
x.out(`✓ kept ${one(name)} as one of your skills · undo: trail forget ${one(name)}`);
x.track('skill_saved', { from: 'asked', scope: 'personal' });
return;
}
if (r.reason === 'not-a-person') return fail(x, personOnly(`skills keep ${one(name)}`));
if (r.reason === 'name-taken') return fail(x, `✗ ${one(name)} is already the name of another skill, so this one can't be kept under it`);
fail(x, `✗ nothing held called ${one(name)}: a held skill can be kept for 24 hours after Trail shows it · see what's held: trail skills`);
}
function restore(x: Io, name: string): void {
const r = restoreSkill(name, x.env, x.now());
if (r.ok) return x.out(`✓ ${one(name)} is back · forget it again: trail forget ${one(name)}`);
if (r.reason === 'name-taken') return fail(x, `✗ the name ${one(name)} is taken now, so the forgotten one can't come back under it`);
fail(x, `✗ no forgotten skill called ${one(name)}`);
}
function offers(x: Io, state: 'on' | 'off', here: boolean): void {
let key: string | null = null;
if (here) {
const place = repoPlace(x.cwd(), x.env);
if (!place.git) return fail(x, '✗ --here needs a repo: run it inside the repo');
key = place.key;
}
const flag = here ? ' --here' : '';
const where = key ? ` in ${one(repoName(key))}` : '';
if (state === 'on') {
if (!personOr(x, `skills offers on${flag}`)) return;
setOffers(true, key, x.env, x.now());
return x.out(`✓ skill offers on${where} · stop them: trail skills offers off${flag}`);
}
setOffers(false, key, x.env, x.now());
x.out(key ? `Skill offers are off${where}. Turn them back on: trail skills offers on --here` : OFFERS_OFF_LINE);
x.track('skill_answer', { answer: 'off' });
}
function onOff(x: Io, state: 'on' | 'off', name: string | undefined): void {
if (name === undefined) {
if (state === 'on') {
if (!personOr(x, 'skills on')) return;
setSkills(true, x.env, x.now());
for (const l of SKILLS_ON_LINES) x.out(l);
return;
}
setSkills(false, x.env, x.now());
return x.out('✓ skills off: Trail stops counting jobs, offering skills and bringing them back · turn on again: trail skills on');
}
if (state === 'on' && !personOr(x, `skills on ${one(name)}`)) return;
if (!knownSkill(name, x.env)) return fail(x, unknownSkill(name));
setSkillOff(name, state === 'off', x.env);
x.out(state === 'off'
? `✓ ${one(name)} off: it stops reaching the agent · turn it back on: trail skills on ${one(name)}`
: `✓ ${one(name)} on: it reaches the agent again · turn it off: trail skills off ${one(name)}`);
}
/** `trail skills …` and `trail forget <name>` (1.7). */
export function registerSkillCommands(program: Command, deps: SkillCliDeps = {}): void {
const x = io(deps);
// Phase 2: `restore --version <n>` reaches the restore, not the CLI's own --version (cli-skills-2.ts).
let restoreAt: string | undefined;
const lift = <F extends (argv?: readonly string[], o?: never) => unknown>(f: F) => ((argv?: readonly string[], o?: never) => {
const l = liftRestoreVersion(argv ?? process.argv);
restoreAt = l.version;
return f.call(program, l.argv, o);
}) as unknown as F;
program.parse = lift(program.parse.bind(program) as never);
program.parseAsync = lift(program.parseAsync.bind(program) as never);
const skills = program
.command('skills')
.description("Your skills: the steps that worked, kept on this machine when you say so, brought back when you ask for the same job")
.option('--json', 'the same facts as one JSON object')
.action((opts: { json?: boolean }) => guarded(x, () => list(x, !!opts.json))());
skills.command('show').description('Print a skill (or a held one) and its status').argument('<name>', 'the skill')
.action((name: string) => guarded(x, () => show(x, name))());
skills.command('draft').description("Print what keeping a run would save, or init's item n (init-<n>). Saves nothing").argument('<run-id>', 'the run, or init-<n>')
.option('--print', 'print it (the only thing draft does)')
.action((runId: string, opts: { print?: boolean }) => guarded(x, () => draft(x, runId, !!opts.print))());
skills.command('add').description('Keep a run as a skill, after the person said yes or asked for it (what was typed decides; no flag does)')
.argument('<name>', 'the skill name')
.requiredOption('--run <run-id>', 'the run to keep', (v: string, prev?: string) => {
if (prev !== undefined) throw new InvalidArgumentError('give --run once.');
return v;
})
.action((name: string, opts: { run: string }, cmd: Command) => {
onlyRun(cmd);
guarded(x, () => add(x, name, opts.run))();
});
skills.command('lesson').description('Keep the lesson Trail offered, after the person typed yes to it (what was typed decides; no flag does)')
.argument('[skill]', 'the skill the lesson rides with (none for a lesson about an error)')
.requiredOption('--offer <offer-id>', 'the offer the person said yes to', (v: string, prev?: string) => {
if (prev !== undefined) throw new InvalidArgumentError('give --offer once.');
return v;
})
.action((skill: string | undefined, opts: { offer: string }, cmd: Command) => {
onlyRun(cmd);
guarded(x, () => said(x, lessonCommand(skill ?? null, opts.offer, x.env, x.now())))();
});
skills.command('keep').description("Keep a skill Trail held because nobody said yes. Only you, in your own terminal").argument('<name...>', 'the held skill')
.action((names: string[]) => guarded(x, () => keep(x, names))());
skills.command('forget').description('Forget a skill (trail skills restore brings it back), a lesson or a learning by its id, or a guardrail').argument('<name>', 'the skill, lesson id, learning id or guardrail')
.action((name: string) => guarded(x, () => forget(x, name))());
skills.command('restore').description('Bring back the skill you forgot last, or with --version <n> an older version of a skill (only you, in your own terminal)')
.argument('<name>', 'the skill')
.action((name: string) => guarded(x, () => {
if (restoreAt === undefined) return restore(x, name);
const code = restoreVersionCommand(name, restoreAt, x);
if (code !== 0) x.exit(code);
})());
skills.command('update').description('Change a skill the way Trail showed, after the person typed yes to it (what was typed decides; no flag does)')
.argument('<name>', 'the skill')
.requiredOption('--offer <offer-id>', 'the offer the person said yes to', (v: string, prev?: string) => {
if (prev !== undefined) throw new InvalidArgumentError('give --offer once.');
return v;
})
.action((name: string, opts: { offer: string }, cmd: Command) => {
onlyRun(cmd);
guarded(x, () => {
const code = updateCommand(name, opts, x);
if (code !== 0) x.exit(code);
})();
});
skills.command('offers').description('Turn skill offers on or off, everywhere or in this repo (--here). Only you turn them on')
.addArgument(new Argument('<state>', 'on or off').choices(['on', 'off'])).option('--here', 'just this repo')
.action((state: 'on' | 'off', opts: { here?: boolean }) => guarded(x, () => offers(x, state, !!opts.here))());
skills.command('on').description('Turn skills on (only you), or one skill back on').argument('[name]', 'one skill')
.action((name: string | undefined) => guarded(x, () => onOff(x, 'on', name))());
skills.command('off').description('Turn skills off, or one skill').argument('[name]', 'one skill')
.action((name: string | undefined) => guarded(x, () => onOff(x, 'off', name))());
program.command('forget', { hidden: true }).description('Forget one of your skills (trail skills restore brings it back), a lesson or a learning by its id, or a guardrail').argument('<name>', 'the skill, lesson id, learning id or guardrail')
.action((name: string) => guarded(x, () => forget(x, name))());
}