Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
import { execFile } from 'node:child_process';
import { promisify } from 'node:util';
import { readFile, writeFile, mkdir, access, realpath, rename, open, unlink, stat } from 'node:fs/promises';
import path from 'node:path';
const run = promisify(execFile);
export const MANIFEST_DIR = '.loop-worktrees';
export const MANIFEST_FILE = path.posix.join(MANIFEST_DIR, 'manifest.json');
const MANIFEST_MUTEX_FILE = path.posix.join(MANIFEST_DIR, '.manifest.mutex');
export const VALID_STATUSES = [
'active',
'rejected',
'escalated',
'merged',
'stale',
];
/** Terminal states cleanup discards by default; "active" is never swept automatically. */
export const CLEANUP_DEFAULT_STATUSES = ['rejected', 'escalated'];
function emptyManifest() {
return { version: 1, worktrees: [] };
}
async function exists(p) {
try {
await access(p);
return true;
}
catch {
return false;
}
}
/** Run git in `cwd`, returning trimmed stdout. Throws a clean Error on failure. */
async function git(args, cwd) {
try {
const { stdout } = await run('git', args, { cwd, maxBuffer: 10 * 1024 * 1024 });
return stdout.trim();
}
catch (err) {
const e = err;
const detail = (e.stderr || e.message || '').trim();
throw new Error(`git ${args.join(' ')} failed: ${detail}`);
}
}
export async function isGitRepo(cwd) {
try {
const out = await git(['rev-parse', '--is-inside-work-tree'], cwd);
return out === 'true';
}
catch {
return false;
}
}
async function assertGitRepo(root) {
if (!(await isGitRepo(root))) {
throw new Error(`Not a git repository: ${root}. loop-worktree manages git worktrees and must run inside a repo.`);
}
}
async function withManifestMutex(root, fn) {
const dir = path.join(root, MANIFEST_DIR);
await mkdir(dir, { recursive: true });
const mutexPath = path.join(root, MANIFEST_MUTEX_FILE);
const deadline = Date.now() + 30000;
for (;;) {
try {
const handle = await open(mutexPath, 'wx');
await handle.close();
break;
}
catch (err) {
if (err.code !== 'EEXIST')
throw err;
try {
const st = await stat(mutexPath);
if (Date.now() - st.mtimeMs > 30000) {
await unlink(mutexPath).catch(() => { });
continue;
}
}
catch {
continue;
}
if (Date.now() > deadline) {
throw new Error(`Timed out waiting for manifest mutex (${MANIFEST_MUTEX_FILE}). If no other loop-worktree process is running, delete it manually.`);
}
await new Promise((resolve) => setTimeout(resolve, 25 + Math.random() * 50));
}
}
try {
return await fn();
}
finally {
await unlink(mutexPath).catch(() => { });
}
}
export async function readManifest(root) {
const file = path.join(root, MANIFEST_FILE);
if (!(await exists(file)))
return emptyManifest();
const raw = await readFile(file, 'utf8');
const parsed = JSON.parse(raw);
if (parsed.version !== 1 || !Array.isArray(parsed.worktrees)) {
throw new Error(`Invalid manifest at ${MANIFEST_FILE}: expected { version: 1, worktrees: [] }.`);
}
return parsed;
}
export async function writeManifest(root, manifest) {
const dir = path.join(root, MANIFEST_DIR);
await mkdir(dir, { recursive: true });
const file = path.join(root, MANIFEST_FILE);
const tmpFile = `${file}.tmp.${Date.now()}.${Math.random().toString(36).slice(2)}`;
await writeFile(tmpFile, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
await rename(tmpFile, file);
}
export async function createWorktree(input) {
const { root, runId, pattern } = input;
const base = input.base ?? 'main';
await assertGitRepo(root);
return withManifestMutex(root, async () => {
const manifest = await readManifest(root);
const existing = manifest.worktrees.find((w) => w.id === runId);
if (existing && existing.status === 'active') {
throw new Error(`Run id "${runId}" already has an active worktree at ${existing.path}.`);
}
const relPath = path.posix.join(MANIFEST_DIR, runId);
const branch = `loop/${runId}`;
// `git worktree add -b <branch> <path> <base>` creates the branch and checks it
// out in an isolated worktree. Forward-slash paths are accepted on all platforms.
await git(['worktree', 'add', '-b', branch, relPath, base], root);
const entry = {
id: runId,
path: relPath,
branch,
baseBranch: base,
pattern,
createdAt: new Date().toISOString(),
status: 'active',
};
try {
manifest.worktrees = manifest.worktrees.filter((w) => w.id !== runId);
manifest.worktrees.push(entry);
await writeManifest(root, manifest);
}
catch (writeErr) {
await git(['worktree', 'remove', '--force', relPath], root).catch(() => { });
await git(['branch', '-D', branch], root).catch(() => { });
throw writeErr;
}
return entry;
});
}
export async function markWorktree(input) {
const { root, runId, status } = input;
if (!VALID_STATUSES.includes(status)) {
throw new Error(`Invalid status "${status}". Use one of: ${VALID_STATUSES.join(', ')}.`);
}
return withManifestMutex(root, async () => {
const manifest = await readManifest(root);
const entry = manifest.worktrees.find((w) => w.id === runId);
if (!entry) {
throw new Error(`No worktree with run id "${runId}" in ${MANIFEST_FILE}.`);
}
entry.status = status;
await writeManifest(root, manifest);
return entry;
});
}
/** Parse a duration like "30m", "24h", "7d" into milliseconds. Shared with lock.ts's --ttl. */
export function parseDurationMs(token, flag) {
const m = /^(\d+)([smhd])$/.exec(token.trim());
if (!m) {
throw new Error(`Invalid ${flag} "${token}". Use e.g. 30s, 30m, 24h, 7d.`);
}
const n = Number(m[1]);
const unit = m[2];
const ms = unit === 's' ? 1000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000;
return n * ms;
}
export async function cleanupWorktrees(input) {
const { root } = input;
await assertGitRepo(root);
return withManifestMutex(root, async () => {
const statuses = input.statuses ?? CLEANUP_DEFAULT_STATUSES;
const cutoff = input.olderThan ? Date.now() - parseDurationMs(input.olderThan, '--older-than') : undefined;
const manifest = await readManifest(root);
const removed = [];
const skipped = [];
for (const entry of manifest.worktrees) {
if (!statuses.includes(entry.status))
continue;
if (cutoff !== undefined && Date.parse(entry.createdAt) > cutoff)
continue;
const args = ['worktree', 'remove', entry.path];
if (input.force)
args.push('--force');
try {
// Without --force, git refuses to remove a worktree with uncommitted or
// untracked changes. We surface that refusal instead of forcing data loss.
await git(args, root);
removed.push(entry);
}
catch (err) {
skipped.push({ entry, reason: err.message });
}
}
const removedIds = new Set(removed.map((e) => e.id));
manifest.worktrees = manifest.worktrees.filter((w) => !removedIds.has(w.id));
await writeManifest(root, manifest);
return { removed, skipped };
});
}
/** Paths (repo-relative, posix) of every worktree git currently knows about. */
async function gitWorktreePaths(root) {
const rootReal = await realpath(root);
const out = await git(['worktree', 'list', '--porcelain', '-z'], root);
const paths = [];
for (const line of out.split('\0')) {
if (!line.startsWith('worktree '))
continue;
const abs = line.slice('worktree '.length);
let absReal;
try {
absReal = await realpath(abs);
}
catch (err) {
// git keeps listing a worktree (as "prunable") even after its directory
// was removed out-of-band -- a manual `rm -rf`, a crash mid-cleanup, a
// container wipe -- rather than via `git worktree remove`. realpath()
// on that now-missing path throws ENOENT, which used to propagate out
// of gc() entirely and abort the exact reconciliation it exists to do.
// Treat a missing directory as simply absent from disk so it still
// surfaces as a `dropped` manifest entry instead of crashing gc().
if (err.code === 'ENOENT')
continue;
throw err;
}
const rel = path.relative(rootReal, absReal).split(path.sep).join('/');
paths.push(rel);
}
return paths;
}
export async function gc(input) {
const { root } = input;
await assertGitRepo(root);
return withManifestMutex(root, async () => {
const manifest = await readManifest(root);
const onDisk = await gitWorktreePaths(root);
const managedOnDisk = onDisk.filter((p) => p.startsWith(`${MANIFEST_DIR}/`));
const manifestPaths = new Set(manifest.worktrees.map((w) => w.path));
const orphans = managedOnDisk.filter((p) => !manifestPaths.has(p));
const dropped = manifest.worktrees.filter((w) => !onDisk.includes(w.path));
const removedOrphans = [];
if (input.force) {
for (const orphan of orphans) {
try {
await git(['worktree', 'remove', '--force', orphan], root);
removedOrphans.push(orphan);
}
catch {
// Leave it reported as an orphan if git still refuses.
}
}
}
if (dropped.length > 0) {
const droppedIds = new Set(dropped.map((e) => e.id));
manifest.worktrees = manifest.worktrees.filter((w) => !droppedIds.has(w.id));
await writeManifest(root, manifest);
}
return { orphans, dropped, removedOrphans };
});
}
export async function listWorktrees(input) {
const manifest = await readManifest(input.root);
if (!input.status)
return manifest.worktrees;
return manifest.worktrees.filter((w) => w.status === input.status);
}