@oomfware/cgr 0.1.1 → 0.1.2

package/README.md

@@ -16,7 +16,10 @@ cgr ask github.com/facebook/react "How do hooks track dependencies to avoid stal
 cgr ask -m sonnet github.com/shadcn-ui/ui "How does the registry system resolve component dependencies?"
 
 # checkout a specific branch
-cgr ask -b canary github.com/vercel/next.js "Where is dynamic route resolution handled in the app router?"
+cgr ask github.com/vercel/next.js#canary "Where is dynamic route resolution handled in the app router?"
+
+# ask about multiple repositories at once
+cgr ask github.com/facebook/react -w github.com/vercel/next.js "How does Next.js integrate with React's server components?"
 
 # works with any git host
 cgr ask tangled.sh/mary.my.id/atcute "How do I validate AT Protocol lexicon schemas at runtime?"
@@ -39,7 +42,7 @@ cgr clean --all
 ## commands
 
 ```
-cgr ask [-m opus|sonnet|haiku] [-b branch] <repo> <question>
+cgr ask [-m opus|sonnet|haiku] [-w repo#branch ...] <repo#branch> <question>
 cgr clean [--all | <repo>]
 ```
 
@@ -55,14 +58,17 @@ add this to your `~/.claude/CLAUDE.md` or project's `CLAUDE.md` to let Claude Co
 ```markdown
 ## cgr
 
-Use `npx @oomfware/cgr ask <repo> <question>` to research external repositories. examples:
+Use `npx @oomfware/cgr ask <repo> <question>` to ask questions about external repositories.
 
 - `npx @oomfware/cgr ask github.com/facebook/react "How do hooks track dependencies to avoid stale closures in useEffect?"`
-- `npx @oomfware/cgr ask -b canary github.com/vercel/next.js "Where is dynamic route resolution handled in the app router?"`
+- `npx @oomfware/cgr ask github.com/vercel/next.js#canary "Where is dynamic route resolution handled in the app router?"`
 - `npx @oomfware/cgr ask -m sonnet github.com/shadcn-ui/ui "How do I configure path aliases so components install to the right location?"`
+- `npx @oomfware/cgr ask github.com/facebook/react -w github.com/vercel/next.js "How does Next.js integrate with React's server components?"`
+
+cgr works best with detailed questions. Include file/folder paths when you know them, and reference
+details from previous answers in follow-ups.
 
-This clones the repo locally and runs Claude Code in read-only mode to analyze it. Run
-`npx @oomfware/cgr --help` for more options.
+Run `npx @oomfware/cgr --help` for more options.
 ```
 
 alternatively, a more structured prompt:
@@ -72,13 +78,13 @@ alternatively, a more structured prompt:
 
 You can use `@oomfware/cgr` to ask questions about external repositories.
 
-    npx @oomfware/cgr ask [options] <repo> <question>
+    npx @oomfware/cgr ask [options] <repo#branch> <question>
 
     options:
-      -m, --model <model>   model to use: opus, sonnet, haiku (default: haiku)
-      -b, --branch <branch> branch to checkout
+      -m, --model <model>  model to use: opus, sonnet, haiku (default: haiku)
+      -w, --with <repo>    additional repository to include (can be repeated)
 
-useful repositories:
+Useful repositories:
 
 - `github.com/facebook/react` for React internals, hooks, reconciler
 - `github.com/vercel/next.js` for Next.js app router, server components
@@ -86,6 +92,8 @@ useful repositories:
 - `github.com/tailwindlabs/tailwindcss` for Tailwind internals, plugin API
 - `github.com/bluesky-social/atproto` for AT Protocol, Bluesky API
 
-This clones the repo locally and runs Claude Code in read-only mode. Run `npx @oomfware/cgr --help`
-for more options.
+cgr works best with detailed questions. Include file/folder paths when you know them, and reference
+details from previous answers in follow-ups.
+
+Run `npx @oomfware/cgr --help` for more options.
 ```

package/dist/assets/system-prompt.md

@@ -26,21 +26,25 @@ user's question accurately and thoroughly by exploring the codebase.
 
 You also have read-only Bash access for standard Unix tools when needed.
 
-## Approach
-
-1. **Explore before answering** - Don't guess. Use Glob and Grep to find relevant files, then Read
-   to understand them.
-2. **Trace the code** - Follow imports, function calls, and data flow to build a complete picture.
-3. **Check history when relevant** - Use git log/blame/show to understand why code exists or how it
-   evolved.
-4. **Cite your sources** - Reference specific files and line numbers (e.g.,
-   `src/hooks/useState.ts:42`).
-5. **Use web resources** - If the codebase references external concepts or you need context, search
-   for documentation.
-
-## Response style
-
-- Be thorough but focused on the question asked
-- Include code snippets when they help explain concepts
-- Explain the "why" not just the "what"
-- If you're uncertain about something, say so and explain what you did find
+## Guidelines
+
+- **Explore first** - Don't guess. Use Glob and Grep to find relevant files, then Read to understand
+  them. Trace imports, function calls, and data flow.
+- **Cite your sources** - Reference file paths and line numbers. When specifics matter, include
+  actual code snippets rather than paraphrasing.
+- **Explain the why** - Don't just describe what code does; explain why it exists and how it fits
+  into the larger picture.
+- **Use history** - When relevant, use git log/blame/show to understand how code evolved.
+- **Admit uncertainty** - If you're unsure about something, say so and explain what you did find.
+
+When citing code, use this format:
+
+**`path/to/file.ts:42-50`**
+
+```typescript
+function example() {
+	return 'actual code from the file';
+}
+```
+
+If examining multiple repositories, prefix paths with the repository name.

