claude-memory-admin 1.10.1 → 1.10.2

package/README.md

@@ -108,9 +108,25 @@ safety net and not a place you browse.
   `~/.claude/settings.json`. A value that is neither absolute nor `~/`-prefixed
   is reported rather than quietly ignored.
 - **Whether Claude is still writing.** A project with `autoMemoryEnabled` off, or
-  `CLAUDE_CODE_DISABLE_AUTO_MEMORY` set, has a store that will never grow again,
-  which on disk is indistinguishable from one Claude has not learned anything
-  about yet. The project header says which it is, and names the file that decided.
+  `CLAUDE_CODE_DISABLE_AUTO_MEMORY` set - in the environment or in the `env`
+  block of any settings layer - has a store that will never grow again, which on
+  disk is indistinguishable from one Claude has not learned anything about yet.
+  The project header says which it is, and names the file that decided.
+- **Which subagent still asks for its memory.** A subagent store exists because
+  some agent file carried a `memory: user | project | local` field, and it stays
+  exactly where it is after that field moves to another scope or is removed. Each
+  store is shown next to the definition that declares it - from `agents/` in the
+  user scope and in each repository - and one that nothing declares any more is
+  marked `orphan`, one whose agent moved scope `moved`. Because subagent memory
+  is part of auto memory, turning auto memory off marks every one of them
+  `inert`: the `memory:` field stops having any effect, and the agent starts with
+  no memory instructions and no file tools at all.
+- **A config directory that is not `~/.claude`.** `CLAUDE_CONFIG_DIR` moves the
+  projects root, the agent definitions, the agent memory, the user `CLAUDE.md` and
+  rules, and the settings file together, and all of them are read from wherever it
+  points. The Environment tab names the directory and says whether the environment
+  or the default chose it. A `~/` written by hand is expanded here rather than left
+  to the shell, because `cmd` and PowerShell do not expand it.
 - **Search across every project**: names, descriptions, bodies and index hooks,
   with snippets and match highlighting. Press `/` to jump to it.
 - **Read each memory** with its frontmatter as structured metadata and
@@ -291,15 +307,22 @@ five and shows, per key, the value that wins and the ones it shadows, struck
 through, each labelled with the file it came from:
 
 `autoMemoryEnabled`, `autoMemoryDirectory`, `claudeMdExcludes` and
-`cleanupPeriodDays`, plus `CLAUDE_CODE_DISABLE_AUTO_MEMORY` when it is set in the
-environment, where it outranks every file.
+`cleanupPeriodDays`, plus `CLAUDE_CODE_DISABLE_AUTO_MEMORY` wherever it is set:
+in the environment, where it outranks every file, or in the `env` block of any of
+the five, which a session exports before it starts and which reading `process.env`
+alone would miss. `CLAUDE_CONFIG_DIR` is named here too, since it decides where
+all five of those files are looked for in the first place.
 
 It also names the failures that are otherwise silent:
 
 - A settings file that exists but is not valid JSON. Claude Code ignores the
   whole file, so every value in it is doing nothing, and nothing says so.
 - A file that parses but is not an object, or cannot be read at all.
-- An `autoMemoryDirectory` that is neither absolute nor `~/`-prefixed.
+- An `autoMemoryDirectory` that is neither absolute nor `~/`-prefixed. A Windows
+  path is accepted on any platform, because a settings file is routinely shared
+  between machines.
+- A `CLAUDE_CONFIG_DIR` that is not absolute, which Claude Code would not accept
+  either: the default is used and the fact is reported rather than swallowed.
 - A value Claude Code accepts the key of but not the number, like a
   `cleanupPeriodDays` below 1: it shows what is written *and* what applies.
 
@@ -453,6 +476,13 @@ claude-memory-admin --root /tmp/memory-snapshot
 ## Safety
 
 - Binds `127.0.0.1`; no telemetry, no network calls.
+- Runs on macOS, Linux and Windows. Line endings are the part of that which is not
+  cosmetic: a `MEMORY.md` saved by a Windows editor is CRLF, and a carriage return
+  is not something JavaScript's `.` matches, so a file like that once parsed as if
+  it were empty - no index entries, no frontmatter, every memory an orphan. It is
+  read correctly now, and a rewrite ends its lines the way it found them: a file
+  that came back half CRLF and half LF would show every line as changed in git, on
+  a change you never made.
 - Reads only `~/.claude/projects`, the agent memory directories and the `CLAUDE.md`
   chain, unless you switch on the path check above, which then also walks that one
   project's directory. It only ever reads: no path a memory names is opened, only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory-admin",
