@cldmv/gh-broker 0.10.0 → 0.10.2

package/README.md

@@ -19,19 +19,18 @@ It runs as a dedicated `gh-broker` system user, holds a read-scoped and a write-
 
 ## ✨ What's New
 
-### Latest: v0.10.0 (November 2026)
+### Latest: v0.10.2 (November 2026)
 
-- **OTP gate for risky write tools.** Gated tools need a current code from an authenticator app, so the agent has to ask you. The first good code opens a five-minute window for that agent, and bad codes lock it out, then hard-lock it until `sudo gh-broker otp unlock <user>`.
-- **One socket per agent and the `gh-broker` command.** Each agent user gets its own socket, and `gh-broker agent add|remove|list|sync` writes its MCP config. `gh-broker otp status|list|unlock|rotate` manages the gate, and `gh-broker install` runs the installer.
-- **Eleven new write tools and a deny list.** These include merging, branch updates, repo create and fork, `delete_branch`, `dismiss_alert` and `minimize_comment`, with the risky ones gated by default and the Copilot coding-agent tools disabled. A built-in deny list refuses file writes, repo deletion and repo settings at config load. Breaking: the socket path, the `bin` and `npm_scaffold`'s `npm_otp`; see the upgrade notes.
-- [View full v0.10.0 Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.10.0.md)
+- **The MCP entry reaches every Claude config folder an agent uses.** Sessions started with `CLAUDE_CONFIG_DIR` (like `~/.claude-secondary`) were left on the removed shared socket. `install` and `agent sync` now update every `~/.claude*` folder in the agent's home, the folder of each running session, and folders saved with `--claude-config`.
+- **Smaller package.** The 1.4 MB source map no longer ships, and the bundle is built minified with tsup, taking the package from 3.2 MB to about 780 kB unpacked. The Node.js floor is back to 22.0.0.
+- [View full v0.10.2 Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.10.2.md)
 
 ### Recent Releases
 
+- **v0.10.1** (November 2026) — the OTP gate says why it refused a code, and `report_dependents` lists dev branches on large orgs without a 502 ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.10.1.md))
+- **v0.10.0** (November 2026) — OTP gate for risky write tools, one socket per agent with the `gh-broker` command, eleven new write tools and a built-in deny list ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.10.0.md))
 - **v0.9.0** (November 2026) — `report_alert_status`, `report_release_changes` and `report_dependents` for the release and fleet skills, `ciVerbosity` on `list_pull_requests`, and install from npm ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.9.0.md))
 - **v0.8.0** (November 2026) — `npm_scaffold` creates an npm package and its trusted publisher, `ghcr_push` pushes images without an agent-held token, and optional credentials hide their tools ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.8.0.md))
