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 { execFile } from "node:child_process";
import { existsSync, realpathSync } from "node:fs";
import { chmod, mkdir, readFile, realpath, rm, stat } from "node:fs/promises";
import { dirname, join, resolve } from "node:path";
import { promisify } from "node:util";
import { findGitRoot, gitHooksDir, resolveCommit } from "./git.js";
import { spawnDetachedProcess } from "./hooks/run.js";
import { pushIsDryRun } from "./push-command.js";
import { countUnsentRecords } from "./record-sync.js";
import { atomicWrite } from "./store/fs.js";
import { captureDisabled, projectPaths } from "./store/paths.js";
import { loadConfig } from "./store/stores.js";
const execFileAsync = promisify(execFile);
const execGit = (args: string[], opts: { cwd: string; env: NodeJS.ProcessEnv }) =>
execFileAsync("git", args, opts);
import { addThoughtTrailer } from "./thought.js";
/**
* Git hook installation (Story 9.3). cogit never owns a hook file: it adds a
* marked block that calls back into the CLI, leaves whatever the user (or Husky)
* put there alone, and a failure never blocks `init` or a commit.
*/
export const BLOCK_START = "# >>> cogit";
export const BLOCK_END = "# <<< cogit";
/**
* The CLI that installs the hooks: the fallback when `cogit` is not on PATH, the
* common case for a plugin-only install. A path that later disappears (a plugin
* update) is refreshed by the next UserPromptSubmit hook.
*/
export function currentCliPath(): string | undefined {
const entry = process.argv[1];
if (entry === undefined || entry === "") return undefined;
try {
return realpathSync(entry);
} catch {
return undefined;
}
}
/**
* The block `init` adds to a hook, at the top so a user line that exits early
* (`exit 0`) can never skip it. A `cogit` on PATH wins; otherwise the CLI that
* installed the block runs under `node`; with neither, the hook does nothing and
* the commit goes on.
*
* - `pre-push` reads git's stdin itself and hands it back to the lines below,
* so a user hook that reads it still gets it and cogit always sees the refs.
* - `prepare-commit-msg` runs the same file again as a child, which skips the
* block, and adds the trailer once the user's lines are done: a tool that
* rewrites the message file (commitizen) keeps the `Thought:` trailer, a user
* `trap ... EXIT` or a closing `exec` cannot drop it, and the user's exit
* status stays the hook's.
*/
export function hookBlock(
event: string,
projectRoot: string,
cliPath: string | null = currentCliPath() ?? null,
): string {
if (event === "pre-push") {
return [
BLOCK_START,
"cogit_stdin=$(cat)",
...cogitCall(event, projectRoot, cliPath, `printf '%s' "$cogit_stdin" | `, ""),
'if [ -n "$cogit_stdin" ]; then exec <<COGIT_STDIN',
"$cogit_stdin",
"COGIT_STDIN",
"else exec </dev/null; fi",
BLOCK_END,
].join("\n");
}
if (event === "prepare-commit-msg") {
return [
BLOCK_START,
'if [ "${COGIT_HOOK_RUN-}" = "$0" ]; then',
" unset COGIT_HOOK_RUN",
"else",
' COGIT_HOOK_RUN=$0 "$0" "$@"',
" cogit_status=$?",
...cogitCall(event, projectRoot, cliPath, "", " "),
" exit $cogit_status",
"fi",
BLOCK_END,
].join("\n");
}
return [BLOCK_START, ...cogitCall(event, projectRoot, cliPath, "", ""), BLOCK_END].join("\n");
}
/** The `cogit` / `node <cli>` branches that run one hook; `"$@"` passes git's arguments. */
function cogitCall(
event: string,
projectRoot: string,
cliPath: string | null,
pipe: string,
indent: string,
): string[] {
const args = `hook ${event} --dir ${shellQuote(projectRoot)} "$@"`;
const lines = ["if command -v cogit >/dev/null 2>&1; then", ` ${pipe}cogit ${args} || true`];
if (cliPath !== null) {
const cli = shellQuote(cliPath);
lines.push(
`elif command -v node >/dev/null 2>&1 && [ -f ${cli} ]; then`,
` ${pipe}node ${cli} ${args} || true`,
);
}
lines.push("fi");
return lines.map((line) => `${indent}${line}`);
}
/**
* The line of a block that names the project and the hook command; doctor
* compares only this one, since the fallback CLI path differs between installs.
*/
export function hookCommandLine(event: string, projectRoot: string): string {
return (
hookBlock(event, projectRoot, null)
.split("\n")
.find((line) => line.includes("cogit hook ")) ?? ""
);
}
/**
* True when cogit can add its block: a new or empty file, one without a
* shebang, or a `sh`-family script. A Python or Node hook is left alone, since
* shell lines would break it; doctor reports it.
*/
export function isShellHook(text: string): boolean {
const first = text.split("\n", 1)[0] ?? "";
if (!first.startsWith("#!")) return true;
return /(^|[/\s])(sh|bash|dash|zsh|ksh|ash)(\s|$)/.test(first.slice(2).trim());
}
/** Single quotes for the shell, with the embedded single quote escaped. */
function shellQuote(value: string): string {
return `'${value.replaceAll("'", `'\\''`)}'`;
}
/**
* Puts the cogit block right under the shebang, keeping the file's own content.
* An older block anywhere in the file (past versions appended it) moves up.
*/
export function withHookBlock(text: string, block: string): string {
const rest = text.includes(BLOCK_START) ? withoutHookBlock(text) : text;
// An empty file still has to be runnable: git execs the hook directly.
if (rest === "") return `#!/bin/sh\n${block}\n`;
if (!rest.startsWith("#!")) return `${block}\n${rest}`;
const cut = rest.indexOf("\n");
if (cut === -1) return `${rest}\n${block}\n`;
return `${rest.slice(0, cut + 1)}${block}\n${rest.slice(cut + 1)}`;
}
/**
* Removes the marked block, and the blank line older versions put before it
* when they appended it; the user's own blank lines stay.
*/
export function withoutHookBlock(text: string): string {
return text.replace(/(\n\n)?# >>> cogit\n[\s\S]*?# <<< cogit\n?/, (_all, gap) =>
gap === undefined ? "" : "\n",
);
}
/** True when what is left is only the shebang `installGitHook` wrote itself. */
function onlyGeneratedShebang(text: string): boolean {
return text.split("\n").every((line) => line.trim() === "" || line.trim() === "#!/bin/sh");
}
/**
* Installs the block into the hook file git actually uses. Returns true when the
* file changed, false when the block was already current or the repository does
* not expose a hooks directory (a bare `.git` directory in tests, a non-repo).
*/
export async function installGitHook(root: string, event: string): Promise<boolean> {
const gitRoot = await findGitRoot(root);
if (gitRoot === undefined) return false;
const dir = await gitHooksDir(gitRoot);
if (dir === undefined) return false;
await mkdir(dir, { recursive: true });
const file = join(dir, event);
const exists = await stat(file).then(
() => true,
() => false,
);
const current = exists ? await readFile(file, "utf8") : "";
if (!isShellHook(current)) return false;
const next = withHookBlock(current, hookBlock(event, root));
if (exists && next === current) return false;
await atomicWrite(file, next);
await chmod(file, 0o755);
return true;
}
/**
* The git-side events cogit answers (Stories 9.3, 9.4, 13.6). A git hook's stdin
* is not the Claude Code hook JSON, so these never go through `runHook`.
* `pre-push` sends the session records along with the code; `prepare-commit-msg`
* adds the `Thought:` trailer that names the message behind it; `post-commit`
* queues the Shape of a message that landed commits, outside the commit.
*/
export const GIT_HOOK_EVENTS = ["prepare-commit-msg", "post-commit", "pre-push"] as const;
/** Hooks older versions installed: their block is removed on the next refresh. */
const RETIRED_GIT_HOOK_EVENTS = ["pre-commit"] as const;
export type GitHookEvent = (typeof GIT_HOOK_EVENTS)[number];
export function isGitHookEvent(event: string): event is GitHookEvent {
return (GIT_HOOK_EVENTS as readonly string[]).includes(event);
}
/** Installs the cogit block into every hook git would run; returns the events added. */
export async function installGitHooks(root: string): Promise<GitHookEvent[]> {
await rm(projectPaths(root).hooksOff, { force: true });
const installed: GitHookEvent[] = [];
for (const event of GIT_HOOK_EVENTS) {
if (await installGitHook(root, event)) installed.push(event);
}
return installed;
}
/**
* Rewrites the blocks that are already there, so they point at the CLI running
* now (a plugin update moves it). Never adds a block to a hook that has none.
*/
export async function refreshGitHooks(root: string): Promise<GitHookEvent[]> {
const gitRoot = await findGitRoot(root);
if (gitRoot === undefined) return [];
const dir = await gitHooksDir(gitRoot);
if (dir === undefined) return [];
const refreshed: GitHookEvent[] = [];
const hasBlock = async (event: string): Promise<boolean> =>
((await readFile(join(dir, event), "utf8").catch(() => undefined)) ?? "").includes(BLOCK_START);
// Missing blocks come back unless the user took them out with `hooks uninstall`:
// Husky rewrites its hooks folder on every `npm install`, and a hook this version
// added must reach a clone that already has cogit's others.
const installed =
!existsSync(projectPaths(root).hooksOff) || (await hasBlock("prepare-commit-msg"));
for (const event of GIT_HOOK_EVENTS) {
if (!installed && !(await hasBlock(event))) continue;
if (await installGitHook(root, event)) refreshed.push(event);
}
await removeHookBlocks(dir, RETIRED_GIT_HOOK_EVENTS);
return refreshed;
}
/**
* Removes only cogit's block from the hooks it installed (Story 9.4): the user's
* own lines stay, and a file that held nothing but the shebang cogit wrote is
* deleted. Returns the events that changed.
*/
export async function uninstallGitHooks(root: string): Promise<GitHookEvent[]> {
const gitRoot = await findGitRoot(root);
if (gitRoot === undefined) return [];
const dir = await gitHooksDir(gitRoot);
if (dir === undefined) return [];
await removeHookBlocks(dir, RETIRED_GIT_HOOK_EVENTS);
const removed = await removeHookBlocks(dir, GIT_HOOK_EVENTS);
// Remembered, so the refresh on the next chat message does not put them back.
const paths = projectPaths(root);
if (existsSync(paths.project)) {
await mkdir(dirname(paths.hooksOff), { recursive: true });
await atomicWrite(paths.hooksOff, `${new Date().toISOString()}\n`);
}
return removed;
}
/** Takes cogit's block out of these hooks; returns the ones that had one. */
async function removeHookBlocks<Event extends string>(
dir: string,
events: readonly Event[],
): Promise<Event[]> {
const removed: Event[] = [];
for (const event of events) {
const file = join(dir, event);
const current = await readFile(file, "utf8").catch(() => undefined);
if (current === undefined || !current.includes(BLOCK_START)) continue;
const next = withoutHookBlock(current);
if (onlyGeneratedShebang(next)) await rm(file, { force: true });
else await atomicWrite(file, next);
removed.push(event);
}
return removed;
}
const NO_OBJECT = /^0+$/;
/**
* The `pre-push` hook (`pushedRefs` is git's stdin: one `<ref> <sha> <remote ref> <sha>` a
* line): hands the records to a background run that waits for this
* push to land, so the user's push never waits for the network, never meets a second
* SSH prompt and never fails because of a record. A push that only deletes sends
* nothing. The line is the only sign that something else is leaving the machine.
*/
async function sendWithPush(
dir: string,
env: NodeJS.ProcessEnv,
pushedRemote: string | undefined,
pushedRefs: string,
spawn: typeof spawnDetachedProcess,
dryRun: () => boolean,
): Promise<void> {
if (captureDisabled(env)) return;
if (dryRun()) return;
const lines = pushedRefs.split("\n").filter(Boolean);
const going = lines
.map((line) => line.split(" "))
.find((part) => !NO_OBJECT.test(part[1] ?? "0"));
if (lines.length > 0 && going === undefined) return;
const unsent = await countUnsentRecords(dir, env, pushedRemote);
if (unsent === 0) return;
const cli = currentCliPath();
if (cli === undefined) return;
process.stderr.write(
`cogit: ${unsent} session record${unsent === 1 ? "" : "s"} will follow this push to ${pushedRemote}\n`,
);
const after = going === undefined ? [] : ["--after", `${going[2]}=${going[1]}`];
spawn(
cli,
["record-sync", "send-pushed", ...after, "-C", dir],
env,
projectPaths(dir).detachedLog,
);
}
/**
* Starts the Shape of the commit that just landed (Story 13.6). The commit's
* `Thought:` trailer, read by the shape run, names the message, so the Shape
* lands on the session that committed, not on whichever session wrote
* `.cogit/HEAD` last. Detached and silent: a commit never waits for a
* side-model run, and a failure lands in the detached log like the session-end
* pass. In `agent` mode the record skill writes the Shape itself.
*/
async function queueShape(
dir: string,
env: NodeJS.ProcessEnv,
spawn: typeof spawnDetachedProcess,
): Promise<void> {
if (captureDisabled(env)) return;
const config = await loadConfig(env).catch(() => undefined);
if (config === undefined || !config.shapes || config.recorder === "agent") return;
const gitRoot = await findGitRoot(dir);
if (gitRoot === undefined) return;
const commit = await resolveCommit(gitRoot, "HEAD");
if (commit === undefined) return;
const cli = currentCliPath();
if (cli === undefined) return;
spawn(cli, ["shape", "--commit", commit, "-C", dir], env, projectPaths(dir).detachedLog);
}
/** Git's own variables in a hook; a lookup of another repository must not inherit them. */
const GIT_REPO_ENV = ["GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR", "GIT_PREFIX"];
async function commonDir(cwd: string, env: NodeJS.ProcessEnv): Promise<string | undefined> {
try {
const { stdout } = await execGit(["rev-parse", "--git-common-dir"], { cwd, env });
const dir = resolve(cwd, String(stdout).trim());
return await realpath(dir).catch(() => dir);
} catch {
return undefined;
}
}
/**
* True when the hook runs in the project's repository (or one of its worktrees).
* A hooks folder shared by every repository (a global `core.hooksPath`) carries
* the block of the one project that installed it; in any other repository the
* block must do nothing, or a commit there takes that project's `Thought:`.
* Unknown counts as the same, as before.
*/
export async function sameRepository(hookCwd: string, dir: string): Promise<boolean> {
const clean = Object.fromEntries(
Object.entries(process.env).filter(([key]) => !GIT_REPO_ENV.includes(key)),
);
const [here, project] = await Promise.all([
commonDir(hookCwd, process.env),
commonDir(dir, clean),
]);
return here === undefined || project === undefined || here === project;
}
/**
* Runs one git hook. A git hook that fails would block the user's commit, so the
* CLI calls this inside its own silence: nothing here throws or prints. `args`
* are what the hook script was given (`$@`): for `prepare-commit-msg` the message
* file and the commit source.
*/
export async function runGitHook(
event: GitHookEvent,
dir: string,
env: NodeJS.ProcessEnv = process.env,
args: readonly string[] = [],
now: Date = new Date(),
spawn: typeof spawnDetachedProcess = spawnDetachedProcess,
pushedRefs: () => Promise<string> = async () => "",
dryRun: () => boolean = pushIsDryRun,
hookCwd?: string,
): Promise<void> {
if (hookCwd !== undefined && !(await sameRepository(hookCwd, dir))) return;
if (event === "pre-push") {
await sendWithPush(dir, env, args[0], await pushedRefs(), spawn, dryRun);
return;
}
if (event === "post-commit") {
await queueShape(dir, env, spawn);
return;
}
const [messageFile, source] = args;
if (messageFile === undefined || messageFile === "") return;
await addThoughtTrailer({
dir,
messageFile,
...(source === undefined ? {} : { source }),
env,
now,
});
}