-  "version": "1.10.1",
+  "version": "1.10.2",
   "description": "Browse, audit and prune the auto memory Claude Code keeps under ~/.claude/projects",
   "keywords": [
     "claude",

package/public/views/cost.mjs

@@ -18,8 +18,37 @@ const AGENT_PROBLEMS = {
   'name-mismatch': 'Name and filename disagree',
   'unknown-model': 'Unrecognised model',
   'unknown-effort': 'Unrecognised effort',
+  'unknown-memory-scope': 'Unrecognised memory scope',
 };
 
+function memoryLine(agent, stores) {
+  if (!agent.memory) {
+    const stale = stores.filter((store) => store.agentName === agent.name && !store.linked);
+    if (!stale.length) return null;
+    return node('div', { class: ui.agentTools }, [
+      node('span', { class: ui.badge('warn'), text: 'no memory:' }),
+      node('span', {
+        text: ` this agent declares no memory scope, but ${stale.length === 1 ? 'a directory it once wrote' : `${stale.length} directories it once wrote`} ${stale.length === 1 ? 'is' : 'are'} still on disk and nothing loads ${stale.length === 1 ? 'it' : 'them'}.`,
+      }),
+    ]);
+  }
+
+  const mine = stores.filter((store) => store.agentName === agent.name && store.linked);
+  const inert = mine.some((store) => store.inert);
+  const count = mine.reduce((sum, store) => sum + store.memoryCount, 0);
+
+  const parts = [
+    node('span', { class: ui.scopeBadge(agent.memory), text: `memory: ${agent.memory}` }),
+  ];
+  if (inert) parts.push(node('span', { class: ui.badge('warn'), text: 'inert' }));
+  parts.push(node('span', {
+    text: mine.length
+      ? ` ${count} ${count === 1 ? 'memory' : 'memories'} in ${mine.length === 1 ? 'its store' : `${mine.length} stores`}${inert ? ', frozen while auto memory is off' : ''}.`
+      : ' no store yet - the directory appears the first time it saves something.',
+  }));
+  return node('div', { class: ui.agentTools }, parts);
+}
+
 const show = (value) => (value === undefined || value === null ? 'unset' : JSON.stringify(value));
 
 const optionText = (option) => (option.note ? `${option.label} (${option.note})` : option.label);
@@ -79,7 +108,12 @@ async function saveAgent(file, field, value) {
       body: JSON.stringify({ file, field, value }),
     });
     if (state.storeId !== id) return;
