Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
import { readFile, stat } from "node:fs/promises";
import { basename, dirname, join } from "node:path";
import pkg from "../../package.json" with { type: "json" };
import type { AgentAdapter } from "../agents/index.js";
import { defaultAgent } from "../agents/index.js";
import { compareVersions, versionNotice } from "../cli-version.js";
import { cogitIgnored, findGitRoot, gitHooksDir, gitUserEmail, gitUserName } from "../git.js";
import { BLOCK_START, GIT_HOOK_EVENTS, hookCommandLine, isShellHook } from "../git-hooks.js";
import type { Io } from "../io.js";
import { hashTurns, isRecorded, upgradeSessionIds } from "../messages.js";
import { cogitGitignoreChanged, recordSyncStatus, trackedRecordFiles } from "../record-sync.js";
import type { Session } from "../schema/session.js";
import { checkHealth } from "../server.js";
import { applyEvents, readEvents } from "../store/events.js";
import { projectPaths } from "../store/paths.js";
import { resolveProjectRoot } from "../store/root.js";
import { loadAllSessions, loadConfig, loadProject, loadSession } from "../store/stores.js";
/**
* `cogit doctor` (Story 13.1): the one command to hand a user whose map stays
* empty. Every check is read-only, runs in a fixed order and never stops the
* others; one line says `ok`, `warn` or `fail`, the reason, and the fix.
*/
export type CheckStatus = "ok" | "warn" | "fail";
export interface DoctorCheck {
/** Stable key for `--json`. */
id: string;
status: CheckStatus;
/** Short reason, one line. */
message: string;
/** The exact command (or setting) that fixes a warn or fail. */
fix?: string;
}
export interface DoctorReport {
/** False when any check failed: the CLI exits 1. */
ok: boolean;
checks: DoctorCheck[];
}
export interface DoctorOptions {
dir: string;
io: Io;
/** Print the report as JSON instead of lines. */
json?: boolean;
}
/** The lowest Node this project supports, from `engines`. */
const MIN_NODE = "22.13.0";
/** Below this, old transcripts are gone before a record can be backfilled. */
const RETENTION_FLOOR = 90;
/** A promise computed once, shared by the checks that need the same read. */
function once<T>(fn: () => Promise<T>): () => Promise<T> {
let cached: Promise<T> | undefined;
return () => (cached ??= fn());
}
interface DoctorContext {
root: string;
env: NodeJS.ProcessEnv;
agent: AgentAdapter;
gitRoot: () => Promise<string | undefined>;
project: () => Promise<Awaited<ReturnType<typeof loadProject>>>;
sessions: () => Promise<Session[]>;
transcripts: () => Promise<Map<string, string>>;
config: () => Promise<Awaited<ReturnType<typeof loadConfig>>>;
}
interface CheckSpec {
id: string;
run: (ctx: DoctorContext) => Promise<DoctorCheck>;
}
/** Claude Code's folder for a working directory: every non-alphanumeric becomes `-`. */
export function transcriptDirName(dir: string): string {
return dir.replace(/[^a-zA-Z0-9]/g, "-");
}
/** This project's transcripts, by session id (the main checkout and a linked worktree). */
export async function projectTranscripts(
root: string,
worktree: string | undefined,
agent: AgentAdapter,
env: NodeJS.ProcessEnv,
): Promise<Map<string, string>> {
const names = new Set([transcriptDirName(root)]);
if (worktree !== undefined) names.add(transcriptDirName(worktree));
const all = await agent.collectTranscripts(env);
return new Map([...all].filter(([, file]) => names.has(basename(dirname(file)))));
}
/**
* The transcript with the latest modification time that `skip` lets through,
* if there is one. Headless runs (Ralph, `claude -p`, other plugins' background
* sessions) are skipped unless they are recorded, so they never read as a tail
* someone forgot to record.
*/
async function newestTranscript(
transcripts: ReadonlyMap<string, string>,
skip: (file: string) => Promise<boolean>,
): Promise<{ id: string; file: string } | undefined> {
const dated: { id: string; file: string; mtime: number }[] = [];
for (const [id, file] of transcripts) {
const info = await stat(file).catch(() => undefined);
if (info !== undefined) dated.push({ id, file, mtime: info.mtimeMs });
}
dated.sort((a, b) => b.mtime - a.mtime);
for (const { id, file } of dated) {
if (!(await skip(file))) return { id, file };
}
return undefined;
}
/** The user messages in this transcript that the record has no node for. */
async function unrecordedTail(
root: string,
sessionId: string,
file: string,
agent: AgentAdapter,
): Promise<number> {
const turns = hashTurns(sessionId, await agent.readConversation(file));
const loaded = await loadSession(root, sessionId);
let recorded = new Set<string>();
if (loaded.found && loaded.ok) {
const upgraded = upgradeSessionIds(loaded.data, turns);
const events = await readEvents(root, sessionId);
recorded = new Set(applyEvents(upgraded.nodes, events).map((node) => node.id));
}
return turns.filter((turn) => !isRecorded(recorded, turn)).length;
}
/** The one line a check prints; the fix rides on the same line. */
export function formatCheck(check: DoctorCheck): string {
const head = `${check.status.padEnd(5)}${check.message}`;
return check.fix === undefined ? head : `${head} · fix: ${check.fix}`;
}
/** A detached-log section header and the lines under it. */
interface LogSection {
header: string;
body: string[];
}
/**
* The last error from a close pass in the detached log, if any. The pass runs
* as `backfill <id> --tail --close`; only its own last section matters, since a
* build after it says nothing about the recording.
*/
export function closePassError(log: string): { sessionId?: string; line: string } | undefined {
const sections: LogSection[] = [];
for (const line of log.split("\n")) {
if (line.startsWith("--- ")) sections.push({ header: line.slice(4), body: [] });
else sections.at(-1)?.body.push(line);
}
const passes = sections.filter((section) => /\bbackfill\b/.test(section.header));
const last = passes.at(-1);
if (last === undefined) return undefined;
const line = last.body.find((text) => /^\s*error:/i.test(text));
if (line === undefined) return undefined;
const id = last.header.split(/\s+/)[2];
return { ...(id === undefined ? {} : { sessionId: id }), line: line.trim() };
}
/** Reads the bounded tail of the detached log; a missing log is an empty one. */
async function readDetachedLog(root: string): Promise<string> {
const text = await readFile(projectPaths(root).detachedLog, "utf8").catch(() => "");
return text.slice(-64 * 1024);
}
/** The Node check, pure so its too-old branch is testable on any machine. */
export function nodeCheck(node: string = process.versions.node): DoctorCheck {
if (compareVersions(node, MIN_NODE) < 0)
return {
id: "node",
status: "fail",
message: `Node ${node} is older than ${MIN_NODE}`,
fix: `install Node ${MIN_NODE} or newer (https://nodejs.org)`,
};
return { id: "node", status: "ok", message: `Node ${node}, cogit ${pkg.version}` };
}
const CHECK_SPECS: CheckSpec[] = [
{ id: "node", run: async () => nodeCheck() },
{
id: "plugin",
run: async (ctx) => {
const installed = await ctx.agent.readPluginInstalled(ctx.env);
if (installed !== true)
return {
id: "plugin",
status: "fail",
message: "the Claude Code plugin is not installed, so nothing is recorded",
fix: ctx.agent.installCommand,
};
const enabled = await ctx.agent.readPluginEnabled(ctx.env, ctx.root);
if (enabled === undefined)
return {
id: "plugin",
status: "warn",
message: "could not read Claude Code's settings to see whether the plugin is enabled",
fix: "check ~/.claude/settings.json is a valid JSON object",
};
if (!enabled)
return {
id: "plugin",
status: "warn",
message: "the plugin is installed but not enabled, so sessions here record nothing",
fix: "cogit init --project-settings",
};
const version = await ctx.agent.readPluginVersion(ctx.env);
if (version === undefined)
return {
id: "plugin",
status: "warn",
message: "the plugin is installed and enabled, but its version is unknown",
fix: "claude plugin update cogit@cogit",
};
const notice = versionNotice(version, pkg.version);
if (notice !== undefined) return { id: "plugin", status: "warn", message: notice };
return {
id: "plugin",
status: "ok",
message: `the plugin is installed, enabled and at the CLI's version (${version})`,
};
},
},
{
id: "git",
run: async (ctx) => {
const gitRoot = await ctx.gitRoot();
if (gitRoot === undefined)
return {
id: "git",
status: "fail",
message: `${ctx.root} is not inside a git repository`,
fix: "git init",
};
const name = await gitUserName(ctx.root, ctx.env);
const email = await gitUserEmail(ctx.root, ctx.env);
if (name !== undefined && email !== undefined)
return {
id: "git",
status: "ok",
message: `git identity: ${name} <${email}>`,
};
const missing = [
name === undefined ? "user.name" : "",
email === undefined ? "user.email" : "",
]
.filter((key) => key !== "")
.join(" and ");
const fix =
(name === undefined ? 'git config --global user.name "Your Name"' : "") +
(name === undefined && email === undefined ? " && " : "") +
(email === undefined ? "git config --global user.email [email protected]" : "");
return {
id: "git",
status: "warn",
message: `git has no ${missing}; sessions are credited to the OS user and two people with one name read as one`,
fix,
};
},
},
{
id: "project",
run: async (ctx) => {
const project = await ctx.project();
if (!project.found)
return {
id: "project",
status: "fail",
message: `${projectPaths(ctx.root).project} is missing`,
fix: "cogit init",
};
if (!project.ok)
return {
id: "project",
status: "fail",
message: `${projectPaths(ctx.root).project}: ${project.error}`,
fix: "fix or remove the file, then run `cogit init`",
};
const hooks = await hookProblems(ctx);
if (hooks.length > 0)
return {
id: "project",
status: "warn",
message: `initialized, but ${hooks.join(", ")}`,
fix: "cogit hooks install",
};
return {
id: "project",
status: "ok",
message: `initialized as "${project.data.name}"; the git hooks are current`,
};
},
},
{
id: "record",
run: async (ctx) => {
const tracked = await trackedRecordFiles(ctx.root, ctx.env);
if (tracked > 0)
return {
id: "record",
status: "warn",
message: `git still tracks ${tracked} session file${tracked === 1 ? "" : "s"} an older version committed`,
fix: "git rm -r --cached .cogit/sessions && git add .cogit/.gitignore, then commit",
};
if (await cogitGitignoreChanged(ctx.root, ctx.env))
return {
id: "record",
status: "warn",
message:
"the new .cogit/.gitignore is not committed; teammates see .cogit/sessions/ in git status",
fix: "git add .cogit/.gitignore, then commit",
};
const sync = await recordSyncStatus(ctx.root, ctx.env);
if (!sync.sharing)
return { id: "record", status: "ok", message: "the record stays on this machine" };
if (sync.sendError !== undefined)
return {
id: "record",
status: "warn",
message: `${sync.pending} session record${sync.pending === 1 ? "" : "s"} could not be sent: ${sync.sendError}`,
fix: "the send runs in the background, where nothing can ask for a passphrase or a token: add your SSH key to ssh-agent (`ssh-add`), or for HTTPS store your login (`gh auth login` or a credential helper). The next push or session start sends the queue",
};
if (sync.downloadError !== undefined && !sync.downloaded)
return {
id: "record",
status: "warn",
message: `the team's records could not be downloaded: ${sync.downloadError}`,
fix: "cogit open",
};
return {
id: "record",
status: "ok",
message:
sync.remote === undefined
? "the record is shared, but this repository has no remote yet"
: `the record is shared through ${sync.remote}`,
};
},
},
{
id: "skill",
run: async (ctx) => {
const allowed = await ctx.agent.readSkillAllowed(ctx.env);
if (allowed === undefined)
return {
id: "skill",
status: "warn",
message: "could not read Claude Code's permissions",
fix: `check ~/.claude/settings.json is valid, or add ${ctx.agent.skillRule} to permissions.allow`,
};
if (!allowed)
return {
id: "skill",
status: "warn",
message: `${ctx.agent.skillRule} is not allowed, so the agent asks before each record update`,
fix: "cogit init --allow-skill",
};
return {
id: "skill",
status: "ok",
message: `${ctx.agent.skillRule} is allowed`,
};
},
},
{
id: "transcripts",
run: async (ctx) => {
const transcripts = await ctx.transcripts();
const retention = await ctx.agent.readRetention(ctx.env);
if (transcripts.size === 0)
return {
id: "transcripts",
status: "warn",
message: "no Claude Code transcripts for this project; start a session here",
fix: "claude",
};
if (retention === undefined)
return {
id: "transcripts",
status: "warn",
message: `${transcripts.size} transcript(s) found, but Claude Code's retention could not be read`,
fix: "cogit init --retention 90",
};
if (retention < RETENTION_FLOOR)
return {
id: "transcripts",
status: "warn",
message: `${transcripts.size} transcript(s) found; Claude Code deletes them after ${retention} days`,
fix: "cogit init --retention 90",
};
return {
id: "transcripts",
status: "ok",
message: `${transcripts.size} transcript(s) found; Claude Code keeps them ${retention} days`,
};
},
},
{
id: "sessions",
run: async (ctx) => {
const sessions = await ctx.sessions();
const transcripts = await ctx.transcripts();
const { recordHeadless } = await ctx.config();
const newest = await newestTranscript(transcripts, (file) =>
recordHeadless ? Promise.resolve(false) : ctx.agent.isHeadlessTranscript(file),
);
const tail =
newest === undefined
? undefined
: await unrecordedTail(ctx.root, newest.id, newest.file, ctx.agent);
const pending = newest !== undefined && tail !== undefined && tail > 0 ? newest : undefined;
if (sessions.length === 0)
return {
id: "sessions",
status: "warn",
message:
pending === undefined
? "no session recorded yet"
: `no session recorded yet; transcript ${pending.id} has ${tail} message(s) with no node`,
...(pending === undefined ? {} : { fix: `cogit backfill ${pending.id} --tail` }),
};
const latest = sessions.reduce((a, b) => (a.updatedAt >= b.updatedAt ? a : b));
if (pending !== undefined)
return {
id: "sessions",
status: "warn",
message: `${sessions.length} session(s) recorded, newest ${latest.updatedAt}; the newest transcript has ${tail} message(s) with no node yet`,
fix: `cogit backfill ${pending.id} --tail`,
};
return {
id: "sessions",
status: "ok",
message: `${sessions.length} session(s) recorded, newest ${latest.updatedAt}; the newest transcript is fully recorded`,
};
},
},
{
id: "server",
run: async (ctx) => {
const port = (await ctx.config()).serverPort;
const url = `http://127.0.0.1:${port}`;
if (await checkHealth(url, ctx.env))
return {
id: "server",
status: "ok",
message: `the map server answers on ${url}`,
};
return {
id: "server",
status: "warn",
message: `no map server on ${url} (the saved map file still opens)`,
fix: "cogit open .",
};
},
},
{
id: "detached",
run: async (ctx) => {
const error = closePassError(await readDetachedLog(ctx.root));
if (error === undefined)
return {
id: "detached",
status: "ok",
message: "the last close pass left no error",
};
return {
id: "detached",
status: "warn",
message: `the last close pass wrote: ${error.line}`,
fix:
error.sessionId === undefined
? "cogit backfill <session-id> --tail --close"
: `cogit backfill ${error.sessionId} --tail --close`,
};
},
},
];
/**
* Hook files that are missing or carry a block for another project or an
* earlier hook command. Only the `cogit hook …` line is compared: the fallback
* CLI path in the block names whichever CLI installed it (the plugin cache, a
* global install), which differs between runs and is refreshed by the plugin.
*/
async function hookProblems(ctx: DoctorContext): Promise<string[]> {
const gitRoot = await ctx.gitRoot();
if (gitRoot === undefined) return ["the git hooks are not installed"];
const dir = await gitHooksDir(gitRoot);
if (dir === undefined) return ["the git hooks directory could not be found"];
const problems: string[] = [];
for (const event of GIT_HOOK_EVENTS) {
const text = await readFile(join(dir, event), "utf8").catch(() => undefined);
if (text !== undefined && !text.includes(BLOCK_START) && !isShellHook(text)) {
problems.push(`the ${event} hook is not a shell script, so cogit cannot add to it`);
continue;
}
if (text === undefined || !text.includes(BLOCK_START)) {
problems.push(`the ${event} hook is missing`);
continue;
}
const block = /# >>> cogit[\s\S]*?# <<< cogit/.exec(text)?.[0] ?? "";
// Below the user's lines, an early `exit` there would skip it.
const top = text.startsWith("#!") ? text.indexOf("\n") + 1 : 0;
const current =
block.split("\n").includes(hookCommandLine(event, ctx.root)) &&
text.slice(top, text.indexOf(BLOCK_START)).trim() === "";
if (!current) problems.push(`the ${event} hook is outdated`);
}
return problems;
}
/**
* Runs every check in order and prints one line each (or the JSON report).
* Returns the report; the caller sets the exit code from `ok`.
*/
export async function doctor(opts: DoctorOptions): Promise<DoctorReport> {
const { io } = opts;
const agent = defaultAgent();
const resolved = await resolveProjectRoot(opts.dir);
const root = resolved.root;
const ctx: DoctorContext = {
root,
env: io.env,
agent,
gitRoot: once(() => findGitRoot(root)),
project: once(() => loadProject(root)),
sessions: once(() => loadAllSessions(root, io.warn)),
transcripts: once(() => projectTranscripts(root, resolved.worktree?.path, agent, io.env)),
config: once(() => loadConfig(io.env)),
};
const checks: DoctorCheck[] = [];
for (const spec of CHECK_SPECS) {
try {
checks.push(await spec.run(ctx));
} catch (err) {
checks.push({
id: spec.id,
status: "fail",
message: `the check could not run: ${(err as Error).message}`,
});
}
}
const report: DoctorReport = {
ok: checks.every((check) => check.status !== "fail"),
checks,
};
if (opts.json === true) {
io.out(JSON.stringify(report, null, 2));
} else {
for (const check of checks) io.out(formatCheck(check));
}
return report;
}