package/dist/index.mjs

@@ -3,15 +3,16 @@ import { argument, choice, command, constant, message, object, option, or, strin
 import { run } from "@optique/run";
 import { spawn } from "node:child_process";
 import { dirname, join } from "node:path";
-import { optional, withDefault } from "@optique/core/modifiers";
+import { multiple, optional, withDefault } from "@optique/core/modifiers";
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { mkdir, rm } from "node:fs/promises";
+import { mkdir, rm, symlink } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
 import { createInterface } from "node:readline";
 
 //#region src/lib/git.ts
 /**
-* executes a git command and returns the result.
+* executes a git command silently, only showing output on failure.
 * @param args git command arguments
 * @param cwd working directory
 * @returns promise that resolves when the command completes
@@ -19,16 +20,27 @@ import { createInterface } from "node:readline";
 const git = (args, cwd) => new Promise((resolve, reject) => {
 	const proc = spawn("git", args, {
 		cwd,
-		stdio: "inherit"
+		stdio: [
+			"inherit",
+			"pipe",
+			"pipe"
+		]
+	});
+	let stderr = "";
+	proc.stderr.on("data", (data) => {
+		stderr += data.toString();
 	});
 	proc.on("close", (code) => {
 		if (code === 0) resolve();
-		else reject(/* @__PURE__ */ new Error(`git ${args[0]} failed with code ${code}`));
+		else {
+			if (stderr) process.stderr.write(stderr);
+			reject(/* @__PURE__ */ new Error(`git ${args[0]} failed with code ${code}`));
+		}
 	});
 	proc.on("error", reject);
 });
 /**
-* executes a git command and captures stdout.
+* executes a git command and captures stdout, only showing stderr on failure.
 * @param args git command arguments
 * @param cwd working directory
 * @returns promise that resolves with stdout
@@ -39,16 +51,23 @@ const gitOutput = (args, cwd) => new Promise((resolve, reject) => {
 		stdio: [
 			"inherit",
 			"pipe",
-			"inherit"
+			"pipe"
 		]
 	});
 	let output = "";
+	let stderr = "";
 	proc.stdout.on("data", (data) => {
 		output += data.toString();
 	});
+	proc.stderr.on("data", (data) => {
+		stderr += data.toString();
+	});
 	proc.on("close", (code) => {
 		if (code === 0) resolve(output.trim());
-		else reject(/* @__PURE__ */ new Error(`git ${args[0]} failed with code ${code}`));
+		else {
+			if (stderr) process.stderr.write(stderr);
+			reject(/* @__PURE__ */ new Error(`git ${args[0]} failed with code ${code}`));
+		}
 	});
 	proc.on("error", reject);
 });
@@ -170,6 +189,70 @@ const getRepoCachePath = (remote) => {
 	if (!parsed) return null;
 	return join(getReposDir(), parsed.host, parsed.owner, parsed.repo);
 };
+/**
+* parses `remote#branch` syntax.
+* @param input the input string, e.g. `github.com/owner/repo#develop`
+* @returns object with remote and optional branch
+*/
+const parseRemoteWithBranch = (input) => {
+	const hashIndex = input.lastIndexOf("#");
+	if (hashIndex === -1) return { remote: input };
+	return {
+		remote: input.slice(0, hashIndex),
+		branch: input.slice(hashIndex + 1)
+	};
+};
+/**
+* returns the sessions directory within the cache.
+* @returns the sessions directory path
+*/
+const getSessionsDir = () => join(getCacheDir(), "sessions");
+/**
+* creates a new session directory with a random UUID.
+* @returns the path to the created session directory
+*/
+const createSessionDir = async () => {
+	const sessionPath = join(getSessionsDir(), randomUUID());
+	await mkdir(sessionPath, { recursive: true });
+	return sessionPath;
+};
+/**
+* removes a session directory.
+* @param sessionPath the session directory path
+*/
+const cleanupSessionDir = async (sessionPath) => {
+	await rm(sessionPath, {
+		recursive: true,
+		force: true
+	});
+};
+
+//#endregion
+//#region src/lib/symlink.ts
+/**
+* builds symlinks in a session directory for all repositories.
+* handles name conflicts by appending `-2`, `-3`, etc.
+* @param sessionPath the session directory path
+* @param repos array of repository entries to symlink
+* @returns map of directory name -> repo entry
+*/
+const buildSymlinkDir = async (sessionPath, repos) => {
+	const result$1 = /* @__PURE__ */ new Map();
+	const usedNames = /* @__PURE__ */ new Set();
+	for (const repo of repos) {
+		let name = repo.parsed.repo;
+		let suffix = 1;
+		while (usedNames.has(name)) {
+			suffix++;
+			name = `${repo.parsed.repo}-${suffix}`;
+		}
+		usedNames.add(name);
+		result$1.set(name, repo);
+		const linkPath = join(sessionPath, name);
+		await symlink(repo.cachePath, linkPath);
+	}
+	return result$1;
+};
 
 //#endregion
 //#region src/commands/ask.ts