-- **v0.7.0** (October 2026) — `issue_labels` adds, removes or swaps single labels without replacing the set, and `issue_write` warns that its `labels` does ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.7.0.md))
-- **v0.6.1** (October 2026) — MCP SDK 1.32.0 (same-origin redirects only) and a refreshed vitest toolchain; no broker source changes ([Changelog](https://github.com/CLDMV/gh-broker/blob/master/docs/changelog/v0/v0.6.1.md))
 
 📚 For the complete version history, see the [docs/changelog/](https://github.com/CLDMV/gh-broker/tree/master/docs/changelog/) folder.
 
@@ -144,7 +143,7 @@ The broker presents its **own** MCP contract to the agent — a proxied tool's s
 ### Requirements
 
 - **Linux with systemd.** The broker runs as a hardened systemd service and listens on a Unix socket.
-- **Node.js 22.12.0 or later** (`engines.node` is `>=22.12.0`). The installer points `/usr/local/bin/node` at the node it runs under.
+- **Node.js 22.0.0 or later** (`engines.node` is `>=22.0.0`; development needs 22.22.0+). The installer points `/usr/local/bin/node` at the node it runs under.
 - **The agent runs as its own Linux user**, without passwordless sudo, so it can't read the broker's secrets. The model behind that is in [docs/agent-user-model.md](docs/agent-user-model.md).
 - **Two fine-grained PATs per org** (read and write). The scopes are listed in [deploy/README.md](deploy/README.md).
 

package/deploy/README.md

@@ -148,7 +148,17 @@ sudo gh-broker agent sync [<user>]   # re-apply the MCP config for one agent or
 }
 ```
 
-If an existing entry already mentions `/run/gh-broker/` (the old shared socket or the new one) that entry is updated in place and keeps its name; otherwise the entry is added as `github`, or `gh-broker` when that name is taken. Nothing else in the file changes. The file is parsed, edited, written to a temp file in the same directory and renamed, keeping its owner and mode, and `~/.claude.json.gh-broker.bak` keeps the previous copy (overwritten each time). A missing file is created `0600`; a file that doesn't parse is left alone and the entry is printed to add by hand. The home directory belongs to the agent user and the command runs as root, so it reads the file without following a symlink and only touches a plain file the user owns with a single link; anything else (a symlink, a hard link, someone else's file) is left alone with a warning, and the temp file is created with a random name that can't be pre-planted. Running Claude sessions for that user must be restarted to pick the change up, and `agent sync <user>` puts the entry back if a running session overwrote the file. `--no-mcp-config` (on `install`, `agent add` and `agent sync`) skips the write and prints the entry.
+If an existing entry already mentions `/run/gh-broker/` (the old shared socket or the new one) that entry is updated in place and keeps its name; otherwise the entry is added as `github`, or `gh-broker` when that name is taken. Nothing else in the file changes. The file is parsed, edited, written to a temp file in the same directory and renamed, keeping its owner and mode, and `~/.claude.json.gh-broker.bak` keeps the previous copy (overwritten each time). A missing file is created `0600`; a file that doesn't parse is left alone and the entry is printed to add by hand. The home directory belongs to the agent user and the command runs as root, so it reads the file without following a symlink and only touches a plain file the user owns with a single link; anything else (a symlink, a hard link, someone else's file) is left alone with a warning, and the temp file is created with a random name that can't be pre-planted. Running Claude sessions for that user must be restarted to pick the change up, and `agent sync <user>` puts the entry back if a running session overwrote the file.
+
+**Other Claude config folders.** A Claude session started with `CLAUDE_CONFIG_DIR` reads `$CLAUDE_CONFIG_DIR/.claude.json` and ignores `~/.claude.json`, so the entry also goes into the `.claude.json` of the agent's other Claude config folders. Only registered agents' folders are looked at:
+
+- each `~/.claude*` directory in the agent's home;
+- the `CLAUDE_CONFIG_DIR` of each `claude` process the agent is running, as long as it resolves inside the agent's home;
+- folders saved for the agent with `--claude-config` (`sudo gh-broker agent add|sync <user> --claude-config <dir>`, or `sudo gh-broker install --claude-config <user>:<dir>`). They're kept in `claudeConfigDirs` in the broker config, so every later sync updates them. This is how a folder outside the home directory is added.
+
+In these folders the file is only updated when it already exists (Claude Code creates it on first run). The folder must be a real directory the agent owns, not a symlink; anything else is skipped with a warning and doesn't fail the run. The folder is opened once and the file is edited through that open folder, so it can't be swapped mid-way. A session folder outside the home directory is skipped, because owning a folder doesn't mean the agent can reach it; save it with `--claude-config` if it's meant to be used. `agent remove` cleans the entry out of every folder it finds, and forgets the saved ones. A session folder that isn't running at that moment and isn't saved keeps its entry, which then points at a closed socket.
+
+`--no-mcp-config` (on `install`, `agent add` and `agent sync`) skips the write and prints the entry.
 
 **Upgrading from the shared socket.** The first `gh-broker install` after the change registers every member of `gh-broker-clients` (other than `gh-broker`) as an agent, writes the new `listen` (`agents:/run/gh-broker/agents`), rewrites each agent's MCP config to its own socket and smoke-tests every socket. `gh-broker-clients` is left in place; nothing depends on it any more. Agents added later need a service restart, which `agent add` does.
 

package/deploy/install.mjs

@@ -88,7 +88,11 @@ Flags:
                           Each agent gets its own socket and MCP config. Optional on an
                           upgrade (registered agents are kept); a first install with none
                           asks (never $SUDO_USER)
-  --no-mcp-config         do not write any agent's ~/.claude.json; print the entry instead
+  --no-mcp-config         do not write any agent's Claude MCP config; print the entry instead
+  --claude-config <user>:<dir>
+                          another Claude config folder (CLAUDE_CONFIG_DIR) that agent uses,
+                          kept in the config so every sync updates it (repeatable). Folders
+                          in the agent's home are found without it
   --secrets-provider <p>  systemd-creds | file   (skips the prompt)
   --secrets-file <path>   JSON { "<cred-name>": "<token>" } to import tokens from
   --secret <name>=<tok>   one token on the command line (repeatable). Visible in

package/deploy/lib/agent-cli.mjs

@@ -16,26 +16,108 @@
 /**
  * `gh-broker agent add | remove | list | sync` (#143, contract v2). An agent is a Linux group
  * `gh-broker-agent-<u>` (the registry), one socket per agent in the daemon's agents directory,
- * and an entry in the agent user's Claude Code MCP config. Every effect is injected.
+ * and an entry in the agent user's Claude Code MCP config: `~/.claude.json`, plus the
+ * `.claude.json` in each other Claude config folder the user has (#163). Every effect is injected.
  */
 import { agentGroup, agentsDir, assertAgentName, registeredAgents, socketPath, versionWarning } from "./agents.mjs";
-import { applyMcpConfig, mcpEntry, mcpFileStatus, removeMcpConfig, MCP_BACKUP, MCP_FILE } from "./mcp-config.mjs";
+import { applyMcpConfig, mcpEntry, mcpFileStatus, removeMcpConfig, SkippedFolder, MCP_BACKUP, MCP_FILE } from "./mcp-config.mjs";
 import { statePathOf } from "./otp-cli.mjs";
+import { absoluteFolders, addClaudeConfigDirs } from "./config-merge.mjs";
 import { spendRecentCodes, withoutUser } from "./otp.mjs";
 
 /** Run one `agent` subcommand. Returns the exit code; throws on a failure the dispatcher reports. */
 export async function agentCommand(command, rest, config, d) {
-	const flags = rest.filter((a) => a.startsWith("-"));
-	const names = rest.filter((a) => !a.startsWith("-"));
-	const noMcp = flags.includes("--no-mcp-config");
+	const { names, noMcp, claudeConfigs } = parseAgentArgs(rest);
+	if (claudeConfigs.length && !["add", "sync"].includes(command)) throw new Error("--claude-config only goes with agent add or agent sync");
 	if (command === "list") return list(config, d);
-	if (command === "sync") return sync(config, names[0], noMcp, d);
+	if (command === "sync") {
+		if (claudeConfigs.length && names.length !== 1) throw new Error("--claude-config needs the agent named: sudo gh-broker agent sync <user> --claude-config <dir>");
+		if (claudeConfigs.length) {
+			assertAgentName(names[0]);
+			if (!registry(d).some((a) => a.user === names[0])) throw new Error(`"${names[0]}" is not a registered agent`);
+			config = rememberFolders(config, names[0], claudeConfigs, d);
+		}
+		return sync(config, names[0], noMcp, d);
+	}
 	if (names.length !== 1) throw new Error(`name the agent user: sudo gh-broker agent ${command} <user>`);
-	return command === "add" ? add(config, names[0], noMcp, d) : remove(config, names[0], d);
+	if (command === "add") {
+		assertAgentName(names[0]);
+		if (!d.userInfo(names[0])) throw new Error(`user "${names[0]}" does not exist; create it first (the installer can: sudo gh-broker install --agent-user ${names[0]} --create-agent-user)`);
+		if (claudeConfigs.length) config = rememberFolders(config, names[0], claudeConfigs, d);
+		return add(config, names[0], noMcp, d);
+	}
+	return remove(config, names[0], d);
+}
+
+/** Split `agent` arguments into names and flags; `--claude-config <dir>` (or `=<dir>`) is repeatable. */
+function parseAgentArgs(rest) {
+	const names = [];
+	const claudeConfigs = [];
+	let noMcp = false;
+	for (let i = 0; i < rest.length; i++) {
+		const a = rest[i];
+		if (a === "--no-mcp-config") noMcp = true;
+		else if (a === "--claude-config" || a.startsWith("--claude-config=")) {
+			const dir = a === "--claude-config" ? rest[++i] : a.slice("--claude-config=".length);
+			if (!dir?.startsWith("/")) throw new Error("--claude-config takes an absolute folder: --claude-config /path/to/claude-config");
+			claudeConfigs.push(dir.replace(/(.)\/+$/, "$1"));
+		} else if (a.startsWith("-")) throw new Error(`unknown flag: ${a}`);
+		else names.push(a);
+	}
+	return { names, noMcp, claudeConfigs };
+}
+
+/** Add `dirs` to `user`'s saved Claude config folders and write the broker config. Returns the new config. */
+function rememberFolders(config, user, dirs, d) {
+	const next = { ...config, claudeConfigDirs: addClaudeConfigDirs(config.claudeConfigDirs, { [user]: dirs }) };
+	d.writeConfig(next);
+	d.log(`${user}: Claude config folders kept in the broker config: ${next.claudeConfigDirs[user].join(", ")}`);
+	return next;
 }
 
 const registry = (d) => registeredAgents(d.groups());
 
+/**
+ * The agent's Claude config folders other than the home directory (#163): the ones saved for it
+ * with --claude-config, its `~/.claude*` folders, and the `CLAUDE_CONFIG_DIR` of its running
+ * `claude` sessions. Only these users' own folders are looked at, never anyone else's. Saved
+ * folders were named by root, so they may be outside the home directory; found ones may not.
+ * @returns {Array<{ folder: string, saved: boolean }>}
+ */
+function extraFolders(info, d, config, user) {
+	const home = info.home.replace(/\/+$/, "");
+	const saved = absoluteFolders(config.claudeConfigDirs?.[user]);
+	const found = [...(d.mcpIO.scan?.(info.home) ?? []), ...(d.mcpIO.sessions?.(info.uid) ?? [])];
+	const seen = new Set([home, info.home]);
+	const out = [];
+	for (const [list, isSaved] of [[saved, true], [found, false]]) {
+		for (const folder of list) {
+			if (seen.has(folder)) continue;
+			seen.add(folder);
+			out.push({ folder, saved: isSaved });
+		}
+	}
+	return out;
+}
+
+/**
+ * Run `fn(io)` for the files in `folder`. The home directory uses the io as is; any other folder is
+ * pinned first (it must be a real directory the agent owns, and unless it was saved with
+ * --claude-config, inside the agent's home). Returns undefined when the folder is gone.
+ */
+function inFolder({ folder, saved }, info, d, fn) {
+	if (folder === info.home || !d.mcpIO.pin) return fn(d.mcpIO);
+	const pinned = d.mcpIO.pin(folder, info.uid, saved ? undefined : info.home);
+	if (!pinned) return undefined;
+	try {
+		return fn(pinned.io);
+	} finally {
+		pinned.close();
+	}
+}
+
+const BAD = ["failed", "unsafe", "unreadable"];
+
 /**
  * Write (or, with `noMcp`, just print) one agent's MCP config and explain the restart. Shared with
  * the installer. Returns the lines it logged through `d.log`.
@@ -49,16 +131,41 @@ export function configureMcp(user, config, d, { noMcp = false } = {}) {
 		d.log(JSON.stringify({ github: entry }, null, "\t"));
 		return "skipped";
 	}
+	const home = configureFolder(user, { folder: info.home, saved: false }, info, dir, entry, d);
+	let worst = home;
+	for (const place of extraFolders(info, d, config, user)) {
+		const r = configureFolder(user, place, info, dir, entry, d);
+		if (BAD.includes(r) && !BAD.includes(worst)) worst = r;
+	}
+	d.log(`${user}: restart the user's running Claude sessions to pick it up. If a running session overwrites the file, "sudo gh-broker agent sync ${user}" puts it back.`);
+	return worst;
+}
+
+/**
+ * Write the entry in one folder's `.claude.json` and log the outcome. The home directory's file is
+ * created when missing; another folder is only updated when it already has one, since Claude
+ * Code writes that file itself in any folder it uses.
+ */
+function configureFolder(user, place, info, dir, entry, d) {
+	const { folder } = place;
+	const isHome = folder === info.home;
+	const file = isHome ? "the user's ~/.claude.json" : `${folder}/${MCP_FILE}`;
+	const where = isHome ? "" : ` in ${folder}/${MCP_FILE}`;
 	let r;
 	try {
-		r = applyMcpConfig({ home: info.home, user, dir, owner: { uid: info.uid, gid: info.gid } }, d.mcpIO);
+		r = inFolder(place, info, d, (io) => applyMcpConfig({ folder, user, dir, owner: { uid: info.uid, gid: info.gid }, create: isHome }, io)) ?? { status: "no-file" };
 	} catch (err) {
-		// The home directory is the agent's, so a write there can fail on anything it puts in the
-		// way (a directory where the backup goes, say). Report it; it must not stop the caller.
-		d.error(`${user}: could not write the MCP config: ${err.message}. Add this under "mcpServers" in the user's ~/.claude.json by hand:`);
+		if (err instanceof SkippedFolder) {
+			d.error(`${user}: skipped ${err.message}`);
+			return "skipped";
+		}
+		// Root is working in a folder the agent owns, so a write can fail on anything the agent puts
+		// in the way (a directory where the backup goes). Report it; it must not stop the caller.
+		d.error(`${user}: could not write the MCP config${where}: ${err.message}. Add this under "mcpServers" in ${file} by hand:`);
 		d.log(JSON.stringify({ github: entry }, null, "\t"));
 		return "failed";
 	}
+	if (r.status === "no-file") return "no-file";
 	if (r.status === "unsafe") {
 		d.error(`${user}: ${r.reason}, so it was left alone (root won't read or replace it). Make it a plain file the user owns and run "sudo gh-broker agent sync ${user}", or add this under "mcpServers" by hand:`);
 		d.log(JSON.stringify({ github: entry }, null, "\t"));
@@ -70,7 +177,6 @@ export function configureMcp(user, config, d, { noMcp = false } = {}) {
 		return "unreadable";
 	}
 	d.log(`${user}: MCP config ${r.status === "unchanged" ? "already up to date" : r.status} in ${r.path} (entry "${r.key}")${r.status === "written" ? `; previous file saved as ${MCP_BACKUP}` : ""}`);
-	d.log(`${user}: restart the user's running Claude sessions to pick it up. If a running session overwrites the file, "sudo gh-broker agent sync ${user}" puts it back.`);
 	return r.status;
 }
 
@@ -87,9 +193,8 @@ export async function smokeAgent(user, config, d) {
 	}
 }
 
+/** `user` is a valid name and an existing user (agentCommand checks both before it saves anything). */
 async function add(config, user, noMcp, d) {
-	assertAgentName(user);
-	if (!d.userInfo(user)) throw new Error(`user "${user}" does not exist; create it first (the installer can: sudo gh-broker install --agent-user ${user} --create-agent-user)`);
 	d.ensureGroup(user);
 	d.log(`${user}: registered (group ${agentGroup(user)})`);
 	configureMcp(user, config, d, { noMcp });
@@ -108,12 +213,31 @@ function remove(config, user, d) {
 	d.log("service restarted");
 	const info = d.userInfo(user);
 	if (info) {
+		const dir = agentsDir(config.listen);
+		for (const place of [{ folder: info.home, saved: false }, ...extraFolders(info, d, config, user)]) {
+			const { folder } = place;
+			const isHome = folder === info.home;
+			try {
+				const r = inFolder(place, info, d, (io) => removeMcpConfig({ folder, dir, uid: info.uid }, io));
+				if (!r || (!isHome && r.status === "no-file")) continue;
+				const what = { removed: `removed the broker entry from ${r.path} (backup: ${MCP_BACKUP})`, absent: `no broker entry in ${r.path}`, "no-file": `no ${MCP_FILE} to edit`, unreadable: `${r.path} is not valid JSON, so it was left alone`, unsafe: `${r.reason}, so it was left alone` };
+				d.log(`${user}: ${what[r.status]}`);
+			} catch (err) {
+				if (err instanceof SkippedFolder) {
+					d.error(`${user}: skipped ${err.message}`);
+					continue;
+				}
+				d.error(`${user}: could not remove the broker entry from ${folder}/${MCP_FILE}: ${err.message}. The agent is unregistered anyway; remove the entry by hand.`);
+			}
+		}
+	}
+	if (config.claudeConfigDirs?.[user]) {
 		try {
-			const r = removeMcpConfig({ home: info.home, dir: agentsDir(config.listen), uid: info.uid }, d.mcpIO);
-			const what = { removed: `removed the broker entry from ${r.path} (backup: ${MCP_BACKUP})`, absent: `no broker entry in ${r.path}`, "no-file": `no ${MCP_FILE} to edit`, unreadable: `${r.path} is not valid JSON, so it was left alone`, unsafe: `${r.reason}, so it was left alone` };
-			d.log(`${user}: ${what[r.status]}`);
+			const { [user]: _gone, ...rest } = config.claudeConfigDirs;
+			d.writeConfig({ ...config, claudeConfigDirs: rest });
+			d.log(`${user}: saved Claude config folders removed from the broker config`);
 		} catch (err) {
-			d.error(`${user}: could not remove the broker entry from ${info.home}/${MCP_FILE}: ${err.message}. The agent is unregistered anyway; remove the entry by hand.`);
+			d.error(`${user}: could not update the broker config: ${err.message}. Remove claudeConfigDirs.${user} from it by hand.`);
 		}
 	}
 	try {
@@ -142,10 +266,22 @@ function list(config, d) {
 		let mcp = "no such user";
 		if (info) {
 			try {
-				mcp = mcpFileStatus({ home: info.home, user: a.user, dir, uid: info.uid }, d.mcpIO);
+				mcp = mcpFileStatus({ folder: info.home, user: a.user, dir, uid: info.uid }, d.mcpIO);
 			} catch (err) {
 				mcp = `can't read (${err.message})`; // one agent's file must not hide the others
 			}
+			const others = [];
+			for (const place of extraFolders(info, d, config, a.user)) {
+				const { folder } = place;
+				let status;
+				try {
+					status = inFolder(place, info, d, (io) => mcpFileStatus({ folder, user: a.user, dir, uid: info.uid, ifAbsent: null }, io));
+				} catch (err) {
+					status = err instanceof SkippedFolder ? `skipped (${err.message})` : `can't read (${err.message})`;
+				}
+				if (status) others.push(`${folder}: ${status}`);
+			}
+			if (others.length) mcp += ` (${others.join(", ")})`;
 		}
 		d.log(`${a.user}  ${sock}  socket: ${d.socketExists(sock) ? "yes" : "no"}  mcp: ${mcp}${a.complete ? "" : "  (group members incomplete; run agent add)"}`);
 	}
@@ -161,6 +297,6 @@ function sync(config, only, noMcp, d) {
 		if (!agents.includes(only)) throw new Error(`"${only}" is not a registered agent`);
 	}
 	let ok = true;
-	for (const user of only ? [only] : agents) if (["failed", "unsafe", "unreadable"].includes(configureMcp(user, config, d, { noMcp }))) ok = false;
+	for (const user of only ? [only] : agents) if (BAD.includes(configureMcp(user, config, d, { noMcp }))) ok = false;
 	return ok ? 0 : 1;
 }

package/deploy/lib/cli.mjs

@@ -26,6 +26,7 @@ export const USAGE = `Usage: sudo gh-broker <command>
 Commands:
   install [flags]            install or upgrade the broker (see: gh-broker install --help)
   agent add <user>           register an agent user: group, MCP config, restart, smoke test (--no-mcp-config to skip the config)
+                             --claude-config <dir>: another Claude config folder it uses outside its home (repeatable, also on sync)
   agent remove <user>        unregister an agent: empty its group, restart, MCP entry, lock state
   agent list                 each agent, its socket, and whether its MCP config points at it
   agent sync [<user>]        re-apply the MCP config for one agent or all

package/deploy/lib/config-merge.mjs

@@ -28,7 +28,8 @@
  *     exception is each deployed tool's boolean `otp` and `enabled`, which carry onto the same
  *     tool in the new list (they never add a tool).
  *   - Everything else is operator data and the deployed copy wins over the example: `listen`,
- *     `upstream`, `defaultOwner`, `owners`, `ghcr`, `app`, `secrets`, `npm`, `otp`. The example ships
+ *     `upstream`, `defaultOwner`, `owners`, `ghcr`, `app`, `secrets`, `npm`, `otp`,
+ *     `claudeConfigDirs` (each agent's extra Claude config folders, #163; layers add to it). The example ships
  *     none of the owner-specific ones, so a fresh install has no owners until the operator
  *     supplies one (--owner, --config, or the interactive prompt).
  *   - Layers 3 and 4 are merged on top of what is deployed rather than replacing it: scalars are
@@ -39,11 +40,11 @@
  * The result is validated by the real loader (`--check`) before anything is deployed, and a
  * --config file may hold only `cred:` references, never token values.
  */
-import { DEFAULT_LISTEN } from "./agents.mjs";
+import { assertAgentName, DEFAULT_LISTEN } from "./agents.mjs";
 
 export const DEFAULT_GHCR_DROP_DIR = "/srv/gh-broker/ghcr-drop";
 
-const OPERATOR_KEYS = ["listen", "upstream", "defaultOwner", "owners", "app", "secrets", "npm", "ghcr", "otp"];
+const OPERATOR_KEYS = ["listen", "upstream", "defaultOwner", "owners", "app", "secrets", "npm", "ghcr", "otp", "claudeConfigDirs"];
 const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 /** Shapes of live GitHub / npm tokens (classic, fine-grained, app, npm granular). */
 const TOKEN_SHAPE = /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|npm_[A-Za-z0-9]{30,})\b/;
@@ -75,7 +76,7 @@ export function mergeConfig(example, current) {
 	out.owners = { ...(example.owners ?? {}), ...(current.owners ?? {}) };
 
 	// optional blocks: current wins if present.
-	for (const k of ["app", "secrets", "npm", "ghcr"]) {
+	for (const k of ["app", "secrets", "npm", "ghcr", "claudeConfigDirs"]) {
 		if (current[k] !== undefined) out[k] = structuredClone(current[k]);
 	}
 
@@ -102,6 +103,7 @@ export function layerConfig(base, overlay) {
 		out.owners = { ...(out.owners ?? {}) };
 		for (const [name, creds] of Object.entries(overlay.owners)) out.owners[name] = { ...(out.owners[name] ?? {}), ...creds };
 	}
+	if (overlay.claudeConfigDirs !== undefined) out.claudeConfigDirs = addClaudeConfigDirs(out.claudeConfigDirs, overlay.claudeConfigDirs);
 	if (overlay.ghcr !== undefined) {
 		const { owners: ghcrOwners, ...scalars } = overlay.ghcr;
 		const merged = { ...(out.ghcr ?? {}), ...structuredClone(scalars) };
@@ -114,6 +116,34 @@ export function layerConfig(base, overlay) {
 	return out;
 }
 
+/**
+ * `claudeConfigDirs` with `more` added: per agent, the folders of both, each once. The result is
+ * a new object; neither argument is changed.
+ */
+export function addClaudeConfigDirs(base, more) {
+	const out = structuredClone(isObject(base) ? base : {});
+	for (const [user, dirs] of Object.entries(more)) out[user] = [...new Set([...absoluteFolders(out[user]), ...absoluteFolders(dirs)])];
+	return out;
+}
+
+/**
+ * The absolute folder paths in one agent's saved list. The deployed config can be hand-edited, so
+ * a string instead of a list, or a relative entry, yields nothing rather than odd folders.
+ */
+export function absoluteFolders(dirs) {
+	return Array.isArray(dirs) ? dirs.filter((d) => typeof d === "string" && d.startsWith("/")) : [];
+}
+
+/** Throw unless `v` is { "<agent user>": ["/absolute/dir", ...] }. `where` names it in the message. */
+export function checkClaudeConfigDirs(v, where) {
+	if (!isObject(v)) throw new Error(`${where} must be an object of agent user -> list of folders`);
+	for (const [user, dirs] of Object.entries(v)) {
+		assertAgentName(user);
+		if (!Array.isArray(dirs) || !dirs.every((d) => typeof d === "string" && d.startsWith("/"))) throw new Error(`${where}.${user} must be a list of absolute paths`);
+	}
+	return v;
+}
+
 /** The config fragment the CLI flags describe (same shape as a config file), or {} when none were given. */
 export function overlayFromFlags(opts) {
 	const o = {};
@@ -132,6 +162,7 @@ export function overlayFromFlags(opts) {
 		g.owners = { [opts.ghcrOwner]: { username: opts.ghcrUsername, credential: `cred:${opts.ghcrOwner}-packages`, images: [...opts.ghcrImages] } };
 	}
 	if (Object.keys(g).length) o.ghcr = g;
+	for (const { user, dir } of opts.claudeConfigs ?? []) ((o.claudeConfigDirs ??= {})[user] ??= []).push(dir);
 	return o;
 }
 
@@ -151,6 +182,7 @@ export function readOperatorConfig(path, read) {
 	if (raw.tools !== undefined) throw new Error("--config: `tools` is the shipped allowlist and cannot be set from a config file");
 	const unknown = Object.keys(raw).filter((k) => !OPERATOR_KEYS.includes(k));
 	if (unknown.length) throw new Error(`--config: unknown key(s) ${unknown.join(", ")} (allowed: ${OPERATOR_KEYS.join(", ")})`);
+	if (raw.claudeConfigDirs !== undefined) checkClaudeConfigDirs(raw.claudeConfigDirs, "--config: claudeConfigDirs");
 	const hit = findTokenShape(raw, "");
 	if (hit) throw new Error(`--config: ${hit} looks like a token. The config holds only "cred:<name>" references; pass the token with --secret, --secrets-file or env`);
 	return raw;

package/deploy/lib/install-args.mjs

@@ -20,6 +20,7 @@
  */
 
 import { assertSafeCredName } from "./secret-store.mjs";
+import { assertAgentName } from "./agents.mjs";
 
 export const NPM_SCOPE = /^@[a-z0-9][a-z0-9._~-]*$/;
 export const NPM_ORG = /^[a-z0-9][a-z0-9._~-]*$/;
@@ -125,6 +126,12 @@ export function parseArgs(argv) {
 			const n = value(++i, a);
 			if (!/^[1-9][0-9]{0,15}$/.test(n) || !Number.isSafeInteger(Number(n))) throw new Error("--ghcr-max-archive-bytes must be a positive whole number of bytes");
 			o.ghcrMaxArchiveBytes = Number(n);
+		} else if (a === "--claude-config") {
+			const pair = value(++i, a);
+			const colon = pair.indexOf(":");
+			const dir = pair.slice(colon + 1);
+			if (colon <= 0 || !dir.startsWith("/")) throw new Error(`--claude-config takes <agent user>:<absolute folder>, got "${pair}"`);
+			(o.claudeConfigs ??= []).push({ user: assertAgentName(pair.slice(0, colon)), dir: dir.replace(/(.)\/+$/, "$1") });
 		} else if (a === "--protect-release-tags") o.protectReleaseTags = true;
 		else if (a === "--no-protect-release-tags") o.protectReleaseTags = false;
 		else if (a.startsWith("-")) throw new Error(`unknown flag: ${a} (see --help)`);