#!/usr/bin/env node
// agent-files.mjs: find other AI agents' config files and point them at AGENTS.md.
//
// Init and Init Update both end with the same step: detect CLAUDE.md, GEMINI.md,
// .cursorrules, the Copilot instructions and the Cursor / Windsurf rule folders,
// and (only for the ones the user confirms) replace each with a short pointer
// to AGENTS.md. Which files exist, how long they are, the relative path back to
// AGENTS.md and the replacement text are all fixed, so they live here.
import fs from "node:fs";
import path from "node:path";
import { EXIT, fail, out, parseArgs, run, readText, isDir } from "./common.mjs";
const USAGE = `
agent-files.mjs: detect AI agent config files and replace them with AGENTS.md pointers. JSON on stdout.
node agent-files.mjs detect [--root
]
Every config file present, with its line count, whether it has custom
content (more than 10 lines) and the pointer it would get.
node agent-files.mjs apply [ ...] [--root ] [--dry-run]
node agent-files.mjs apply --all [--root ] [--dry-run]
Replace the confirmed entries (ids from detect: CLAUDE.md, GEMINI.md,
.cursorrules, .github/copilot-instructions.md, .cursor/rules,
.windsurf/rules). A rules folder loses its .md files (and .mdc, for Cursor) and gets one
reference.md. Only run this for entries the user confirmed.
An entry that is AGENTS.md itself through a symlink or hard link
(detect: linkedToAgents) is refused by id and skipped by --all
("skipped-linked"). A symlink to any other file is removed and replaced,
never written through.
Exit: 0 ok · 2 bad arguments · 3 AGENTS.md missing or an id not present ·
5 refused (an entry linked to AGENTS.md).
`;
// id, title, where the pointer goes, and the relative path back to AGENTS.md.
const TARGETS = [
{ id: "CLAUDE.md", title: "CLAUDE.md", file: "CLAUDE.md", ref: "./AGENTS.md" },
{ id: "GEMINI.md", title: "GEMINI.md", file: "GEMINI.md", ref: "./AGENTS.md" },
{ id: ".cursorrules", title: ".cursorrules", file: ".cursorrules", ref: "./AGENTS.md" },
{ id: ".github/copilot-instructions.md", title: "Copilot Instructions", file: ".github/copilot-instructions.md", ref: "../AGENTS.md" },
{ id: ".cursor/rules", title: "Project Rules", dir: ".cursor/rules", ref: "../../AGENTS.md" },
{ id: ".windsurf/rules", title: "Project Rules", dir: ".windsurf/rules", ref: "../../AGENTS.md" },
];
const CUSTOM_LINES = 10;
// CLAUDE.md gets its own template: Claude Code auto-loads it, so it carries the
// directive that makes AGENTS.md the mandatory first read.
function claudeTemplate() {
return [
"# CLAUDE.md",
"",
"**CRITICAL — MANDATORY FIRST STEP: You MUST read [AGENTS.md](./AGENTS.md) before responding to ANY user message, including simple questions. Do NOT skip this step regardless of how trivial the request appears. No exceptions.**",
"",
"See AGENTS.md for complete project documentation including:",
"- Development commands and setup",
"- Architecture overview",
"- Environment variables",
"- Testing patterns",
"- Deployment guides",
"- Keeping this file current / Failure log",
"- Section details in .agents-docs/",
"",
"This file exists for Claude Code auto-loading. All AI coding agents should reference AGENTS.md.",
"",
].join("\n");
}
function referenceTemplate(title, ref) {
return [
`# ${title}`,
"",
`See [AGENTS.md](${ref}) for complete project documentation including:`,
"- Development commands and setup",
"- Architecture overview",
"- Environment variables",
"- Testing patterns",
"- Deployment guides",
"- Keeping this file current / Failure log",
"- Section details in .agents-docs/",
"",
].join("\n");
}
function templateFor(t) {
return t.id === "CLAUDE.md" ? claudeTemplate() : referenceTemplate(t.title, t.ref);
}
// A CRLF checkout of a pointer file is still the pointer.
function lf(text) {
return text === null ? null : text.replace(/\r\n/g, "\n");
}
const samePath = (a, b) => (process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b);
// True when p is AGENTS.md itself: a symlink resolving to it, or a hard link to
// the same inode. Writing a pointer through either would replace AGENTS.md.
// Some platforms report ino 0 for every file, so 0 never counts as a match.
function isAgentsFile(p, agents) {
try {
if (samePath(fs.realpathSync.native(p), fs.realpathSync.native(agents))) return true;
const a = fs.statSync(p, { bigint: true });
const b = fs.statSync(agents, { bigint: true });
return a.ino !== 0n && a.ino === b.ino && a.dev === b.dev;
} catch {
return false;
}
}
function lineCount(text) {
if (!text) return 0;
return text.replace(/\r?\n$/, "").split(/\r?\n/).length;
}
function detect(root) {
const agents = path.join(root, "AGENTS.md");
const found = [];
for (const t of TARGETS) {
if (t.file) {
const text = readText(path.join(root, t.file));
if (text === null) continue;
const lines = lineCount(text);
found.push({
id: t.id,
title: t.title,
files: [{ path: t.file, lines }],
lines,
custom: lines > CUSTOM_LINES,
alreadyPointer: lf(text) === templateFor(t),
linkedToAgents: isAgentsFile(path.join(root, t.file), agents),
writes: t.file,
pointsTo: t.ref,
});
} else {
const dir = path.join(root, t.dir);
if (!isDir(dir)) continue;
// Cursor's own rule files are .mdc; leaving them would keep a second source of rules.
const exts = t.id === ".cursor/rules" ? [".md", ".mdc"] : [".md"];
const mds = fs.readdirSync(dir).filter((n) => exts.some((e) => n.toLowerCase().endsWith(e)) && !isDir(path.join(dir, n))).sort();
if (!mds.length) continue;
const files = mds.map((n) => ({ path: `${t.dir}/${n}`, lines: lineCount(readText(path.join(dir, n))) }));
const lines = files.reduce((n, f) => n + f.lines, 0);
found.push({
id: t.id,
title: t.title,
files,
lines,
custom: files.some((f) => f.lines > CUSTOM_LINES),
alreadyPointer: mds.length === 1 && mds[0] === "reference.md" && lf(readText(path.join(dir, "reference.md"))) === templateFor(t),
linkedToAgents: mds.some((n) => isAgentsFile(path.join(dir, n), agents)),
writes: `${t.dir}/reference.md`,
deletes: files.map((f) => f.path).filter((p) => !p.endsWith("/reference.md")),
pointsTo: t.ref,
});
}
}
return found;
}
run(USAGE, async (argv) => {
const args = parseArgs(argv, { booleans: ["dry-run", "all"], values: ["root"] });
const cmd = args._[0];
const root = path.resolve(args.root || ".");
const hasAgents = fs.existsSync(path.join(root, "AGENTS.md"));
if (cmd === "detect") {
const found = detect(root);
out({
ok: true,
root,
hasAgents,
found,
warnings: found.filter((f) => f.custom && !f.alreadyPointer && !f.linkedToAgents).map((f) => `${f.id} has custom content that will be replaced (${f.lines} lines).`),
...(found.length ? {} : { note: "No AI agent config files found: skip this step silently." }),
});
return;
}
if (cmd !== "apply") fail(EXIT.USAGE, "unknown-command", cmd ? `Unknown command "${cmd}".` : "No command given.", "Commands: detect, apply. Run with --help.");
if (!hasAgents) fail(EXIT.NOT_FOUND, "no-agents-md", "AGENTS.md does not exist, so there is nothing to point these files at.", "Create AGENTS.md first.");
const ids = args._.slice(1);
if (!args.all && !ids.length) fail(EXIT.USAGE, "nothing-selected", "Name the entries to replace, or pass --all.", "Use the ids `detect` printed, for the entries the user confirmed.");
const found = detect(root);
const chosen = args.all ? found : ids.map((id) => {
const hit = found.find((f) => f.id === id.replace(/\\/g, "/").replace(/\/$/, ""));
if (!hit) fail(EXIT.NOT_FOUND, "not-present", `"${id}" is not one of the detected entries (${found.map((f) => f.id).join(", ") || "none"}).`, "Run `detect` and use its ids.");
return hit;
});
// Checked before anything is written, so a refusal leaves every file as it was.
const linked = chosen.find((c) => c.linkedToAgents);
if (linked && !args.all) {
fail(EXIT.REFUSED, "linked-to-agents", `${linked.id} is AGENTS.md itself (via a symlink or hard link); replacing it would overwrite AGENTS.md with the pointer.`, `Leave ${linked.id} as it is: it already serves AGENTS.md. Rerun apply without it.`);
}
const actions = [];
for (const entry of chosen) {
if (entry.linkedToAgents) {
actions.push({ action: "skipped-linked", path: entry.writes });
continue;
}
const t = TARGETS.find((x) => x.id === entry.id);
const content = templateFor(t);
for (const del of entry.deletes || []) {
actions.push({ action: "delete", path: del });
if (!args["dry-run"]) fs.rmSync(path.join(root, del), { force: true });
}
const target = path.join(root, entry.writes);
const changed = lf(readText(target)) !== content;
actions.push({ action: changed ? "write" : "unchanged", path: entry.writes });
if (changed && !args["dry-run"]) {
fs.mkdirSync(path.dirname(target), { recursive: true });
// A symlink (or a hard link) to some other file is replaced, not written
// through, so the file it shares content with is left alone.
let st = null;
try {
st = fs.lstatSync(target);
} catch {}
if (st && (st.isSymbolicLink() || st.nlink > 1)) fs.rmSync(target, { force: true });
fs.writeFileSync(target, content);
}
}
out({ ok: true, root, dryRun: !!args["dry-run"], updated: chosen.filter((c) => !c.linkedToAgents).map((c) => c.id), actions });
});