@rucher/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florian Varrin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# @rucher/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `rucher` binary: status, journal and sessions of your Claude Code sub-agents, from the terminal. Built on [`@rucher/carnet`](../carnet).
+
+```bash
+rucher init --name shop --repos ~/code/shop-api,~/code/shop-web
+rucher status --watch     # the status pane
+rucher log                # the journal
+rucher sessions           # named sessions
+rucher resume shop-auth   # back into a named session
+rucher serve              # the Carnet MCP server, started by the Claude Code plugin
+```
+
+See the repository [README](../../README.md) for install and the plugin, and `docs/carnet-spec.md` for every command.

package/dist/cli.mjs

@@ -0,0 +1,1027 @@
+#!/usr/bin/env node
+import { defineCommand, runMain } from "citty";
+import { existsSync, readdirSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import tab from "@bomb.sh/tab/citty";
+import { CarnetError, LEGEND, addGroupRepo, claudeCode, formatClock, handleSessionStart, handleUserPromptSubmit, hostById, initGroup, isGroupRoot, locateGroup, openCarnet, readRegistry, removeGroupRepo, renderSections, repoPathFor, shortId, unregisterGroups } from "@rucher/carnet";
+import { styleText } from "node:util";
+import { spawnSync } from "node:child_process";
+import { serveCarnet } from "@rucher/carnet/mcp";
+// src/completion.ts
+const hiddenCommands = /* @__PURE__ */ new Set(["hook", "serve"]);
+function quietly(suggest) {
+	try {
+		suggest();
+	} catch {}
+}
+function suggestSessions(context, complete) {
+	quietly(() => {
+		const carnet = openCarnet(context);
+		try {
+			const sessions = carnet.sessions.list({ includeTemporary: true });
+			const suggestions = [...sessions.flatMap((session) => session.name ? [{
+				value: session.name,
+				description: session.purpose ?? session.status
+			}] : []), ...sessions.flatMap((session) => session.name ? [] : [{
+				value: shortId(session.id),
+				description: session.status
+			}])];
+			for (const suggestion of suggestions) if (!context.typedWords.slice(0, -1).includes(suggestion.value)) complete(suggestion.value, suggestion.description);
+		} finally {
+			carnet.close();
+		}
+	});
+}
+function suggestGroups(context, complete) {
+	quietly(() => {
+		const groups = readRegistry(context.env);
+		for (const group of groups) complete(groups.filter((other) => other.name === group.name).length > 1 ? group.path : group.name, group.path);
+	});
+}
+function suggestRepos(context, complete) {
+	quietly(() => {
+		for (const repo of locateGroup(context).repos) complete(repo, "");
+	});
+}
+function suggestDirectories(context, complete) {
+	quietly(() => {
+		const partial = context.typedWords.at(-1) ?? "";
+		const base = partial.endsWith("/") ? partial : dirname(partial) === "." ? "" : `${dirname(partial)}/`;
+		for (const entry of readdirSync(resolve(context.cwd, base || "."), { withFileTypes: true })) if (entry.isDirectory() && !entry.name.startsWith(".")) complete(join(base, entry.name), "");
+	});
+}
+function processContext() {
+	const separator = process.argv.indexOf("--");
+	const typedWords = separator === -1 ? [] : process.argv.slice(separator + 1);
+	return {
+		cwd: process.cwd(),
+		env: process.env,
+		typedWords
+	};
+}
+const sessions = (complete) => suggestSessions(processContext(), complete);
+const groups = (complete) => suggestGroups(processContext(), complete);
+const repos = (complete) => suggestRepos(processContext(), complete);
+const directories = (complete) => suggestDirectories(processContext(), complete);
+const completionConfig = { subCommands: {
+	status: { options: { session: sessions } },
+	log: { options: { session: sessions } },
+	init: { args: { directory: directories } },
+	resume: { args: { name: sessions } },
+	sessions: { subCommands: { merge: { args: {
+		from: sessions,
+		into: sessions
+	} } } },
+	groups: { subCommands: { forget: { args: { reference: groups } } } },
+	group: { subCommands: {
+		add: { args: { path: directories } },
+		remove: { args: { path: repos } }
+	} }
+} };
+async function setupCompletion(main) {
+	const subCommands = await (typeof main.subCommands === "function" ? main.subCommands() : main.subCommands);
+	const visible = Object.fromEntries(Object.entries(subCommands ?? {}).filter(([name]) => !hiddenCommands.has(name)));
+	await tab({
+		...main,
+		subCommands: visible
+	}, completionConfig);
+	const complete = visible["complete"];
+	if (complete) main.subCommands = {
+		...subCommands,
+		complete
+	};
+}
+// package.json
+var version = "0.1.0";
+// src/color.ts
+function paint(io) {
+	const style = (name) => (text) => io.color ? styleText(name, text, { validateStream: false }) : text;
+	return {
+		bold: style("bold"),
+		dim: style("dim"),
+		yellow: style("yellow"),
+		red: style("red"),
+		cyan: style("cyan")
+	};
+}
+// src/commands/init.ts
+function syncContextFiles(group, mode) {
+	return group.hosts.flatMap((id) => hostById(id).contextFiles.map((file) => ({
+		path: file.path,
+		result: file.sync(group, mode)
+	})));
+}
+function init(options, io) {
+	const colors = paint(io);
+	const root = resolve(io.cwd, options.directory ?? ".");
+	let group;
+	try {
+		group = initGroup(root, {
+			name: options.name,
+			repos: options.repos?.map((repo) => resolve(io.cwd, repo)),
+			env: io.env
+		});
+	} catch (error) {
+		if (error instanceof CarnetError) {
+			io.stderr(`error: ${error.message}\n`);
+			return 1;
+		}
+		throw error;
+	}
+	const lines = [
+		`${colors.bold(group.name)} initialised in ${group.root}`,
+		`  repos: ${group.repos.length ? group.repos.join(", ") : "none yet, add them with `rucher group add <path>`"}`,
+		`  database: ${group.dbPath}`
+	];
+	for (const { path, result } of syncContextFiles(group, "merge")) {
+		if (result === "unchanged") continue;
+		lines.push(result === "no-markers" ? `  kept existing ${path} ${colors.dim("(add the rucher:repos markers to keep its repo list in sync, and a line: multi-agent work uses the rucher tools)")}` : `  ${result} ${path}`);
+	}
+	const hosts = group.hosts.map((id) => hostById(id).displayName).join(" or ");
+	lines.push("", `Next: start ${hosts} in this directory, then \`rucher status --watch\` in a side pane.`);
+	io.stdout(`${lines.join("\n")}\n`);
+	return 0;
+}
+// src/commands/group.ts
+function groupShow(io) {
+	const colors = paint(io);
+	const group = locateGroup({
+		cwd: io.cwd,
+		env: io.env
+	});
+	const repos = group.repos.length ? group.repos.map((r) => `  ${basename(r)}  ${colors.dim(r)}`).join("\n") : `  ${colors.dim("none")}`;
+	io.stdout(`${colors.bold(group.name)}  ${colors.dim(group.root)}\nrepos:\n${repos}\n`);
+	return 0;
+}
+function syncNotes(group, mode) {
+	return syncContextFiles(group, mode).filter(({ result }) => result !== "unchanged").map(({ path, result }) => result === "no-markers" ? `${path} has no rucher:repos markers, update its repo list yourself` : `${result} ${path}`);
+}
+function withNotes(line, notes) {
+	return `${line}${notes.length ? ` (${notes.join(", ")})` : ""}\n`;
+}
+function carnetErrors(io, run) {
+	try {
+		return run();
+	} catch (error) {
+		if (error instanceof CarnetError) {
+			io.stderr(`error: ${error.message}\n`);
+			return 1;
+		}
+		throw error;
+	}
+}
+function groupAdd(repo, io) {
+	const found = locateGroup({
+		cwd: io.cwd,
+		env: io.env
+	});
+	return carnetErrors(io, () => {
+		const path = resolve(io.cwd, repo);
+		const group = addGroupRepo(found.root, path);
+		io.stdout(withNotes(`added ${basename(path)} to ${group.name}`, syncNotes(group, "merge")));
+		return 0;
+	});
+}
+function groupRemove(repo, io) {
+	const found = locateGroup({
+		cwd: io.cwd,
+		env: io.env
+	});
+	return carnetErrors(io, () => {
+		const path = resolve(io.cwd, repo);
+		const group = removeGroupRepo(found.root, path);
+		io.stdout(withNotes(`removed ${basename(path)} from ${group.name}`, syncNotes(group, "exact")));
+		return 0;
+	});
+}
+function groupSync(io) {
+	const group = locateGroup({
+		cwd: io.cwd,
+		env: io.env
+	});
+	const notes = syncNotes(group, "exact");
+	io.stdout(notes.length ? withNotes(`synced ${group.name}`, notes) : `${group.name} already in sync\n`);
+	return 0;
+}
+// src/commands/groups.ts
+function missing(reference) {
+	return !isGroupRoot(reference.path);
+}
+function groupsList(io) {
+	const colors = paint(io);
+	const groups = readRegistry(io.env);
+	if (groups.length === 0) {
+		io.stdout(`${colors.dim("no registered group")}\n`);
+		return 0;
+	}
+	const width = Math.max(...groups.map((group) => group.name.length));
+	const lines = groups.map((group) => `${colors.bold(group.name.padEnd(width))}  ${group.path}${missing(group) ? `  ${colors.yellow("missing")}` : ""}`);
+	io.stdout(`${lines.join("\n")}\n`);
+	return 0;
+}
+function groupsForget(reference, io) {
+	const groups = readRegistry(io.env);
+	const byPath = groups.filter((group) => group.path === resolve(io.cwd, reference));
+	const matches = byPath.length ? byPath : groups.filter((group) => group.name === reference);
+	const [match] = matches;
+	if (!match) {
+		io.stderr(`error: no registered group named or located at "${reference}"\n`);
+		return 1;
+	}
+	if (matches.length > 1) {
+		io.stderr(`error: several groups are named "${reference}", forget one by path:\n${matches.map((group) => `  ${group.path}`).join("\n")}\n`);
+		return 1;
+	}
+	unregisterGroups([match.path], io.env);
+	io.stdout(`forgot ${match.name} (${match.path}); its meta directory is untouched\n`);
+	return 0;
+}
+function groupsPrune(io) {
+	const gone = readRegistry(io.env).filter(missing);
+	if (gone.length === 0) {
+		io.stdout("nothing to prune\n");
+		return 0;
+	}
+	unregisterGroups(gone.map((group) => group.path), io.env);
+	io.stdout(`pruned ${gone.length}:\n${gone.map((g) => `  ${g.name}  ${g.path}`).join("\n")}\n`);
+	return 0;
+}
+// src/commands/hook.ts
+const host = claudeCode;
+function runHook(io, run) {
+	try {
+		run();
+	} catch (error) {
+		if (error instanceof CarnetError && error.code === "NO_GROUP") return 0;
+		io.stderr(`rucher hook: ${error instanceof Error ? error.message : String(error)}\n`);
+	}
+	return 0;
+}
+function withCarnet(cwd, io, use) {
+	const carnet = openCarnet({
+		cwd: cwd ?? io.cwd,
+		env: io.env
+	});
+	try {
+		use(carnet);
+	} finally {
+		carnet.close();
+	}
+}
+function sessionStart(stdinText, io) {
+	return runHook(io, () => {
+		const payload = host.parseSessionPayload(stdinText);
+		withCarnet(payload.cwd, io, (carnet) => {
+			const { additionalContext } = handleSessionStart(carnet, payload, {
+				host: host.id,
+				processId: host.processId(io.env),
+				RUCHER_PURGE_DAYS: io.env.RUCHER_PURGE_DAYS
+			});
+			if (additionalContext) {
+				const hookSpecificOutput = {
+					hookEventName: "SessionStart",
+					additionalContext
+				};
+				io.stdout(`${JSON.stringify({ hookSpecificOutput })}\n`);
+			}
+		});
+	});
+}
+function subagentHook(action, stdinText, io) {
+	return runHook(io, () => {
+		const payload = host.parseSubagentPayload(stdinText);
+		withCarnet(payload.cwd, io, (carnet) => {
+			carnet.agents[action](payload.session_id, payload.agent_id);
+		});
+	});
+}
+function subagentStart(stdinText, io) {
+	return subagentHook("pairSubagent", stdinText, io);
+}
+function subagentStop(stdinText, io) {
+	return subagentHook("stopSubagent", stdinText, io);
+}
+function userPromptSubmit(stdinText, io) {
+	return runHook(io, () => {
+		const payload = host.parsePromptPayload(stdinText);
+		withCarnet(payload.cwd, io, (carnet) => {
+			handleUserPromptSubmit(carnet, host, payload);
+		});
+	});
+}
+// src/session.ts
+var CliError = class extends Error {
+	hint;
+	constructor(message, hint) {
+		super(message);
+		this.hint = hint;
+		this.name = "CliError";
+	}
+};
+function findSession(carnet, reference) {
+	try {
+		return carnet.sessions.find(reference);
+	} catch (error) {
+		if (!(error instanceof CarnetError) || error.code !== "SESSION_NOT_FOUND") throw error;
+		const known = carnet.sessions.list().map((session) => session.name).filter(Boolean);
+		throw new CliError(error.message, known.length ? `known sessions: ${known.join(", ")}` : "pass a session name, id or id prefix, see rucher sessions --all");
+	}
+}
+function resolveSession(carnet, reference) {
+	if (reference) return findSession(carnet, reference);
+	const session = carnet.sessions.default();
+	if (!session) throw new CliError("No session in this group yet", "start a Claude Code session inside the group");
+	return session;
+}
+// src/commands/log.ts
+function formatEvents(events, io) {
+	const colors = paint(io);
+	if (events.length === 0) return colors.dim("no events yet");
+	return events.map((event) => {
+		return [
+			colors.dim(formatClock(new Date(event.at))),
+			colors.bold(event.type.padEnd(9)),
+			event.agent ?? "",
+			event.link ?? event.note ?? "",
+			event.commit ? colors.cyan(event.commit.slice(0, 7)) : ""
+		].filter(Boolean).join("  ");
+	}).join("\n");
+}
+function formatDay(date) {
+	const month = String(date.getMonth() + 1).padStart(2, "0");
+	const day = String(date.getDate()).padStart(2, "0");
+	return `${date.getFullYear()}-${month}-${day}`;
+}
+function markdownEvent(event) {
+	const parts = [`${formatClock(new Date(event.at))} **${event.type}**`];
+	if (event.agent) parts.push(`\`${event.agent}\``);
+	const detail = [
+		event.note,
+		event.link ? `[report](${event.link})` : null,
+		event.commit ? `\`${event.commit.slice(0, 7)}\`` : null
+	].filter(Boolean).join(" · ");
+	return `- ${parts.join(" ")}${detail ? `: ${detail}` : ""}`;
+}
+function formatEventsMarkdown(events, title) {
+	const lines = [`# Journal: ${title}`];
+	if (events.length === 0) return `${lines[0]}\n\nNo events yet.`;
+	let day = "";
+	for (const event of events) {
+		const current = formatDay(new Date(event.at));
+		if (current !== day) {
+			day = current;
+			lines.push("", `## ${day}`, "");
+		}
+		lines.push(markdownEvent(event));
+	}
+	return lines.join("\n");
+}
+function sessionTitle(carnet, session) {
+	return `${carnet.group.name} · ${session.name ?? session.id.slice(0, 8)}`;
+}
+function logOnce(carnet, io, options) {
+	const session = resolveSession(carnet, options.session);
+	const events = carnet.events.read(session.id, options.count);
+	io.stdout(`${options.md ? formatEventsMarkdown(events, sessionTitle(carnet, session)) : formatEvents(events, io)}\n`);
+}
+// src/commands/resume.ts
+function resumeTarget(carnet, reference, io) {
+	const session = findSession(carnet, reference);
+	if (session.status === "dropped") io.stderr(`warning: session ${reference} was dropped\n`);
+	const cwd = session.cwd && existsSync(session.cwd) ? session.cwd : io.cwd;
+	return {
+		...hostById(session.host).resumeCommand(session),
+		cwd
+	};
+}
+function runTarget({ command, args, cwd }) {
+	const result = spawnSync(command, args, {
+		cwd,
+		stdio: "inherit"
+	});
+	if (result.error) throw result.error;
+	return result.status ?? 1;
+}
+// src/commands/serve.ts
+function serve(io) {
+	serveCarnet({
+		cwd: io.cwd,
+		env: io.env
+	});
+}
+// src/commands/status.ts
+const SECTION_HEADERS = /* @__PURE__ */ new Set([
+	"On the table",
+	"Waiting on you",
+	"Running"
+]);
+function truncate(line, columns) {
+	const chars = Array.from(line);
+	return chars.length > columns ? `${chars.slice(0, Math.max(columns - 1, 1)).join("")}…` : line;
+}
+function colorizeLine(line, io) {
+	const colors = paint(io);
+	if (line === LEGEND) return colors.dim(line);
+	const cut = truncate(line, io.columns);
+	if (SECTION_HEADERS.has(line)) return colors.bold(cut);
+	if (line.startsWith("  ⚙️")) return colors.yellow(cut);
+	if (line === "  nothing") return colors.dim(cut);
+	return cut;
+}
+function sessionWhere(carnet, session) {
+	return repoPathFor(carnet.group, session.cwd) ?? session.repo;
+}
+function sessionLabel(carnet, session, columns) {
+	const name = session.name ?? session.id.slice(0, 8);
+	const where = sessionWhere(carnet, session);
+	if (!where) return name;
+	const room = columns - Array.from(name).length - 3;
+	return room > 1 ? `${name} · ${truncate(where, room)}` : name;
+}
+function sessionHeader(carnet, session, io) {
+	return paint(io).cyan(sessionLabel(carnet, session, io.columns));
+}
+function sessionLines(carnet, session, view, io) {
+	if (session.status === "dropped") return [paint(io).dim("  dropped, see rucher sessions --all")];
+	return renderSections(view).split("\n").map((line) => colorizeLine(line, io));
+}
+function hasSomethingToShow(carnet, session) {
+	return carnet.agents.list(session.id).length > 0 || carnet.table.get(session.id) !== void 0;
+}
+function sessionBlock(carnet, session, view, io) {
+	return [sessionHeader(carnet, session, io), ...sessionLines(carnet, session, view, io)].join("\n");
+}
+function singleView(carnet, session, io) {
+	const colors = paint(io);
+	const view = carnet.status.view(session);
+	const separator = " - ";
+	const label = sessionLabel(carnet, session, io.columns - view.time.length - 3);
+	return [
+		`${colors.dim(view.time)}${separator}${colors.cyan(label)}`,
+		"",
+		...sessionLines(carnet, session, view, io),
+		"",
+		colors.dim(LEGEND)
+	].join("\n");
+}
+function renderStatusView(carnet, io, options) {
+	const sessions = options.all ? carnet.sessions.list({ includeTemporary: true }).filter((session) => hasSomethingToShow(carnet, session)) : [];
+	if (sessions.length === 0) return singleView(carnet, resolveSession(carnet, options.session), io);
+	let time = "";
+	const blocks = sessions.map((session) => {
+		const view = carnet.status.view(session);
+		time ||= view.time;
+		return sessionBlock(carnet, session, view, io);
+	});
+	return [
+		paint(io).dim(time),
+		"",
+		blocks.join("\n\n"),
+		"",
+		paint(io).dim(LEGEND)
+	].join("\n");
+}
+function statusOnce(carnet, io, options) {
+	io.stdout(`${renderStatusView(carnet, io, options)}\n`);
+}
+const CLEAR = "\x1B[H\x1B[2J";
+const HIDE_CURSOR = "\x1B[?25l";
+const SHOW_CURSOR = "\x1B[?25h";
+function statusWatch(carnet, io, options) {
+	return new Promise((resolve) => {
+		let last = "";
+		const repaint = () => {
+			let text;
+			try {
+				text = renderStatusView(carnet, io, options);
+			} catch (error) {
+				text = paint(io).dim(error instanceof Error ? error.message : String(error));
+			}
+			if (text === last) return;
+			last = text;
+			io.stdout(`${CLEAR}${text}\n`);
+		};
+		const timer = setInterval(repaint, options.intervalMilliseconds);
+		const stop = () => {
+			clearInterval(timer);
+			io.stdout(SHOW_CURSOR);
+			resolve();
+		};
+		options.signal?.addEventListener("abort", stop, { once: true });
+		io.stdout(HIDE_CURSOR);
+		repaint();
+	});
+}
+// src/commands/sessions.ts
+function lastActive(at, now) {
+	const date = new Date(at);
+	return date.toDateString() === now.toDateString() ? formatClock(date) : date.toISOString().slice(0, 10);
+}
+function row(carnet, session, now) {
+	const open = carnet.agents.list(session.id).length;
+	return [
+		session.name ?? session.id.slice(0, 8),
+		session.status,
+		sessionWhere(carnet, session) ?? "",
+		lastActive(session.lastActiveAt, now),
+		open ? `${open} agent${open > 1 ? "s" : ""}` : "",
+		session.purpose ?? ""
+	];
+}
+function sessionsOnce(carnet, io, options = {}) {
+	const colors = paint(io);
+	const sessions = carnet.sessions.list({
+		includeTemporary: options.all,
+		includeDropped: options.all
+	});
+	if (sessions.length === 0) {
+		const hint = options.all ? "" : " (temporary ones are hidden, use --all)";
+		io.stdout(`${colors.dim(`no named session yet${hint}`)}\n`);
+		return;
+	}
+	const now = options.now ?? /* @__PURE__ */ new Date();
+	const rows = sessions.map((session) => ({
+		session,
+		cells: row(carnet, session, now)
+	}));
+	const widths = rows.reduce((current, { cells }) => cells.map((cell, column) => Math.max(current[column] ?? 0, cell.length)), []);
+	const lines = rows.map(({ session, cells }) => {
+		return cells.map((cell, column) => {
+			const padded = column < cells.length - 1 ? cell.padEnd(widths[column] ?? 0) : cell;
+			if (column === 0) return colors.bold(padded);
+			if (column === 1 && session.status !== "active") return colors.dim(padded);
+			return padded;
+		}).join("  ").trimEnd();
+	});
+	io.stdout(`${lines.join("\n")}\n`);
+}
+function sessionsMerge(carnet, fromReference, intoReference, io) {
+	const from = findSession(carnet, fromReference);
+	const into = findSession(carnet, intoReference);
+	const result = carnet.sessions.merge(from.id, into.id);
+	const label = (session) => session.name ?? session.id.slice(0, 8);
+	const lines = [
+		`merged ${label(from)} into ${label(result.session)}`,
+		`  agents moved: ${result.movedAgents.join(", ") || "none"}`,
+		...result.closedAgents.length ? [`  agents closed (name already used): ${result.closedAgents.join(", ")}`] : [],
+		`  events moved: ${result.movedEvents}`,
+		`  table line moved: ${result.movedTable ? "yes" : "no"}`
+	];
+	io.stdout(`${lines.join("\n")}\n`);
+}
+// src/io.ts
+function processIo(options = {}) {
+	const tty = process.stdout.isTTY === true;
+	const colorWanted = options.color ?? true;
+	return {
+		stdout: (text) => process.stdout.write(text),
+		stderr: (text) => process.stderr.write(text),
+		cwd: process.cwd(),
+		env: process.env,
+		color: tty && colorWanted && !process.env.NO_COLOR,
+		columns: process.stdout.columns ?? 80
+	};
+}
+function readStdin() {
+	return new Promise((resolve) => {
+		let data = "";
+		process.stdin.setEncoding("utf8");
+		process.stdin.on("data", (chunk) => {
+			data += chunk;
+		});
+		process.stdin.on("end", () => resolve(data));
+		process.stdin.on("error", () => resolve(data));
+	});
+}
+// src/main.ts
+function fail(io, error) {
+	if (error instanceof CliError) io.stderr(`error: ${error.message}${error.hint ? `\n  ${error.hint}` : ""}\n`);
+	else if (error instanceof CarnetError) io.stderr(`error: ${error.message}\n`);
+	else io.stderr(`error: ${error instanceof Error ? error.message : String(error)}\n`);
+	process.exit(1);
+}
+const colorArgument = { color: {
+	type: "boolean",
+	default: true,
+	description: "Colored output (--no-color to disable)"
+} };
+const sessionArgument = { session: {
+	type: "string",
+	alias: "s",
+	description: "Session name, id or id prefix (default: most recently active)"
+} };
+const initCommand = defineCommand({
+	meta: {
+		name: "init",
+		description: "Make the current directory a Rucher group (meta directory)"
+	},
+	args: {
+		directory: {
+			type: "positional",
+			description: "Meta directory (default: current directory)",
+			required: false
+		},
+		name: {
+			type: "string",
+			description: "Group name (default: directory name)"
+		},
+		repos: {
+			type: "string",
+			description: "Comma-separated repo paths (more later with `rucher group add`)"
+		},
+		...colorArgument
+	},
+	run({ args }) {
+		const io = processIo({ color: args.color });
+		const repos = args.repos ? args.repos.split(",").map((repo) => repo.trim()).filter(Boolean) : void 0;
+		process.exitCode = init({
+			directory: args.directory,
+			name: args.name,
+			repos
+		}, io);
+	}
+});
+const statusCommand = defineCommand({
+	meta: {
+		name: "status",
+		description: "Show agent statuses of a session"
+	},
+	args: {
+		...sessionArgument,
+		all: {
+			type: "boolean",
+			default: false,
+			description: "Every session with activity"
+		},
+		watch: {
+			type: "boolean",
+			alias: "w",
+			default: false,
+			description: "Refresh continuously"
+		},
+		interval: {
+			type: "string",
+			default: "1",
+			description: "Refresh interval in seconds with --watch"
+		},
+		...colorArgument
+	},
+	async run({ args }) {
+		const io = processIo({ color: args.color });
+		try {
+			const carnet = openCarnet({
+				cwd: io.cwd,
+				env: io.env
+			});
+			const options = {
+				session: args.session,
+				all: args.all
+			};
+			if (!args.watch) {
+				statusOnce(carnet, io, options);
+				return;
+			}
+			const controller = new AbortController();
+			process.on("SIGINT", () => controller.abort());
+			process.on("SIGTERM", () => controller.abort());
+			const intervalMilliseconds = Math.max(Number(args.interval) || 1, .2) * 1e3;
+			await statusWatch(carnet, io, {
+				...options,
+				intervalMilliseconds,
+				signal: controller.signal
+			});
+		} catch (error) {
+			fail(io, error);
+		}
+	}
+});
+const logCommand = defineCommand({
+	meta: {
+		name: "log",
+		description: "Show the last journal events of a session"
+	},
+	args: {
+		...sessionArgument,
+		count: {
+			type: "string",
+			alias: "n",
+			default: "20",
+			description: "Number of events"
+		},
+		md: {
+			type: "boolean",
+			default: false,
+			description: "Markdown output, for archiving"
+		},
+		...colorArgument
+	},
+	run({ args }) {
+		const io = processIo({ color: args.color });
+		try {
+			logOnce(openCarnet({
+				cwd: io.cwd,
+				env: io.env
+			}), io, {
+				session: args.session,
+				count: Number(args.count) || 20,
+				md: args.md
+			});
+		} catch (error) {
+			fail(io, error);
+		}
+	}
+});
+const sessionsListCommand = defineCommand({
+	meta: {
+		name: "list",
+		description: "List the named sessions of the group"
+	},
+	args: {
+		all: {
+			type: "boolean",
+			default: false,
+			description: "Include temporary and dropped sessions"
+		},
+		...colorArgument
+	},
+	run({ args }) {
+		const io = processIo({ color: args.color });
+		try {
+			sessionsOnce(openCarnet({
+				cwd: io.cwd,
+				env: io.env
+			}), io, { all: args.all });
+		} catch (error) {
+			fail(io, error);
+		}
+	}
+});
+const sessionsMergeCommand = defineCommand({
+	meta: {
+		name: "merge",
+		description: "Move the agents, table line and journal of one session into another, then drop it"
+	},
+	args: {
+		from: {
+			type: "positional",
+			description: "Session to empty (name, id or id prefix)",
+			required: true
+		},
+		into: {
+			type: "positional",
+			description: "Session that keeps everything (name, id or id prefix)",
+			required: true
+		}
+	},
+	run({ args }) {
+		const io = processIo();
+		try {
+			const carnet = openCarnet({
+				cwd: io.cwd,
+				env: io.env
+			});
+			sessionsMerge(carnet, args.from, args.into, io);
+			carnet.close();
+		} catch (error) {
+			fail(io, error);
+		}
+	}
+});
+const sessionsCommand = defineCommand({
+	meta: {
+		name: "sessions",
+		description: "List or merge the sessions of the group"
+	},
+	default: "list",
+	subCommands: {
+		list: sessionsListCommand,
+		merge: sessionsMergeCommand
+	}
+});
+const resumeCommand = defineCommand({
+	meta: {
+		name: "resume",
+		description: "Resume a named session in its host (Claude Code today)"
+	},
+	args: { name: {
+		type: "positional",
+		description: "Session name, id or id prefix",
+		required: true
+	} },
+	run({ args }) {
+		const io = processIo();
+		try {
+			const carnet = openCarnet({
+				cwd: io.cwd,
+				env: io.env
+			});
+			const target = resumeTarget(carnet, args.name, io);
+			carnet.close();
+			process.exitCode = runTarget(target);
+		} catch (error) {
+			fail(io, error);
+		}
+	}
+});
+const groupCommand = defineCommand({
+	meta: {
+		name: "group",
+		description: "Show the current group, add or remove repos, sync its settings"
+	},
+	subCommands: {
+		show: defineCommand({
+			meta: {
+				name: "show",
+				description: "Name, meta directory and repos of the current group"
+			},
+			args: { ...colorArgument },
+			run({ args }) {
+				const io = processIo({ color: args.color });
+				try {
+					process.exitCode = groupShow(io);
+				} catch (error) {
+					fail(io, error);
+				}
+			}
+		}),
+		add: defineCommand({
+			meta: {
+				name: "add",
+				description: "Add a repo path to the current group"
+			},
+			args: {
+				path: {
+					type: "positional",
+					description: "Repo path",
+					required: true
+				},
+				...colorArgument
+			},
+			run({ args }) {
+				const io = processIo({ color: args.color });
+				try {
+					process.exitCode = groupAdd(args.path, io);
+				} catch (error) {
+					fail(io, error);
+				}
+			}
+		}),
+		remove: defineCommand({
+			meta: {
+				name: "remove",
+				description: "Remove a repo path from the current group"
+			},
+			args: {
+				path: {
+					type: "positional",
+					description: "Repo path",
+					required: true
+				},
+				...colorArgument
+			},
+			run({ args }) {
+				const io = processIo({ color: args.color });
+				try {
+					process.exitCode = groupRemove(args.path, io);
+				} catch (error) {
+					fail(io, error);
+				}
+			}
+		}),
+		sync: defineCommand({
+			meta: {
+				name: "sync",
+				description: "Rewrite the hosts' context files (repo list, directory access) from group.json"
+			},
+			args: { ...colorArgument },
+			run({ args }) {
+				const io = processIo({ color: args.color });
+				try {
+					process.exitCode = groupSync(io);
+				} catch (error) {
+					fail(io, error);
+				}
+			}
+		})
+	}
+});
+const groupsCommand = defineCommand({
+	meta: {
+		name: "groups",
+		description: "Registered groups of this machine"
+	},
+	subCommands: {
+		list: defineCommand({
+			meta: {
+				name: "list",
+				description: "Registered groups, missing ones flagged"
+			},
+			args: { ...colorArgument },
+			run({ args }) {
+				process.exitCode = groupsList(processIo({ color: args.color }));
+			}
+		}),
+		forget: defineCommand({
+			meta: {
+				name: "forget",
+				description: "Unregister a group by name or meta directory path"
+			},
+			args: {
+				reference: {
+					type: "positional",
+					description: "Group name or path",
+					required: true
+				},
+				...colorArgument
+			},
+			run({ args }) {
+				process.exitCode = groupsForget(args.reference, processIo({ color: args.color }));
+			}
+		}),
+		prune: defineCommand({
+			meta: {
+				name: "prune",
+				description: "Unregister groups whose meta directory is gone"
+			},
+			args: { ...colorArgument },
+			run({ args }) {
+				process.exitCode = groupsPrune(processIo({ color: args.color }));
+			}
+		})
+	}
+});
+const hookCommand = defineCommand({
+	meta: {
+		name: "hook",
+		description: "Agent host hook entry points (Claude Code, JSON payload on stdin)"
+	},
+	subCommands: {
+		"session-start": defineCommand({
+			meta: {
+				name: "session-start",
+				description: "SessionStart hook: records the session"
+			},
+			async run() {
+				process.exitCode = sessionStart(await readStdin(), processIo());
+			}
+		}),
+		"user-prompt-submit": defineCommand({
+			meta: {
+				name: "user-prompt-submit",
+				description: "UserPromptSubmit hook: names the session after a /rename"
+			},
+			async run() {
+				process.exitCode = userPromptSubmit(await readStdin(), processIo());
+			}
+		}),
+		"subagent-start": defineCommand({
+			meta: {
+				name: "subagent-start",
+				description: "SubagentStart hook: pairs the fork with its agent"
+			},
+			async run() {
+				process.exitCode = subagentStart(await readStdin(), processIo());
+			}
+		}),
+		"subagent-stop": defineCommand({
+			meta: {
+				name: "subagent-stop",
+				description: "SubagentStop hook: flags a fork that never called agent_done"
+			},
+			async run() {
+				process.exitCode = subagentStop(await readStdin(), processIo());
+			}
+		})
+	}
+});
+const serveCommand = defineCommand({
+	meta: {
+		name: "serve",
+		description: "Run the Carnet MCP server over stdio"
+	},
+	run() {
+		serve(processIo());
+	}
+});
+const main = defineCommand({
+	meta: {
+		name: "rucher",
+		version,
+		description: "Status, journal and sessions of your coding agents (Claude Code today)"
+	},
+	subCommands: {
+		init: initCommand,
+		status: statusCommand,
+		log: logCommand,
+		sessions: sessionsCommand,
+		resume: resumeCommand,
+		group: groupCommand,
+		groups: groupsCommand,
+		hook: hookCommand,
+		serve: serveCommand
+	}
+});
+// src/cli.ts
+await setupCompletion(main);
+runMain(main);
+export {};

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@rucher/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "rucher: status, journal and sessions of your Claude Code sub-agents, from the terminal",
+  "keywords": [
+    "agents",
+    "claude-code",
+    "cli",
+    "multi-agent",
+    "status"
+  ],
+  "homepage": "https://github.com/Florian-Varrin/Rucher/tree/master/packages/cli#readme",
+  "bugs": {
+    "url": "https://github.com/Florian-Varrin/Rucher/issues"
+  },
+  "license": "MIT",
+  "author": "Florian Varrin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Florian-Varrin/Rucher.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "rucher": "./dist/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@bomb.sh/tab": "0.0.22",
+    "@rucher/carnet": "0.1.0",
+    "citty": "^0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24",
+    "typescript": "^7.0.2",
+    "vite-plus": "1.4.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
 }