-    state.aux.cost = { ...state.aux.cost, agents: data.agents, agentsDirExists: data.agentsDirExists };
+    state.aux.cost = {
+      ...state.aux.cost,
+      agents: data.agents,
+      agentsDirExists: data.agentsDirExists,
+      agentStores: data.agentStores,
+    };
     toast(value === null ? `Cleared ${field} in ${file}` : `${file}: ${field} = ${value}`);
   } catch (err) {
     toast(err.message, { error: true });
@@ -138,21 +172,30 @@ function settingCard(entry, writable) {
   return card;
 }
 
-function agentRow(agent, fields) {
+function agentRow(agent, fields, stores) {
   const row = node('div', { class: ui.agentRow });
 
-  row.append(node('div', { class: ui.agentTop }, [
+  const top = [
     node('span', { class: ui.agentName, text: agent.name }),
-    node('span', { class: ui.agentFile, text: agent.file }),
-  ]));
+    node('span', { class: ui.agentFile, text: agent.projectPath ? `${agent.projectPath}/.claude/agents/${agent.file}` : agent.file }),
+  ];
+  if (agent.scope === 'project') top.push(node('span', { class: ui.scopeBadge('project'), text: 'project' }));
+  row.append(node('div', { class: ui.agentTop }, top));
 
   if (agent.description) row.append(node('p', { class: ui.agentDesc, text: agent.description }));
   if (agent.tools) row.append(node('div', { class: ui.agentTools, text: `tools: ${agent.tools}` }));
 
-  row.append(node('div', { class: ui.agentControls }, [
-    labelled('model', picker(fields.model.options, agent.model, (value) => saveAgent(agent.file, 'model', value))),
-    labelled('effort', picker(fields.effort.options, agent.effort, (value) => saveAgent(agent.file, 'effort', value))),
-  ]));
+  const memory = memoryLine(agent, stores);
+  if (memory) row.append(memory);
+
+  if (agent.writable) {
+    row.append(node('div', { class: ui.agentControls }, [
+      labelled('model', picker(fields.model.options, agent.model, (value) => saveAgent(agent.file, 'model', value))),
+      labelled('effort', picker(fields.effort.options, agent.effort, (value) => saveAgent(agent.file, 'effort', value))),
+    ]));
+  } else {
+    row.append(node('div', { class: ui.agentTools, text: `model: ${agent.model || 'inherit'}, effort: ${agent.effort || 'default'} - read-only, this file lives in a repository.` }));
+  }
 
   for (const problem of agent.problems) {
     row.append(issue(
@@ -181,7 +224,7 @@ function agentsCard(data) {
     return card;
   }
 
-  for (const agent of data.agents) card.append(agentRow(agent, data.agentFields));
+  for (const agent of data.agents) card.append(agentRow(agent, data.agentFields, data.agentStores || []));
   return card;
 }
 

package/public/views/issue.mjs

@@ -258,5 +258,29 @@ export function renderIssue(item, memories) {
     );
   }
 
+  if (item.kind === 'agent-memory-inert') {
+    return issue(
+      'Auto memory is off, so this store is frozen',
+      `subagent memory is part of auto memory${item.setBy ? `, and ${item.setBy} turns it off` : ' and it is turned off'}. The memory: field on ${item.agentName} has no effect while that is the case: the agent starts with no memory instructions and no file tools, so nothing here is read and nothing new is written.`,
+      { bad },
+    );
+  }
+
+  if (item.kind === 'agent-store-orphan') {
+    return issue(
+      'Nothing declares this store any more',
+      `${item.defined ? `${item.agentName} exists but no longer carries a memory: field` : `no agent named ${item.agentName} was found in any scope`}. A store is created by that field and outlives it, so this directory is still holding what it learned and no session will read it again.`,
+      { bad },
+    );
+  }
+
+  if (item.kind === 'agent-store-scope-mismatch') {
+    return issue(
+      `${item.agentName} keeps its memory in the ${item.declaredScope} scope now`,
+      `this store is the ${item.scope} one${item.declaredBy ? `, but ${item.declaredBy} declares memory: ${item.declaredScope}` : ''}. The live store is the ${item.declaredScope} one; this is what the agent wrote before the field changed.`,
+      { bad },
+    );
+  }
+
   return issue(item.kind, JSON.stringify(item));
 }

package/public/views/stores.mjs

@@ -11,6 +11,26 @@ function storeSubtitle(store) {
   return `${scope} · ${store.sublabel}`;
 }
 
+function agentMarker(store) {
+  if (!String(store.kind).startsWith('agent-') || !store.linkage) return null;
+  if (store.inert) {
+    return { text: 'inert', title: `Auto memory is off${store.inertBy ? ` (${store.inertBy})` : ''}, so the memory: field has no effect and this store is frozen.` };
+  }
+  if (store.linked) return null;
+  if (store.declaredScope) {
+    return {
+      text: 'moved',
+      title: `${store.agentName} now declares memory: ${store.declaredScope}, so the live store is elsewhere and this one is stale.`,
+    };
+  }
+  return {
+    text: 'orphan',
+    title: store.defined
+      ? `${store.agentName} exists but declares no memory: field any more, so nothing loads this store.`
+      : `No agent named ${store.agentName} was found in any scope, so nothing loads this store.`,
+  };
+}
+
 function issueTitle(store) {
   const parts = [];
   if (store.issueCount) parts.push(`${store.issueCount} to fix in Cleanup`);
@@ -32,6 +52,7 @@ function storeButton(store) {
   const global = store.kind === 'global';
   const health = !global && !store.hasMemoryDir ? 'none' : store.severity || 'ok';
   const off = store.autoMemory && store.autoMemory.known && !store.autoMemory.enabled;
+  const marker = agentMarker(store);
   const active = state.activeSessions.filter((s) => s.storeId === store.id);
   return node('button', {
     class: ui.storeItem({ active: store.id === state.storeId, empty: !global && !store.hasMemoryDir }),
@@ -43,6 +64,7 @@ function storeButton(store) {
       node('span', { class: ui.storeName, text: store.label }),
       active.length ? node('span', { class: ui.dot('ok'), title: activeTitle(active) }) : null,
       off ? node('span', { class: ui.offMarker, text: 'off', title: 'Auto memory is disabled for this project' }) : null,
+      marker ? node('span', { class: ui.offMarker, text: marker.text, title: marker.title }) : null,
       global ? null : node('span', { class: ui.storeCount, text: store.hasMemoryDir ? String(store.memoryCount) : '-' }),
     ]),
     node('span', { class: ui.storePath, text: storeSubtitle(store) }),

package/server.mjs

@@ -13,7 +13,7 @@ import { buildStore } from './src/model.mjs';
 import { resolveGlobalInstructions, resolveInstructions, summarise } from './src/instructions.mjs';
 import { settingsReport, summariseSettings } from './src/settings.mjs';
 import { costReport, writeUserSetting } from './src/cost.mjs';
-import { AGENTS_DIR, AGENT_FIELDS, agentsDirExists, listAgents, setAgentField } from './src/agents.mjs';
+import { AGENTS_DIR, AGENT_FIELDS, agentsDirExists, listAllAgents, setAgentField } from './src/agents.mjs';
 import { listStores } from './src/stores.mjs';
 import { forgetPath, rememberPath } from './src/pathcache.mjs';
 import { searchAll } from './src/search.mjs';
@@ -140,6 +140,67 @@ const VERSION = (() => {
   }
 })();
 
+/**
+ * Every agent definition on the machine: the user directory plus the agents
+ * directory of each repository auto memory has already resolved a path for.
+ * Nothing here guesses at a repository that was not confirmed somewhere else.
+ */
+function allAgents() {
+  const projectPaths = listStores(ROOT)
+    .filter((store) => store.kind === 'auto' && store.pathExists)
+    .flatMap((store) => [store.path, ...(store.workingDirs || [])]);
+  return listAllAgents({ projectPaths });
+}
+
+/** Each subagent memory store next to the definition that asks for it, for the agents panel. */
+function agentStoreLinks() {
+  return listStores(ROOT)
+    .filter((store) => String(store.kind).startsWith('agent-'))
+    .map((store) => ({
+      id: store.id,
+      kind: store.kind,
+      agentName: store.agentName,
+      projectPath: store.projectPath,
+      memoryCount: store.memoryCount,
+      declaredBy: store.declaredBy ?? null,
+      declaredScope: store.declaredScope ?? null,
+      linked: Boolean(store.linked),
+      defined: Boolean(store.defined),
+      inert: Boolean(store.inert),
+      inertBy: store.inertBy ?? null,
+    }));
+}
+
+/**
+ * Hand the address to whatever opens a URL here, and never let that decide
+ * whether the server runs.
+ *
+ * `start` is a cmd.exe builtin rather than a program, so spawning it by name
+ * fails on Windows; the documented form is `cmd /c start "" <url>`, where the
+ * empty string is the window title `start` would otherwise read the URL as. On
+ * Linux `xdg-open` is simply missing on a minimal install and inside some
+ * containers. Either way the failure arrives as an async 'error' event, which
+ * with no listener is an uncaught exception that would take down a server that
+ * had already printed its address and was working perfectly well.
+ */
+function openBrowser(address) {
+  const [command, args] = process.platform === 'darwin'
+    ? ['open', [address]]
+    : process.platform === 'win32'
+      ? [process.env.COMSPEC || 'cmd.exe', ['/d', '/s', '/c', 'start', '""', address.replace(/&/g, '^&')]]
+      : ['xdg-open', [address]];
+
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true, windowsHide: true });
+    child.on('error', () => {
+      console.log('Could not open a browser automatically - open the address above yourself.');
+    });
+    child.unref();
+  } catch {
+    console.log('Could not open a browser automatically - open the address above yourself.');
+  }
+}
+
 function storeProjectDir(store) {
   // The global store is the user scope itself, which no project owns.
   if (store.kind === 'global') return null;
@@ -331,10 +392,15 @@ async function handleApi(req, res, url) {
   if (action === 'cost' && req.method === 'GET') {
     return sendJson(res, 200, {
       settings: costReport(),
-      agents: listAgents(),
+      // Project-scope definitions come along read-only: an agent with
+      // `memory: project` lives in a repository rather than in the user
+      // directory, and leaving it out would show its memory store as belonging
+      // to no agent at all.
+      agents: allAgents(),
       agentsDir: AGENTS_DIR,
       agentsDirExists: agentsDirExists(),
       agentFields: AGENT_FIELDS,
+      agentStores: agentStoreLinks(),
     });
   }
 
@@ -346,8 +412,13 @@ async function handleApi(req, res, url) {
 
   if (action === 'cost/agent' && req.method === 'POST') {
     const body = await readBody(req);
-    const agents = setAgentField(body.file, body.field, body.value ?? null);
-    return sendJson(res, 200, { agents, agentsDir: AGENTS_DIR, agentsDirExists: agentsDirExists() });
+    setAgentField(body.file, body.field, body.value ?? null);
+    return sendJson(res, 200, {
+      agents: allAgents(),
+      agentsDir: AGENTS_DIR,
+      agentsDirExists: agentsDirExists(),
+      agentStores: agentStoreLinks(),
+    });
   }
 
   if (action === 'delete-preview' && req.method === 'POST') {
@@ -484,10 +555,7 @@ export function startServer({ port, root, open = true } = {}) {
     const address = `http://localhost:${listenPort}`;
     console.log(`Memory Admin  ->  ${address}`);
     console.log(`Reading       ->  ${ROOT}`);
-    if (open && !process.env.NO_OPEN) {
-      const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-      spawn(opener, [address], { stdio: 'ignore', detached: true }).unref();
-    }
+    if (open && !process.env.NO_OPEN) openBrowser(address);
   });
   return server;
 }

package/src/agents.mjs

@@ -1,9 +1,12 @@
-// User-scope subagent definitions: ~/.claude/agents/*.md.
+// Subagent definitions: agents/*.md, in the user scope and in each repository.
 //
-// Not to be confused with ~/.claude/agent-memory (src/stores.mjs), which is what
-// those agents *remember*. This module is about what they *are*: a markdown file
-// whose frontmatter names the agent and, optionally, pins the model and effort
-// it runs at. Pinning a summariser to Haiku while a reviewer stays on Opus is the
+// Not to be confused with agent-memory (src/stores.mjs), which is what those
+// agents *remember*. This module is about what they *are*: a markdown file whose
+// frontmatter names the agent and, optionally, pins the model and effort it runs
+// at, and declares with `memory:` whether it keeps a memory directory at all.
+// That last field is the link between the two: a store exists because some file
+// here asked for it, and a store no file asks for any more is a store nothing
+// loads. Pinning a summariser to Haiku while a reviewer stays on Opus is the
 // finer-grained version of the CLAUDE_CODE_SUBAGENT_MODEL switch in src/cost.mjs,
 // which - worth remembering when both are set - outranks everything here.
 //
@@ -12,13 +15,21 @@
 // somebody wrote on purpose, and this tool has no view on it.
 
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 
+import { canonicalPath, configPath } from './config.mjs';
 import { parseFrontmatter } from './parse.mjs';
 import { writeFileAtomic } from './mutate.mjs';
 
-export const AGENTS_DIR = path.join(os.homedir(), '.claude', 'agents');
+export const AGENTS_DIR = configPath('agents');
+export const PROJECT_AGENTS_DIR = path.join('.claude', 'agents');
+
+/** The scopes `memory:` accepts, and the store kind each one produces. */
+export const MEMORY_SCOPES = {
+  user: 'agent-user',
+  project: 'agent-project',
+  local: 'agent-local',
+};
 
 const MODEL_ID = /^claude-[A-Za-z0-9._[\]-]+$/;
 
@@ -55,6 +66,7 @@ export const AGENT_PROBLEM_SEVERITY = {
   'name-mismatch': 'warn',
   'unknown-model': 'warn',
   'unknown-effort': 'warn',
+  'unknown-memory-scope': 'warn',
 };
 
 function known(field, value) {
@@ -92,9 +104,9 @@ export function safeAgentPath(dir, file) {
   return full;
 }
 
-function describeAgent(dir, file) {
+function describeAgent(dir, file, { scope = 'user', writable = true, projectPath = null } = {}) {
   const full = path.join(dir, file);
-  const stem = file.replace(/\.md$/, '');
+  const stem = path.basename(file).replace(/\.md$/, '');
 
   let text;
   try {
@@ -102,11 +114,15 @@ function describeAgent(dir, file) {
   } catch (err) {
     return {
       file,
+      scope,
+      writable: false,
+      projectPath,
       name: stem,
       description: '',
       tools: '',
       model: null,
       effort: null,
+      memory: null,
       bytes: 0,
       problems: [{ kind: 'no-frontmatter', severity: 'bad', detail: err.message }],
     };
@@ -117,6 +133,7 @@ function describeAgent(dir, file) {
   const name = scalar('name') || stem;
   const model = scalar('model') || null;
   const effort = scalar('effort') || null;
+  const memory = scalar('memory') || null;
 
   const problems = [];
   const flag = (kind, detail) => problems.push({ kind, severity: AGENT_PROBLEM_SEVERITY[kind], detail });
@@ -129,26 +146,39 @@ function describeAgent(dir, file) {
     if (scalar('name') && scalar('name') !== stem) flag('name-mismatch', `Named "${scalar('name')}" in a file called "${file}".`);
     if (model && !known('model', model)) flag('unknown-model', `model: ${model} is neither an alias nor a claude- model name.`);
     if (effort && !known('effort', effort)) flag('unknown-effort', `effort: ${effort} is not one of low, medium, high, xhigh or max.`);
+    if (memory && !Object.prototype.hasOwnProperty.call(MEMORY_SCOPES, memory)) {
+      flag('unknown-memory-scope', `memory: ${memory} is not one of user, project or local, so this agent keeps no memory directory.`);
+    }
   }
 
   return {
     file,
+    scope,
+    // Only a plain .md at the top of the user directory is rewritable: writes go
+    // through safeAgentPath, which takes a bare basename, and nothing here has
+    // any business editing a file inside somebody's repository.
+    writable: writable && file === path.basename(file),
+    projectPath,
     name,
     description: scalar('description'),
     tools: scalar('tools'),
     model,
     effort,
+    memory: memory && Object.prototype.hasOwnProperty.call(MEMORY_SCOPES, memory) ? memory : null,
+    memoryRaw: memory,
     bytes: Buffer.byteLength(text, 'utf8'),
     problems,
   };
 }
 
 /**
- * Every user-scope agent definition. A directory that is not there is the
- * ordinary state of a machine whose owner has never written one, not a failure,
- * so it answers with an empty list.
+ * Every .md under an agents directory, including the subfolders people use to
+ * group them. Claude Code scans both agent roots recursively and identifies an
+ * agent by its `name` rather than by where the file sits, so a scan that stopped
+ * at the top level would miss agents that are running.
  */
-export function listAgents({ dir = AGENTS_DIR } = {}) {
+function agentFiles(dir, prefix = '', depth = 0) {
+  if (depth > 4) return [];
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -156,12 +186,54 @@ export function listAgents({ dir = AGENTS_DIR } = {}) {
     return [];
   }
 
-  return entries
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.md') && !entry.name.startsWith('.'))
-    .map((entry) => describeAgent(dir, entry.name))
+  const files = [];
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue;
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) files.push(...agentFiles(path.join(dir, entry.name), rel, depth + 1));
+    else if (entry.isFile() && entry.name.endsWith('.md')) files.push(rel);
+  }
+  return files;
+}
+
+/**
+ * Every user-scope agent definition. A directory that is not there is the
+ * ordinary state of a machine whose owner has never written one, not a failure,
+ * so it answers with an empty list.
+ */
+export function listAgents({ dir = AGENTS_DIR } = {}) {
+  return agentFiles(dir)
+    .map((file) => describeAgent(dir, file, { scope: 'user', writable: true }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Project-scope definitions, from <repo>/.claude/agents. These are read and
+ * never written: they belong to a repository somebody else may share, and an
+ * agent with `memory: project` is normally defined here rather than in the user
+ * scope, so leaving them out would orphan the very stores this exists to explain.
+ */
+export function listProjectAgents(projectPath, { relative = PROJECT_AGENTS_DIR } = {}) {
+  if (!projectPath || !path.isAbsolute(projectPath)) return [];
+  const dir = path.join(projectPath, relative);
+  return agentFiles(dir)
+    .map((file) => describeAgent(dir, file, { scope: 'project', writable: false, projectPath }))
     .sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/** Every definition on the machine this tool can see: user scope plus each repository. */
+export function listAllAgents({ dir = AGENTS_DIR, projectPaths = [] } = {}) {
+  const agents = listAgents({ dir });
+  const seen = new Set();
+  for (const projectPath of projectPaths) {
+    const key = canonicalPath(projectPath || '');
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    agents.push(...listProjectAgents(projectPath));
+  }
+  return agents;
+}
+
 /** Whether the directory itself exists, which is what tells an empty list from a missing one. */
 export function agentsDirExists({ dir = AGENTS_DIR } = {}) {
   try {
@@ -205,7 +277,11 @@ function insertionIndex(block) {
  * that changed, never re-emit the document from a parse of it.
  */
 export function rewriteAgentField(text, field, value) {
-  const lines = text.split('\n');
+  // Rejoin with whatever the file already used. A checkout on Windows is CRLF
+  // throughout, and splitting on \n then rejoining with it would leave every
+  // line this function did not touch ending \r\n and the one it did ending \n.
+  const eol = /\r\n/.test(text) ? '\r\n' : '\n';
+  const lines = text.split(/\r?\n/);
   if (lines[0]?.trim() !== '---') {
     throw new Error('This file has no frontmatter block, so there is nothing to set.');
   }
@@ -230,7 +306,7 @@ export function rewriteAgentField(text, field, value) {
     block[at] = `${field}: ${value}`;
   }
 
-  return [lines[0], ...block, ...lines.slice(end)].join('\n');
+  return [lines[0], ...block, ...lines.slice(end)].join(eol);
 }
 
 function normaliseAgentValue(field, value) {

package/src/checks.mjs

@@ -2,6 +2,13 @@ import path from 'node:path';
 import { parseFrontmatter } from './parse.mjs';
 
 export const VALID_TYPES = ['user', 'feedback', 'project', 'reference'];
+
+/** The scope each subagent store kind stands for, for the messages below. */
+const STORE_SCOPES = {
+  'agent-user': 'user',
+  'agent-project': 'project',
+  'agent-local': 'local',
+};
 export const EMPTY_BODY_CHARS = 40;
 export const EMPTY_INSTRUCTION_CHARS = 10;
 export const HOOK_ECHO_OVERLAP = 0.9;
@@ -218,6 +225,68 @@ export function checkNoMemoryDespiteSessions(store, memories, retention) {
   }];
 }
 
+/**
+ * A subagent store nothing declares any more.
+ *
+ * The directory only exists because some agent file once carried a `memory:`
+ * field naming this scope. Rename the agent, move it to another scope or drop
+ * the field and the directory stays exactly where it is, still holding whatever
+ * it learned, and no session will ever read it again. That is invisible on disk,
+ * which is the whole reason to say it here.
+ */
+export function checkAgentStoreOrphan(store) {
+  if (!store || !store.linkage || store.linked) return [];
+  if (store.declaredScope) return [];
+
+  return [{
+    kind: 'agent-store-orphan',
+    severity: 'warn',
+    agentName: store.agentName,
+    scope: STORE_SCOPES[store.kind] || null,
+    defined: Boolean(store.defined),
+  }];
+}
+
+/** The agent still exists, but its `memory:` names a different scope than this store. */
+export function checkAgentStoreScopeMismatch(store) {
+  if (!store || !store.linkage || store.linked) return [];
+  if (!store.declaredScope) return [];
+
+  return [{
+    kind: 'agent-store-scope-mismatch',
+    severity: 'warn',
+    agentName: store.agentName,
+    scope: STORE_SCOPES[store.kind] || null,
+    declaredScope: store.declaredScope,
+    declaredBy: store.declaredBy,
+  }];
+}
+
+/**
+ * Subagent memory is part of auto memory, so turning auto memory off turns this
+ * store off with it: the `memory:` field stops having any effect, the agent
+ * launches with no memory instructions and no file tools, and the directory can
+ * neither be read nor grow. Nothing about the files themselves shows that.
+ */
+export function checkAgentMemoryInert(store) {
+  if (!store || !store.linkage || !store.inert) return [];
+
+  return [{
+    kind: 'agent-memory-inert',
+    severity: 'warn',
+    agentName: store.agentName,
+    setBy: store.inertBy || null,
+  }];
+}
+
+export function agentStoreChecks(store) {
+  return [
+    ...checkAgentMemoryInert(store),
+    ...checkAgentStoreOrphan(store),
+    ...checkAgentStoreScopeMismatch(store),
+  ];
+}
+
 export function sessionChecks(store, memories, retention, { remembered = false, resolveOrigin = null } = {}) {
   if (!retention) return [];
   return [