@@ -183,40 +266,75 @@ const schema$1 = object({
 		"sonnet",
 		"haiku"
 	]), { description: message`model to use for analysis` }), "haiku"),
-	branch: optional(option("-b", "--branch", string(), { description: message`branch to checkout` })),
-	remote: argument(string({ metavar: "REPO" }), { description: message`git remote URL (HTTP/HTTPS/SSH)` }),
+	branch: optional(option("-b", "--branch", string(), { description: message`branch to checkout (deprecated: use repo#branch instead)` })),
+	with: withDefault(multiple(option("-w", "--with", string(), { description: message`additional repository to include` })), []),
+	remote: argument(string({ metavar: "REPO" }), { description: message`git remote URL (HTTP/HTTPS/SSH), optionally with #branch` }),
 	question: argument(string({ metavar: "QUESTION" }), { description: message`question to ask about the repository` })
 });
 /**
-* handles the ask command.
-* clones/updates the repository and spawns Claude Code to answer the question.
-* @param args parsed command arguments
+* prints an error message for invalid remote URL and exits.
+* @param remote the invalid remote URL
 */
-const handler$1 = async (args) => {
-	const parsed = parseRemote(args.remote);
-	if (!parsed) {
-		console.error(`error: invalid remote URL: ${args.remote}`);
-		console.error("expected format: host/owner/repo, e.g.:");
-		console.error("  github.com/user/repo");
-		console.error("  https://github.com/user/repo");
-		console.error("  git@github.com:user/repo.git");
-		process.exit(1);
-	}
-	const cachePath = getRepoCachePath(args.remote);
+const exitInvalidRemote = (remote) => {
+	console.error(`error: invalid remote URL: ${remote}`);
+	console.error("expected format: host/owner/repo, e.g.:");
+	console.error("  github.com/user/repo");
+	console.error("  https://github.com/user/repo");
+	console.error("  git@github.com:user/repo.git");
+	process.exit(1);
+};
+/**
+* validates and parses a remote string (with optional #branch).
+* @param input the remote string, possibly with #branch suffix
+* @returns parsed repo entry or exits on error
+*/
+const parseRepoInput = (input) => {
+	const { remote, branch } = parseRemoteWithBranch(input);
+	const parsed = parseRemote(remote);
+	if (!parsed) return exitInvalidRemote(remote);
+	const cachePath = getRepoCachePath(remote);
 	if (!cachePath) {
-		console.error(`error: could not determine cache path for: ${args.remote}`);
+		console.error(`error: could not determine cache path for: ${remote}`);
 		process.exit(1);
 	}
-	const remoteUrl = normalizeRemote(args.remote);
-	console.error(`preparing repository: ${parsed.host}/${parsed.owner}/${parsed.repo}`);
-	try {
-		await ensureRepo(remoteUrl, cachePath, args.branch);
-	} catch (err) {
-		console.error(`error: failed to prepare repository: ${err}`);
-		process.exit(1);
+	return {
+		remote,
+		parsed,
+		cachePath,
+		branch
+	};
+};
+/**
+* builds a context prompt for a single repository.
+* @param repo the repo entry
+* @returns context prompt string
+*/
+const buildSingleRepoContext = (repo) => {
+	return `You are examining ${`${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`} (checked out on ${repo.branch ?? "default branch"}).`;
+};
+/**
+* builds a context prompt for multiple repositories.
+* @param dirMap map of directory name -> repo entry
+* @returns context prompt string
+*/
+const buildMultiRepoContext = (dirMap) => {
+	const lines = ["You are examining multiple repositories:", ""];
+	for (const [dirName, repo] of dirMap) {
+		const repoDisplay = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+		const branchDisplay = repo.branch ?? "default branch";
+		lines.push(`- ${dirName}/ -> ${repoDisplay} (checked out on ${branchDisplay})`);
 	}
-	const contextPrompt = `You are examining ${`${parsed.host}/${parsed.owner}/${parsed.repo}`} (checked out on ${args.branch ?? "default branch"}).`;
-	const claude = spawn("claude", [
+	return lines.join("\n");
+};
+/**
+* spawns Claude Code and waits for it to exit.
+* @param cwd working directory
+* @param contextPrompt context prompt for Claude
+* @param args command arguments
+* @returns promise that resolves with exit code
+*/
+const spawnClaude = (cwd, contextPrompt, args) => new Promise((resolve, reject) => {
+	const claudeArgs = [
 		"-p",
 		args.question,
 		"--model",
@@ -227,17 +345,71 @@ const handler$1 = async (args) => {
 		systemPromptPath,
 		"--append-system-prompt",
 		contextPrompt
-	], {
-		cwd: cachePath,
+	];
+	console.error("spawning claude...");
+	const claude = spawn("claude", claudeArgs, {
+		cwd,
 		stdio: "inherit"
 	});
 	claude.on("close", (code) => {
-		process.exit(code ?? 0);
+		resolve(code ?? 0);
 	});
 	claude.on("error", (err) => {
-		console.error(`error: failed to spawn claude: ${err}`);
-		process.exit(1);
+		reject(/* @__PURE__ */ new Error(`failed to spawn claude: ${err}`));
 	});
+});
+/**
+* handles the ask command.
+* clones/updates the repository and spawns Claude Code to answer the question.
+* @param args parsed command arguments
+*/
+const handler$1 = async (args) => {
+	const mainRepo = parseRepoInput(args.remote);
+	if (!mainRepo.branch && args.branch) mainRepo.branch = args.branch;
+	if (args.with.length === 0) {
+		const remoteUrl = normalizeRemote(mainRepo.remote);
+		console.error(`preparing repository: ${mainRepo.parsed.host}/${mainRepo.parsed.owner}/${mainRepo.parsed.repo}`);
+		try {
+			await ensureRepo(remoteUrl, mainRepo.cachePath, mainRepo.branch);
+		} catch (err) {
+			console.error(`error: failed to prepare repository: ${err}`);
+			process.exit(1);
+		}
+		const contextPrompt = buildSingleRepoContext(mainRepo);
+		const exitCode$1 = await spawnClaude(mainRepo.cachePath, contextPrompt, args);
+		process.exit(exitCode$1);
+	}
+	const allRepos = [mainRepo, ...args.with.map(parseRepoInput)];
+	console.error("preparing repositories...");
+	const prepareResults = await Promise.allSettled(allRepos.map(async (repo) => {
+		const remoteUrl = normalizeRemote(repo.remote);
+		const display = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+		console.error(`  preparing: ${display}`);
+		await ensureRepo(remoteUrl, repo.cachePath, repo.branch);
+		return repo;
+	}));
+	const failures = [];
+	for (let i = 0; i < prepareResults.length; i++) {
+		const result$1 = prepareResults[i];
+		if (result$1.status === "rejected") {
+			const repo = allRepos[i];
+			const display = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+			failures.push(`  ${display}: ${result$1.reason}`);
+		}
+	}
+	if (failures.length > 0) {
+		console.error("error: failed to prepare repositories:");
+		for (const failure of failures) console.error(failure);
+		process.exit(1);
+	}
+	const sessionPath = await createSessionDir();
+	let exitCode = 1;
+	try {
+		exitCode = await spawnClaude(sessionPath, buildMultiRepoContext(await buildSymlinkDir(sessionPath, allRepos)), args);
+	} finally {
+		await cleanupSessionDir(sessionPath);
+	}
+	process.exit(exitCode);
 };
 
 //#endregion
@@ -331,14 +503,20 @@ const confirm = (msg) => new Promise((resolve) => {
 */
 const handler = async (args) => {
 	const reposDir = getReposDir();
+	const sessionsDir = getSessionsDir();
 	if (args.all) {
-		if (!existsSync(reposDir)) {
-			console.log("no cached repositories found");
+		const reposExist = existsSync(reposDir);
+		const sessionsExist$1 = existsSync(sessionsDir);
+		if (!reposExist && !sessionsExist$1) {
+			console.log("no cached data found");
 			return;
 		}
-		const size = getDirSize(reposDir);
-		console.log(`removing all cached repositories (${formatSize(size)})`);
-		await rm(reposDir, { recursive: true });
+		let totalSize$1 = 0;
+		if (reposExist) totalSize$1 += getDirSize(reposDir);
+		if (sessionsExist$1) totalSize$1 += getDirSize(sessionsDir);
+		console.log(`removing all cached data (${formatSize(totalSize$1)})`);
+		if (reposExist) await rm(reposDir, { recursive: true });
+		if (sessionsExist$1) await rm(sessionsDir, { recursive: true });
 		console.log("done");
 		return;
 	}
@@ -359,20 +537,30 @@ const handler = async (args) => {
 		return;
 	}
 	const repos = listCachedRepos();
-	if (repos.length === 0) {
-		console.log("no cached repositories found");
+	const sessionsExist = existsSync(sessionsDir);
+	const sessionsSize = sessionsExist ? getDirSize(sessionsDir) : 0;
+	if (repos.length === 0 && !sessionsExist) {
+		console.log("no cached data found");
 		return;
 	}
-	console.log("cached repositories:\n");
 	let totalSize = 0;
-	for (const repo of repos) {
-		console.log(`  ${repo.displayPath.padEnd(50)} ${formatSize(repo.size)}`);
-		totalSize += repo.size;
+	if (repos.length > 0) {
+		console.log("cached repositories:\n");
+		for (const repo of repos) {
+			console.log(`  ${repo.displayPath.padEnd(50)} ${formatSize(repo.size)}`);
+			totalSize += repo.size;
+		}
+	}
+	if (sessionsExist && sessionsSize > 0) {
+		if (repos.length > 0) console.log();
+		console.log(`sessions: ${formatSize(sessionsSize)}`);
+		totalSize += sessionsSize;
 	}
 	console.log(`\n  total: ${formatSize(totalSize)}`);
 	console.log();
-	if (await confirm("remove all cached repositories?")) {
-		await rm(reposDir, { recursive: true });
+	if (await confirm("remove all cached data?")) {
+		if (repos.length > 0) await rm(reposDir, { recursive: true });
+		if (sessionsExist) await rm(sessionsDir, { recursive: true });
 		console.log("done");
 	}
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oomfware/cgr",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "ask questions about git repositories using Claude Code",
   "license": "0BSD",
   "repository": {

package/src/assets/system-prompt.md

@@ -26,21 +26,25 @@ user's question accurately and thoroughly by exploring the codebase.
 
 You also have read-only Bash access for standard Unix tools when needed.
 
-## Approach
-
-1. **Explore before answering** - Don't guess. Use Glob and Grep to find relevant files, then Read
-   to understand them.
-2. **Trace the code** - Follow imports, function calls, and data flow to build a complete picture.
-3. **Check history when relevant** - Use git log/blame/show to understand why code exists or how it
-   evolved.
-4. **Cite your sources** - Reference specific files and line numbers (e.g.,
-   `src/hooks/useState.ts:42`).
-5. **Use web resources** - If the codebase references external concepts or you need context, search
-   for documentation.
-
-## Response style
-
-- Be thorough but focused on the question asked
-- Include code snippets when they help explain concepts
-- Explain the "why" not just the "what"
-- If you're uncertain about something, say so and explain what you did find
+## Guidelines
+
+- **Explore first** - Don't guess. Use Glob and Grep to find relevant files, then Read to understand
+  them. Trace imports, function calls, and data flow.
+- **Cite your sources** - Reference file paths and line numbers. When specifics matter, include
+  actual code snippets rather than paraphrasing.
+- **Explain the why** - Don't just describe what code does; explain why it exists and how it fits
+  into the larger picture.
+- **Use history** - When relevant, use git log/blame/show to understand how code evolved.
+- **Admit uncertainty** - If you're unsure about something, say so and explain what you did find.
+
+When citing code, use this format:
+
+**`path/to/file.ts:42-50`**
+
+```typescript
+function example() {
+	return 'actual code from the file';
+}
+```
+
+If examining multiple repositories, prefix paths with the repository name.

package/src/commands/ask.ts

@@ -2,10 +2,18 @@ import { spawn } from 'node:child_process';
 import { join } from 'node:path';
 
 import { argument, choice, constant, type InferValue, message, object, option, string } from '@optique/core';
-import { optional, withDefault } from '@optique/core/modifiers';
+import { multiple, optional, withDefault } from '@optique/core/modifiers';
 
 import { ensureRepo } from '../lib/git.ts';
-import { getRepoCachePath, normalizeRemote, parseRemote } from '../lib/paths.ts';
+import {
+	cleanupSessionDir,
+	createSessionDir,
+	getRepoCachePath,
+	normalizeRemote,
+	parseRemote,
+	parseRemoteWithBranch,
+} from '../lib/paths.ts';
+import { buildSymlinkDir, type RepoEntry } from '../lib/symlink.ts';
 
 // resolve asset paths relative to the bundle (dist/index.mjs -> dist/assets/)
 const assetsDir = join(import.meta.dirname, 'assets');
@@ -20,13 +28,22 @@ export const schema = object({
 		}),
 		'haiku',
 	),
+	// TODO: deprecated in favor of #branch syntax, remove in future version
 	branch: optional(
 		option('-b', '--branch', string(), {
-			description: message`branch to checkout`,
+			description: message`branch to checkout (deprecated: use repo#branch instead)`,
 		}),
 	),
+	with: withDefault(
+		multiple(
+			option('-w', '--with', string(), {
+				description: message`additional repository to include`,
+			}),
+		),
+		[],
+	),
 	remote: argument(string({ metavar: 'REPO' }), {
-		description: message`git remote URL (HTTP/HTTPS/SSH)`,
+		description: message`git remote URL (HTTP/HTTPS/SSH), optionally with #branch`,
 	}),
 	question: argument(string({ metavar: 'QUESTION' }), {
 		description: message`question to ask about the repository`,
@@ -35,70 +52,184 @@ export const schema = object({
 
 export type Args = InferValue<typeof schema>;
 
+/**
+ * prints an error message for invalid remote URL and exits.
+ * @param remote the invalid remote URL
+ */
+const exitInvalidRemote = (remote: string): never => {
+	console.error(`error: invalid remote URL: ${remote}`);
+	console.error('expected format: host/owner/repo, e.g.:');
+	console.error('  github.com/user/repo');
+	console.error('  https://github.com/user/repo');
+	console.error('  git@github.com:user/repo.git');
+	process.exit(1);
+};
+
+/**
+ * validates and parses a remote string (with optional #branch).
+ * @param input the remote string, possibly with #branch suffix
+ * @returns parsed repo entry or exits on error
+ */
+const parseRepoInput = (input: string): RepoEntry => {
+	const { remote, branch } = parseRemoteWithBranch(input);
+	const parsed = parseRemote(remote);
+	if (!parsed) {
+		return exitInvalidRemote(remote);
+	}
+	const cachePath = getRepoCachePath(remote);
+	if (!cachePath) {
+		console.error(`error: could not determine cache path for: ${remote}`);
+		process.exit(1);
+	}
+	return { remote, parsed, cachePath, branch };
+};
+
+/**
+ * builds a context prompt for a single repository.
+ * @param repo the repo entry
+ * @returns context prompt string
+ */
+const buildSingleRepoContext = (repo: RepoEntry): string => {
+	const repoDisplay = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+	const branchDisplay = repo.branch ?? 'default branch';
+	return `You are examining ${repoDisplay} (checked out on ${branchDisplay}).`;
+};
+
+/**
+ * builds a context prompt for multiple repositories.
+ * @param dirMap map of directory name -> repo entry
+ * @returns context prompt string
+ */
+const buildMultiRepoContext = (dirMap: Map<string, RepoEntry>): string => {
+	const lines = ['You are examining multiple repositories:', ''];
+	for (const [dirName, repo] of dirMap) {
+		const repoDisplay = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+		const branchDisplay = repo.branch ?? 'default branch';
+		lines.push(`- ${dirName}/ -> ${repoDisplay} (checked out on ${branchDisplay})`);
+	}
+	return lines.join('\n');
+};
+
+/**
+ * spawns Claude Code and waits for it to exit.
+ * @param cwd working directory
+ * @param contextPrompt context prompt for Claude
+ * @param args command arguments
+ * @returns promise that resolves with exit code
+ */
+const spawnClaude = (cwd: string, contextPrompt: string, args: Args): Promise<number> =>
+	new Promise((resolve, reject) => {
+		const claudeArgs = [
+			'-p',
+			args.question,
+			'--model',
+			args.model,
+			'--settings',
+			settingsPath,
+			'--system-prompt-file',
+			systemPromptPath,
+			'--append-system-prompt',
+			contextPrompt,
+		];
+
+		console.error('spawning claude...');
+		const claude = spawn('claude', claudeArgs, {
+			cwd,
+			stdio: 'inherit',
+		});
+
+		claude.on('close', (code) => {
+			resolve(code ?? 0);
+		});
+
+		claude.on('error', (err) => {
+			reject(new Error(`failed to spawn claude: ${err}`));
+		});
+	});
+
 /**
  * handles the ask command.
  * clones/updates the repository and spawns Claude Code to answer the question.
  * @param args parsed command arguments
  */
 export const handler = async (args: Args): Promise<void> => {
-	// validate remote URL
-	const parsed = parseRemote(args.remote);
-	if (!parsed) {
-		console.error(`error: invalid remote URL: ${args.remote}`);
-		console.error('expected format: host/owner/repo, e.g.:');
-		console.error('  github.com/user/repo');
-		console.error('  https://github.com/user/repo');
-		console.error('  git@github.com:user/repo.git');
-		process.exit(1);
+	// parse main remote (with optional #branch)
+	const mainRepo = parseRepoInput(args.remote);
+
+	// #branch takes precedence over -b flag
+	if (!mainRepo.branch && args.branch) {
+		mainRepo.branch = args.branch;
 	}
 
-	// get cache path
-	const cachePath = getRepoCachePath(args.remote);
-	if (!cachePath) {
-		console.error(`error: could not determine cache path for: ${args.remote}`);
-		process.exit(1);
+	// #region single repo mode
+	if (args.with.length === 0) {
+		// clone or update repository
+		const remoteUrl = normalizeRemote(mainRepo.remote);
+		console.error(
+			`preparing repository: ${mainRepo.parsed.host}/${mainRepo.parsed.owner}/${mainRepo.parsed.repo}`,
+		);
+		try {
+			await ensureRepo(remoteUrl, mainRepo.cachePath, mainRepo.branch);
+		} catch (err) {
+			console.error(`error: failed to prepare repository: ${err}`);
+			process.exit(1);
+		}
+
+		const contextPrompt = buildSingleRepoContext(mainRepo);
+		const exitCode = await spawnClaude(mainRepo.cachePath, contextPrompt, args);
+		process.exit(exitCode);
 	}
+	// #endregion
 
-	// clone or update repository
-	const remoteUrl = normalizeRemote(args.remote);
-	console.error(`preparing repository: ${parsed.host}/${parsed.owner}/${parsed.repo}`);
-	try {
-		await ensureRepo(remoteUrl, cachePath, args.branch);
-	} catch (err) {
-		console.error(`error: failed to prepare repository: ${err}`);
+	// #region multi repo mode
+	// parse all -w remotes
+	const additionalRepos = args.with.map(parseRepoInput);
+	const allRepos = [mainRepo, ...additionalRepos];
+
+	// clone/update all repos in parallel
+	console.error('preparing repositories...');
+	const prepareResults = await Promise.allSettled(
+		allRepos.map(async (repo) => {
+			const remoteUrl = normalizeRemote(repo.remote);
+			const display = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+			console.error(`  preparing: ${display}`);
+			await ensureRepo(remoteUrl, repo.cachePath, repo.branch);
+			return repo;
+		}),
+	);
+
+	// check for failures
+	const failures: string[] = [];
+	for (let i = 0; i < prepareResults.length; i++) {
+		const result = prepareResults[i]!;
+		if (result.status === 'rejected') {
+			const repo = allRepos[i]!;
+			const display = `${repo.parsed.host}/${repo.parsed.owner}/${repo.parsed.repo}`;
+			failures.push(`  ${display}: ${result.reason}`);
+		}
+	}
+
+	if (failures.length > 0) {
+		console.error('error: failed to prepare repositories:');
+		for (const failure of failures) {
+			console.error(failure);
+		}
 		process.exit(1);
 	}
 
-	// build context for append prompt
-	const repoDisplay = `${parsed.host}/${parsed.owner}/${parsed.repo}`;
-	const branchDisplay = args.branch ?? 'default branch';
-	const contextPrompt = `You are examining ${repoDisplay} (checked out on ${branchDisplay}).`;
-
-	// spawn Claude Code
-	const claudeArgs = [
-		'-p',
-		args.question,
-		'--model',
-		args.model,
-		'--settings',
-		settingsPath,
-		'--system-prompt-file',
-		systemPromptPath,
-		'--append-system-prompt',
-		contextPrompt,
-	];
-
-	const claude = spawn('claude', claudeArgs, {
-		cwd: cachePath,
-		stdio: 'inherit',
-	});
+	// create session directory and symlinks
+	const sessionPath = await createSessionDir();
+	let exitCode = 1;
 
-	claude.on('close', (code) => {
-		process.exit(code ?? 0);
-	});
+	try {
+		const dirMap = await buildSymlinkDir(sessionPath, allRepos);
+		const contextPrompt = buildMultiRepoContext(dirMap);
+		exitCode = await spawnClaude(sessionPath, contextPrompt, args);
+	} finally {
+		// always clean up session directory
+		await cleanupSessionDir(sessionPath);
+	}
 
-	claude.on('error', (err) => {
-		console.error(`error: failed to spawn claude: ${err}`);
-		process.exit(1);
-	});
+	process.exit(exitCode);
+	// #endregion
 };

package/src/commands/clean.ts

@@ -6,7 +6,7 @@ import { createInterface } from 'node:readline';
 import { argument, constant, type InferValue, message, object, option, string } from '@optique/core';
 import { optional } from '@optique/core/modifiers';
 
-import { getRepoCachePath, getReposDir } from '../lib/paths.ts';
+import { getRepoCachePath, getReposDir, getSessionsDir } from '../lib/paths.ts';
 
 export const schema = object({
 	command: constant('clean'),
@@ -142,16 +142,33 @@ const confirm = (msg: string): Promise<boolean> =>
  */
 export const handler = async (args: Args): Promise<void> => {
 	const reposDir = getReposDir();
+	const sessionsDir = getSessionsDir();
 
 	// clean all
 	if (args.all) {
-		if (!existsSync(reposDir)) {
-			console.log('no cached repositories found');
+		const reposExist = existsSync(reposDir);
+		const sessionsExist = existsSync(sessionsDir);
+
+		if (!reposExist && !sessionsExist) {
+			console.log('no cached data found');
 			return;
 		}
-		const size = getDirSize(reposDir);
-		console.log(`removing all cached repositories (${formatSize(size)})`);
-		await rm(reposDir, { recursive: true });
+
+		let totalSize = 0;
+		if (reposExist) {
+			totalSize += getDirSize(reposDir);
+		}
+		if (sessionsExist) {
+			totalSize += getDirSize(sessionsDir);
+		}
+
+		console.log(`removing all cached data (${formatSize(totalSize)})`);
+		if (reposExist) {
+			await rm(reposDir, { recursive: true });
+		}
+		if (sessionsExist) {
+			await rm(sessionsDir, { recursive: true });
+		}
 		console.log('done');
 		return;
 	}
@@ -176,23 +193,43 @@ export const handler = async (args: Args): Promise<void> => {
 
 	// list repos and prompt for confirmation
 	const repos = listCachedRepos();
-	if (repos.length === 0) {
-		console.log('no cached repositories found');
+	const sessionsExist = existsSync(sessionsDir);
+	const sessionsSize = sessionsExist ? getDirSize(sessionsDir) : 0;
+
+	if (repos.length === 0 && !sessionsExist) {
+		console.log('no cached data found');
 		return;
 	}
 
-	console.log('cached repositories:\n');
 	let totalSize = 0;
-	for (const repo of repos) {
-		console.log(`  ${repo.displayPath.padEnd(50)} ${formatSize(repo.size)}`);
-		totalSize += repo.size;
+
+	if (repos.length > 0) {
+		console.log('cached repositories:\n');
+		for (const repo of repos) {
+			console.log(`  ${repo.displayPath.padEnd(50)} ${formatSize(repo.size)}`);
+			totalSize += repo.size;
+		}
+	}
+
+	if (sessionsExist && sessionsSize > 0) {
+		if (repos.length > 0) {
+			console.log();
+		}
+		console.log(`sessions: ${formatSize(sessionsSize)}`);
+		totalSize += sessionsSize;
 	}
+
 	console.log(`\n  total: ${formatSize(totalSize)}`);
 	console.log();
 
-	const confirmed = await confirm('remove all cached repositories?');
+	const confirmed = await confirm('remove all cached data?');
 	if (confirmed) {
-		await rm(reposDir, { recursive: true });
+		if (repos.length > 0) {
+			await rm(reposDir, { recursive: true });
+		}
+		if (sessionsExist) {
+			await rm(sessionsDir, { recursive: true });
+		}
 		console.log('done');
 	}
 };

package/src/lib/git.ts

@@ -4,7 +4,7 @@ import { mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
 
 /**
- * executes a git command and returns the result.
+ * executes a git command silently, only showing output on failure.
  * @param args git command arguments
  * @param cwd working directory
  * @returns promise that resolves when the command completes
@@ -13,12 +13,19 @@ const git = (args: string[], cwd?: string): Promise<void> =>
 	new Promise((resolve, reject) => {
 		const proc = spawn('git', args, {
 			cwd,
-			stdio: 'inherit',
+			stdio: ['inherit', 'pipe', 'pipe'],
+		});
+		let stderr = '';
+		proc.stderr!.on('data', (data: Buffer) => {
+			stderr += data.toString();
 		});
 		proc.on('close', (code) => {
 			if (code === 0) {
 				resolve();
 			} else {
+				if (stderr) {
+					process.stderr.write(stderr);
+				}
 				reject(new Error(`git ${args[0]} failed with code ${code}`));
 			}
 		});
@@ -26,7 +33,7 @@ const git = (args: string[], cwd?: string): Promise<void> =>
 	});
 
 /**
- * executes a git command and captures stdout.
+ * executes a git command and captures stdout, only showing stderr on failure.
  * @param args git command arguments
  * @param cwd working directory
  * @returns promise that resolves with stdout
@@ -35,16 +42,23 @@ const gitOutput = (args: string[], cwd?: string): Promise<string> =>
 	new Promise((resolve, reject) => {
 		const proc = spawn('git', args, {
 			cwd,
-			stdio: ['inherit', 'pipe', 'inherit'],
+			stdio: ['inherit', 'pipe', 'pipe'],
 		});
 		let output = '';
+		let stderr = '';
 		proc.stdout!.on('data', (data: Buffer) => {
 			output += data.toString();
 		});
+		proc.stderr!.on('data', (data: Buffer) => {
+			stderr += data.toString();
+		});
 		proc.on('close', (code) => {
 			if (code === 0) {
 				resolve(output.trim());
 			} else {
+				if (stderr) {
+					process.stderr.write(stderr);
+				}
 				reject(new Error(`git ${args[0]} failed with code ${code}`));
 			}
 		});

package/src/lib/paths.ts

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, rm } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
@@ -90,3 +92,43 @@ export const getRepoCachePath = (remote: string): string | null => {
 	}
 	return join(getReposDir(), parsed.host, parsed.owner, parsed.repo);
 };
+
+/**
+ * parses `remote#branch` syntax.
+ * @param input the input string, e.g. `github.com/owner/repo#develop`
+ * @returns object with remote and optional branch
+ */
+export const parseRemoteWithBranch = (input: string): { remote: string; branch?: string } => {
+	const hashIndex = input.lastIndexOf('#');
+	if (hashIndex === -1) {
+		return { remote: input };
+	}
+	return {
+		remote: input.slice(0, hashIndex),
+		branch: input.slice(hashIndex + 1),
+	};
+};
+
+/**
+ * returns the sessions directory within the cache.
+ * @returns the sessions directory path
+ */
+export const getSessionsDir = (): string => join(getCacheDir(), 'sessions');
+
+/**
+ * creates a new session directory with a random UUID.
+ * @returns the path to the created session directory
+ */
+export const createSessionDir = async (): Promise<string> => {
+	const sessionPath = join(getSessionsDir(), randomUUID());
+	await mkdir(sessionPath, { recursive: true });
+	return sessionPath;
+};
+
+/**
+ * removes a session directory.
+ * @param sessionPath the session directory path
+ */
+export const cleanupSessionDir = async (sessionPath: string): Promise<void> => {
+	await rm(sessionPath, { recursive: true, force: true });
+};

package/src/lib/symlink.ts

@@ -0,0 +1,47 @@
+import { symlink } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/** parsed remote information */
+export type ParsedRemote = { host: string; owner: string; repo: string };
+
+/** repository entry with all metadata needed for symlinking */
+export type RepoEntry = {
+	remote: string;
+	parsed: ParsedRemote;
+	cachePath: string;
+	branch?: string;
+};
+
+/**
+ * builds symlinks in a session directory for all repositories.
+ * handles name conflicts by appending `-2`, `-3`, etc.
+ * @param sessionPath the session directory path
+ * @param repos array of repository entries to symlink
+ * @returns map of directory name -> repo entry
+ */
+export const buildSymlinkDir = async (
+	sessionPath: string,
+	repos: RepoEntry[],
+): Promise<Map<string, RepoEntry>> => {
+	const result = new Map<string, RepoEntry>();
+	const usedNames = new Set<string>();
+
+	for (const repo of repos) {
+		let name = repo.parsed.repo;
+		let suffix = 1;
+
+		// handle name conflicts
+		while (usedNames.has(name)) {
+			suffix++;
+			name = `${repo.parsed.repo}-${suffix}`;
+		}
+
+		usedNames.add(name);
+		result.set(name, repo);
+
+		const linkPath = join(sessionPath, name);
+		await symlink(repo.cachePath, linkPath);
+	}
+
+	return result;
+};