Skip to content

Commit 8abdd59

Browse files
n0mahdclaude
andcommitted
feat(web): group instructions under Project and Global, and move CLAUDE.md into AGENTS.md
The Instructions list mixed made-up names ("This project", "Just you", "Claude's own notes") with gray explanations, and gave an agent's own Global file a permanent row. Rows are now file names under Project and Global headings, and the only second line is a problem with its fix. - CLAUDE.local.md sits under Project. Files no enabled agent reads, such as CLAUDE.md with Claude off, aren't listed. - An agent with its own Global AGENTS.md shows as a line on Global AGENTS.md, with Use Global instead, rather than as its own row. - A project's CLAUDE.md can be moved to AGENTS.md, or merged into an AGENTS.md that already exists: its text goes at the end and CLAUDE.md is deleted. When Claude would still skip AGENTS.md afterwards, the same confirmation turns AGENTS.md on for Claude. - A CLAUDE.md that only imports AGENTS.md, or is a link to it, gets no row. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 6d6ea98 commit 8abdd59

15 files changed

Lines changed: 1331 additions & 425 deletions

‎apps/server/src/instructions/InstructionCatalog.test.ts‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -394,6 +394,59 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("InstructionCatalog"
394394
}),
395395
);
396396

397+
it.effect(
398+
"gives a CLAUDE.md that only imports AGENTS.md no entry, and keeps the import working",
399+
() =>
400+
Effect.gen(function* () {
401+
const { home, project, write } = yield* makeMachine;
402+
yield* write("repos/app/AGENTS.md", "rules");
403+
for (const only of ["@AGENTS.md\n", "\n@./AGENTS.md\n\n"]) {
404+
yield* write("repos/app/CLAUDE.md", only);
405+
yield* onMachine(home, CLAUDE, (catalog) =>
406+
Effect.gen(function* () {
407+
const { entries } = yield* listed(catalog, { cwd: project });
408+
expect(entries.map((entry) => entry.id)).not.toContain("project:claude:CLAUDE.md");
409+
expect(claudeAccess(entries)).toMatchObject({ state: "import" });
410+
}),
411+
);
412+
}
413+
// Anything else in the file keeps its entry, and so does an empty one.
414+
for (const text of ["@AGENTS.md\n- Run the tests.\n", ""]) {
415+
yield* write("repos/app/CLAUDE.md", text);
416+
yield* onMachine(home, CLAUDE, (catalog) =>
417+
Effect.gen(function* () {
418+
const { entries } = yield* listed(catalog, { cwd: project });
419+
expect(entries.map((entry) => entry.id)).toContain("project:claude:CLAUDE.md");
420+
}),
421+
);
422+
}
423+
}),
424+
);
425+
426+
it.effect.skipIf(!symlinksSupported)(
427+
"gives a CLAUDE.md that is the same file as AGENTS.md no entry, whichever links to the other",
428+
() =>
429+
Effect.gen(function* () {
430+
const { home, fs, path, project, write, link } = yield* makeMachine;
431+
for (const [real, linked] of [
432+
["AGENTS.md", "CLAUDE.md"],
433+
["CLAUDE.md", "AGENTS.md"],
434+
] as const) {
435+
yield* fs.remove(path.join(project, "AGENTS.md"), { force: true });
436+
yield* fs.remove(path.join(project, "CLAUDE.md"), { force: true });
437+
yield* write(`repos/app/${real}`, "rules");
438+
yield* link(`repos/app/${real}`, `repos/app/${linked}`);
439+
yield* onMachine(home, CLAUDE, (catalog) =>
440+
Effect.gen(function* () {
441+
const { entries } = yield* listed(catalog, { cwd: project });
442+
expect(entries.map((entry) => entry.id)).not.toContain("project:claude:CLAUDE.md");
443+
expect(claudeAccess(entries)).toMatchObject({ state: "import" });
444+
}),
445+
);
446+
}
447+
}),
448+
);
449+
397450
it.effect("reports a settings.json that isn't JSON and falls back to Claude's default", () =>
398451
Effect.gen(function* () {
399452
const { home, project, write } = yield* makeMachine;

‎apps/server/src/instructions/InstructionCatalog.ts‎

Lines changed: 36 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -516,6 +516,11 @@ const make = Effect.gen(function* () {
516516
readonly sizes: ReadonlyMap<string, number>;
517517
/** Some Claude file in the top folder imports the project's AGENTS.md. */
518518
readonly claudeImportsAgentsMd: boolean;
519+
/**
520+
* The top folder's CLAUDE.md holds nothing but that import, or is the same file as AGENTS.md
521+
* through a link, so it has nothing to show.
522+
*/
523+
readonly claudeMdOnlyImports: boolean;
519524
}
520525

521526
const loadProject = Effect.fnUntraced(function* (
@@ -536,23 +541,40 @@ const make = Effect.gen(function* () {
536541
for (const [name, size] of found) if (size !== undefined) sizes.set(name, size);
537542
const agentsMd = path.join(cwd, "AGENTS.md");
538543
let claudeImportsAgentsMd = false;
544+
let claudeMdOnlyImports = false;
545+
if (sizes.has("CLAUDE.md") && sizes.has("AGENTS.md")) {
546+
const [claudeReal, agentsReal] = yield* Effect.all([
547+
fileSystem.realPath(path.join(cwd, "CLAUDE.md")).pipe(Effect.option),
548+
fileSystem.realPath(agentsMd).pipe(Effect.option),
549+
]);
550+
if (
551+
Option.isSome(claudeReal) &&
552+
Option.isSome(agentsReal) &&
553+
claudeReal.value === agentsReal.value
554+
) {
555+
claudeImportsAgentsMd = true;
556+
claudeMdOnlyImports = true;
557+
}
558+
}
539559
for (const name of ["CLAUDE.md", ".claude/CLAUDE.md", PERSONAL_FILE]) {
540560
if (!sizes.has(name)) continue;
561+
if (name === "CLAUDE.md" && claudeMdOnlyImports) continue;
541562
const file = path.join(cwd, name);
542563
const read = yield* textOf(file);
543-
if (
544-
read._tag === "Read" &&
545-
hasAgentsMdImport(read.text, {
546-
path,
547-
agentsMdPath: agentsMd,
548-
claudeMdDirectory: path.dirname(file),
549-
homeDirectory,
550-
})
551-
) {
552-
claudeImportsAgentsMd = true;
564+
if (read._tag !== "Read") continue;
565+
const target = {
566+
path,
567+
agentsMdPath: agentsMd,
568+
claudeMdDirectory: path.dirname(file),
569+
homeDirectory,
570+
} satisfies AgentsMdImportTarget;
571+
if (!hasAgentsMdImport(read.text, target)) continue;
572+
claudeImportsAgentsMd = true;
573+
if (name === "CLAUDE.md" && removeAgentsMdImport(read.text, target).trim() === "") {
574+
claudeMdOnlyImports = true;
553575
}
554576
}
555-
return { cwd, sizes, claudeImportsAgentsMd } satisfies ProjectFacts;
577+
return { cwd, sizes, claudeImportsAgentsMd, claudeMdOnlyImports } satisfies ProjectFacts;
556578
});
557579

558580
const accessOf = (
@@ -795,6 +817,9 @@ const make = Effect.gen(function* () {
795817
// so they can be created. The local one only when an agent would read it.
796818
const creatable = root.kind === "shared" || root.kind === "claudeLocal";
797819
if (size === undefined && !creatable) continue;
820+
// Many repos keep a one-line CLAUDE.md that only points Claude at AGENTS.md. It already
821+
// does its job, so it gets no entry, as a Global CLAUDE.md that only imports Global.
822+
if (root.name === "CLAUDE.md" && project.claudeMdOnlyImports) continue;
798823
const access = instances.flatMap((instance) => {
799824
const found = projectAccess(instance, root.name, project, claudeByInstance);
800825
return found === undefined ? [] : [found];

‎apps/server/src/instructions/InstructionManager.test.ts‎

Lines changed: 139 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -747,7 +747,7 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("InstructionManager"
747747
yield* write("repos/app/CLAUDE.md", "rules");
748748
yield* onMachine(home, { ...CLAUDE, registered: [project] }, ({ manager }) =>
749749
Effect.gen(function* () {
750-
yield* manager.share({ cwd: project, id: "project:claude:CLAUDE.md" });
750+
yield* manager.share({ cwd: project, id: "project:claude:CLAUDE.md", merge: false });
751751

752752
expect(yield* read("repos/app/AGENTS.md")).toBe("rules");
753753
expect(yield* fs.exists(path.join(project, "CLAUDE.md"))).toBe(false);
@@ -767,22 +767,22 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("InstructionManager"
767767
yield* onMachine(home, { ...CLAUDE, registered: [project] }, ({ manager }) =>
768768
Effect.gen(function* () {
769769
const exists = yield* manager
770-
.share({ cwd: project, id: "project:claude:CLAUDE.md" })
770+
.share({ cwd: project, id: "project:claude:CLAUDE.md", merge: false })
771771
.pipe(Effect.flip);
772772
expect(exists.reason).toBe("exists");
773773
expect(yield* read("repos/app/AGENTS.md")).toBe("agents");
774774
expect(yield* read("repos/app/CLAUDE.md")).toBe("claude");
775775

776776
const nested = yield* manager
777-
.share({ cwd: project, id: "project:claude:.claude/CLAUDE.md" })
777+
.share({ cwd: project, id: "project:claude:.claude/CLAUDE.md", merge: false })
778778
.pipe(Effect.flip);
779779
expect(nested.reason).toBe("unknownEntry");
780780
}),
781781
);
782782
yield* onMachine(home, CLAUDE, ({ manager }) =>
783783
Effect.gen(function* () {
784784
const unregistered = yield* manager
785-
.share({ cwd: project, id: "project:claude:CLAUDE.md" })
785+
.share({ cwd: project, id: "project:claude:CLAUDE.md", merge: false })
786786
.pipe(Effect.flip);
787787
expect(unregistered.reason).toBe("unregisteredProject");
788788
}),
@@ -796,7 +796,7 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("InstructionManager"
796796
yield* onMachine(home, { ...CLAUDE, registered: [project] }, ({ manager }) =>
797797
Effect.gen(function* () {
798798
const error = yield* manager
799-
.share({ cwd: project, id: "project:claude:CLAUDE.md" })
799+
.share({ cwd: project, id: "project:claude:CLAUDE.md", merge: false })
800800
.pipe(Effect.flip);
801801
expect(error.reason).toBe("notFound");
802802
}),
@@ -805,6 +805,140 @@ it.layer(NodeServices.layer, { excludeTestServices: true })("InstructionManager"
805805
);
806806
});
807807

808+
describe("share with merge", () => {
809+
const CLAUDE_ID = "project:claude:CLAUDE.md";
810+
811+
it.effect("adds CLAUDE.md's text to the end of AGENTS.md, then deletes CLAUDE.md", () =>
812+
Effect.gen(function* () {
813+
const { home, project, write, read, fs, path } = yield* makeMachine;
814+
yield* write("repos/app/AGENTS.md", "# App\n- Use pnpm.");
815+
yield* write("repos/app/CLAUDE.md", "\n- Run the tests.\n\n");
816+
yield* onMachine(home, { ...CLAUDE, registered: [project] }, ({ manager }) =>
817+
Effect.gen(function* () {
818+
yield* manager.share({ cwd: project, id: CLAUDE_ID, merge: true });
819+
820+
expect(yield* read("repos/app/AGENTS.md")).toBe(
821+
"# App\n- Use pnpm.\n\n- Run the tests.\n",
822+
);
823+
expect(yield* fs.exists(path.join(project, "CLAUDE.md"))).toBe(false);
824+
}),
825+
);
826+
}),
827+
);
828+
829+
it.effect("takes the line that imports AGENTS.md out of what it adds", () =>
830+
Effect.gen(function* () {
831+
const { home, project, write, read } = yield* makeMachine;
832+
yield* write("repos/app/AGENTS.md", "rules\n");
833+
yield* write("repos/app/CLAUDE.md", "@AGENTS.md\n\nextra rule\n");
834+
yield* onMachine(home, { ...CLAUDE, registered: [project] }, ({ manager }) =>
835+
Effect.gen(function* () {
836+
yield* manager.share({ cwd: project, id: CLAUDE_ID, merge: true });
837+
expect(yield* read("repos/app/AGENTS.md")).toBe("rules\n\nextra rule\n");
838+
}),
839+
);
840+
}),
841+
);
842+
843+
it.effect(
844+
"only deletes a CLAUDE.md that is just the import, or that AGENTS.md has already",
845+
() =>
846+
Effect.gen(function* () {
847+
const { home, project, write, read, fs, path } = yield* makeMachine;
848+
yield* write("repos/app/AGENTS.md", "- Use pnpm.\n- Run the tests.\n");
849+
yield* onMachine(home, { ...CLAUDE, registered: [project] }, ({ manager }) =>
850+
Effect.gen(function* () {
851+
for (const text of ["@./AGENTS.md\n", "- Run the tests.\n", " \n"]) {
852+
yield* write("repos/app/CLAUDE.md", text);
853+
yield* manager.share({ cwd: project, id: CLAUDE_ID, merge: true });
854+
855+
expect(yield* read("repos/app/AGENTS.md")).toBe("- Use pnpm.\n- Run the tests.\n");
856+
expect(yield* fs.exists(path.join(project, "CLAUDE.md"))).toBe(false);
857+
}
858+
}),
859+
);
860+
}),
861+
);
862+
863+
it.effect("refuses without an AGENTS.md, and leaves CLAUDE.md alone", () =>
864+
Effect.gen(function* () {
865+
const { home, project, write, read } = yield* makeMachine;
866+
yield* write("repos/app/CLAUDE.md", "rules");
867+
yield* onMachine(home, { ...CLAUDE, registered: [project] }, ({ manager }) =>
868+
Effect.gen(function* () {
869+
const error = yield* manager
870+
.share({ cwd: project, id: CLAUDE_ID, merge: true })
871+
.pipe(Effect.flip);
872+
expect(error.reason).toBe("notFound");
873+
expect(yield* read("repos/app/CLAUDE.md")).toBe("rules");
874+
}),
875+
);
876+
}),
877+
);
878+
879+
it.effect("refuses when the result would be over 1 MB, and changes nothing", () =>
880+
Effect.gen(function* () {
881+
const { home, project, write, read } = yield* makeMachine;
882+
yield* write("repos/app/AGENTS.md", "a".repeat(700_000));
883+
yield* write("repos/app/CLAUDE.md", "b".repeat(700_000));
884+
yield* onMachine(home, { ...CLAUDE, registered: [project] }, ({ manager }) =>
885+
Effect.gen(function* () {
886+
const error = yield* manager
887+
.share({ cwd: project, id: CLAUDE_ID, merge: true })
888+
.pipe(Effect.flip);
889+
expect(error.reason).toBe("tooLarge");
890+
expect((yield* read("repos/app/AGENTS.md")).length).toBe(700_000);
891+
expect((yield* read("repos/app/CLAUDE.md")).length).toBe(700_000);
892+
}),
893+
);
894+
}),
895+
);
896+
897+
it.effect.skipIf(!symlinksSupported)(
898+
"writes through a linked AGENTS.md, and removes a CLAUDE.md that is a link without its target",
899+
() =>
900+
Effect.gen(function* () {
901+
const { home, project, write, link, read, fs, path } = yield* makeMachine;
902+
yield* write("dotfiles/app-agents.md", "rules\n");
903+
yield* write("dotfiles/app-claude.md", "more rules\n");
904+
yield* link("dotfiles/app-agents.md", "repos/app/AGENTS.md");
905+
yield* link("dotfiles/app-claude.md", "repos/app/CLAUDE.md");
906+
yield* onMachine(home, { ...CLAUDE, registered: [project] }, ({ manager }) =>
907+
Effect.gen(function* () {
908+
yield* manager.share({ cwd: project, id: CLAUDE_ID, merge: true });
909+
910+
// The text lands in the real file, so AGENTS.md is still a link to it.
911+
expect(yield* read("dotfiles/app-agents.md")).toBe("rules\n\nmore rules\n");
912+
expect(yield* fs.readLink(path.join(project, "AGENTS.md"))).toBe(
913+
path.join(home, "dotfiles/app-agents.md"),
914+
);
915+
expect(yield* fs.exists(path.join(project, "CLAUDE.md"))).toBe(false);
916+
expect(yield* read("dotfiles/app-claude.md")).toBe("more rules\n");
917+
}),
918+
);
919+
}),
920+
);
921+
922+
it.effect.skipIf(!symlinksSupported)(
923+
"won't delete a CLAUDE.md that the project's AGENTS.md is a link to",
924+
() =>
925+
Effect.gen(function* () {
926+
const { home, project, write, link, read } = yield* makeMachine;
927+
yield* write("repos/app/CLAUDE.md", "rules");
928+
yield* link("repos/app/CLAUDE.md", "repos/app/AGENTS.md");
929+
yield* onMachine(home, { ...CLAUDE, registered: [project] }, ({ manager }) =>
930+
Effect.gen(function* () {
931+
const error = yield* manager
932+
.share({ cwd: project, id: CLAUDE_ID, merge: true })
933+
.pipe(Effect.flip);
934+
expect(error.reason).toBe("exists");
935+
expect(yield* read("repos/app/CLAUDE.md")).toBe("rules");
936+
}),
937+
);
938+
}),
939+
);
940+
});
941+
808942
describe("adopt", () => {
809943
it.effect.skipIf(!symlinksSupported)(
810944
"adds the agent's text to the shared file under its name, then links the agent to it",

‎apps/server/src/instructions/InstructionManager.ts‎

Lines changed: 51 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@
1313
* already has a file of its own is moved over with `adopt`, which keeps that file's text in the
1414
* Global file first.
1515
* - The only writes that take a real file are `adopt` (its text is kept first), `share` (a
16-
* rename, refused when AGENTS.md exists) and `delete`.
16+
* rename, refused when AGENTS.md exists; or a merge, where CLAUDE.md's text is written to the end
17+
* of AGENTS.md before CLAUDE.md goes) and `delete`.
1718
*
1819
* @module InstructionManager
1920
*/
@@ -112,7 +113,10 @@ export class InstructionManager extends Context.Service<
112113
readonly setClaudeSetting: (
113114
input: ClaudeInstructionSettingInput,
114115
) => Effect.Effect<void, InstructionError>;
115-
/** Rename a project's CLAUDE.md to AGENTS.md, when it has no AGENTS.md. */
116+
/**
117+
* Rename a project's CLAUDE.md to AGENTS.md, when it has no AGENTS.md; or with `merge`, add its
118+
* text to the end of the project's AGENTS.md and delete it.
119+
*/
116120
readonly share: (input: InstructionShareInput) => Effect.Effect<void, InstructionError>;
117121
/** Add an agent's own text to the Global file, then make the agent's file a link to it. */
118122
readonly adopt: (input: InstructionAdoptInput) => Effect.Effect<void, InstructionError>;
@@ -484,10 +488,52 @@ const make = Effect.gen(function* () {
484488
const from = yield* inspectAt(entry.path);
485489
if (!from.isFile) return yield* refuse("notFound", "That file doesn't exist.");
486490
const agentsMd = path.join(path.dirname(entry.path), "AGENTS.md");
487-
if ((yield* inspectAt(agentsMd)).present) {
488-
return yield* refuse("exists", "This project already has an AGENTS.md.");
491+
const into = yield* inspectAt(agentsMd);
492+
if (!input.merge) {
493+
if (into.present)
494+
return yield* refuse("exists", "This project already has an AGENTS.md.");
495+
return yield* guard(fileSystem.rename(entry.path, agentsMd), cannotWrite(agentsMd));
496+
}
497+
if (!into.isFile) {
498+
return yield* refuse("notFound", "This project has no AGENTS.md to merge into.");
499+
}
500+
// AGENTS.md is a link to this very file, so deleting the file would take AGENTS.md too.
501+
if (from.linkTarget === undefined && into.real === from.real) {
502+
return yield* refuse("exists", "AGENTS.md is a link to CLAUDE.md.");
503+
}
504+
505+
const claudeText = yield* readTextAt(entry.path);
506+
if (claudeText._tag === "TooLarge") return yield* refuse("tooLarge", LIMIT_MESSAGE);
507+
if (claudeText._tag !== "Read") {
508+
return yield* refuse("readOnly", "T3 Code can't read that file as text.");
489509
}
490-
yield* guard(fileSystem.rename(entry.path, agentsMd), cannotWrite(agentsMd));
510+
const agentsTarget = yield* writeTargetAt(agentsMd);
511+
const agentsText = yield* readTextAt(agentsTarget);
512+
if (agentsText._tag === "TooLarge") return yield* refuse("tooLarge", LIMIT_MESSAGE);
513+
if (agentsText._tag !== "Read") {
514+
return yield* refuse("readOnly", "T3 Code can't read AGENTS.md as text.");
515+
}
516+
517+
// A line that imports AGENTS.md would only point AGENTS.md at itself, so it doesn't move.
518+
const view = yield* catalog.shared;
519+
const own = removeAgentsMdImport(claudeText.text, {
520+
path,
521+
agentsMdPath: agentsMd,
522+
claudeMdDirectory: path.dirname(entry.path),
523+
homeDirectory: view.homeDirectory,
524+
}).trim();
525+
if (own !== "" && !agentsText.text.includes(own)) {
526+
const joined =
527+
agentsText.text.trim() === ""
528+
? `${own}\n`
529+
: `${agentsText.text}${agentsText.text.endsWith("\n") ? "" : "\n"}\n${own}\n`;
530+
if (encoder.encode(joined).byteLength > INSTRUCTION_MAX_BYTES) {
531+
return yield* refuse("tooLarge", LIMIT_MESSAGE);
532+
}
533+
yield* writeText(agentsTarget, joined);
534+
}
535+
// The text is in AGENTS.md now, so CLAUDE.md can go. A link goes and what it points at stays.
536+
yield* guard(fileSystem.remove(entry.path), cannotWrite(entry.path));
491537
}),
492538
);
493539
},

0 commit comments

Comments
 (0)