@oomfware/cgr 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2026 Mary
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# @oomfware/cgr
+
+ask questions about any git repository using Claude Code.
+
+```sh
+pnpm install -g @oomfware/cgr
+```
+
+## usage
+
+```sh
+# ask a question about a repository
+cgr ask github.com/facebook/react "How do hooks track dependencies to avoid stale closures?"
+
+# specify a model (default: haiku)
+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?"
+
+# works with any git host
+cgr ask tangled.sh/mary.my.id/atcute "How do I validate AT Protocol lexicon schemas at runtime?"
+```
+
+repositories are cached locally at `~/.cache/cgr/repos/<host>/<owner>/<repo>`. use `cgr clean` to
+manage the cache:
+
+```sh
+# list cached repos with sizes
+cgr clean
+
+# remove a specific repo
+cgr clean github.com/facebook/react
+
+# remove all cached repos
+cgr clean --all
+```
+
+## commands
+
+```
+cgr ask [-m opus|sonnet|haiku] [-b branch] <repo> <question>
+cgr clean [--all | <repo>]
+```
+
+| command | description                                                       |
+| ------- | ----------------------------------------------------------------- |
+| `ask`   | clone/update a repository and ask Claude Code a question about it |
+| `clean` | remove cached repositories                                        |
+
+## configuring CLAUDE.md
+
+add this to your `~/.claude/CLAUDE.md` or project's `CLAUDE.md` to let Claude Code know about cgr:
+
+```markdown
+## cgr
+
+Use `npx @oomfware/cgr ask <repo> <question>` to research external repositories. examples:
+
+- `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 -m sonnet github.com/shadcn-ui/ui "How do I configure path aliases so components install to the right location?"`
+
+This clones the repo locally and runs Claude Code in read-only mode to analyze it. Run
+`npx @oomfware/cgr --help` for more options.
+```
+
+alternatively, a more structured prompt:
+
+```markdown
+# cgr
+
+You can use `@oomfware/cgr` to ask questions about external repositories.
+
+    npx @oomfware/cgr ask [options] <repo> <question>
+
+    options:
+      -m, --model <model>   model to use: opus, sonnet, haiku (default: haiku)
+      -b, --branch <branch> branch to checkout
+
+useful repositories:
+
+- `github.com/facebook/react` for React internals, hooks, reconciler
+- `github.com/vercel/next.js` for Next.js app router, server components
+- `github.com/shadcn-ui/ui` for shadcn component patterns, registry system
+- `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.
+```

package/dist/assets/settings.json

@@ -0,0 +1,48 @@
+{
+	"permissions": {
+		"allow": [
+			"Read",
+			"Glob",
+			"Grep",
+			"WebFetch",
+			"WebSearch",
+
+			"Bash(git blame:*)",
+			"Bash(git branch:*)",
+			"Bash(git checkout:*)",
+			"Bash(git diff:*)",
+			"Bash(git log:*)",
+			"Bash(git show:*)",
+			"Bash(git status:*)",
+			"Bash(git tag:*)",
+
+			"Bash(cat:*)",
+			"Bash(file:*)",
+			"Bash(find:*)",
+			"Bash(grep:*)",
+			"Bash(head:*)",
+			"Bash(ls:*)",
+			"Bash(stat:*)",
+			"Bash(tail:*)",
+			"Bash(tree:*)",
+			"Bash(wc:*)",
+
+			"Bash(awk:*)",
+			"Bash(cut:*)",
+			"Bash(diff:*)",
+			"Bash(jq:*)",
+			"Bash(sed:*)",
+			"Bash(sort:*)",
+			"Bash(tr:*)",
+			"Bash(uniq:*)",
+			"Bash(xargs:*)",
+
+			"Bash(basename:*)",
+			"Bash(dirname:*)",
+			"Bash(realpath:*)",
+
+			"Bash(du:*)"
+		],
+		"deny": ["*"]
+	}
+}

package/dist/assets/system-prompt.md

@@ -0,0 +1,46 @@
+You are a code research assistant analyzing an external repository. Your goal is to answer the
+user's question accurately and thoroughly by exploring the codebase.
+
+## Available tools
+
+**File exploration:**
+
+- `Read` - Read file contents
+- `Glob` - Find files by pattern (e.g., `**/*.ts`, `src/**/*.test.js`)
+- `Grep` - Search file contents with regex
+
+**Git commands:**
+
+- `git log` - View commit history
+- `git show` - Inspect commits, files at specific revisions
+- `git diff` - Compare changes between commits/branches
+- `git blame` - See who changed each line and when
+- `git branch` - List branches
+- `git tag` - List tags
+- `git checkout` - Switch branches, tags, or view files at specific commits
+
+**External resources:**
+
+- `WebSearch` - Search the web for documentation, issues, discussions
+- `WebFetch` - Fetch specific URLs (docs, GitHub issues, etc.)
+
+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

package/dist/index.mjs

@@ -0,0 +1,392 @@
+#!/usr/bin/env node
+import { argument, choice, command, constant, message, object, option, or, string } from "@optique/core";
+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 { existsSync, readdirSync, statSync } from "node:fs";
+import { mkdir, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline";
+
+//#region src/lib/git.ts
+/**
+* executes a git command and returns the result.
+* @param args git command arguments
+* @param cwd working directory
+* @returns promise that resolves when the command completes
+*/
+const git = (args, cwd) => new Promise((resolve, reject) => {
+	const proc = spawn("git", args, {
+		cwd,
+		stdio: "inherit"
+	});
+	proc.on("close", (code) => {
+		if (code === 0) resolve();
+		else reject(/* @__PURE__ */ new Error(`git ${args[0]} failed with code ${code}`));
+	});
+	proc.on("error", reject);
+});
+/**
+* executes a git command and captures stdout.
+* @param args git command arguments
+* @param cwd working directory
+* @returns promise that resolves with stdout
+*/
+const gitOutput = (args, cwd) => new Promise((resolve, reject) => {
+	const proc = spawn("git", args, {
+		cwd,
+		stdio: [
+			"inherit",
+			"pipe",
+			"inherit"
+		]
+	});
+	let output = "";
+	proc.stdout.on("data", (data) => {
+		output += data.toString();
+	});
+	proc.on("close", (code) => {
+		if (code === 0) resolve(output.trim());
+		else reject(/* @__PURE__ */ new Error(`git ${args[0]} failed with code ${code}`));
+	});
+	proc.on("error", reject);
+});
+/**
+* clones a repository to the cache path.
+* @param remote the remote URL
+* @param cachePath the local cache path
+* @param branch optional branch to checkout
+*/
+const cloneRepo = async (remote, cachePath, branch) => {
+	await mkdir(dirname(cachePath), { recursive: true });
+	const args = ["clone"];
+	if (branch) args.push("--branch", branch);
+	args.push(remote, cachePath);
+	await git(args);
+};
+/**
+* updates an existing repository in the cache.
+* discards any local modifications, staged changes, and untracked files.
+* @param cachePath the local cache path
+* @param branch optional branch to checkout (uses default branch if not specified)
+*/
+const updateRepo = async (cachePath, branch) => {
+	await git(["fetch", "origin"], cachePath);
+	let targetBranch = branch;
+	if (!targetBranch) targetBranch = (await gitOutput(["symbolic-ref", "refs/remotes/origin/HEAD"], cachePath)).replace("refs/remotes/origin/", "");
+	await git([
+		"reset",
+		"--hard",
+		"HEAD"
+	], cachePath);
+	await git(["clean", "-fd"], cachePath);
+	await git([
+		"checkout",
+		"-f",
+		targetBranch
+	], cachePath);
+	await git([
+		"reset",
+		"--hard",
+		`origin/${targetBranch}`
+	], cachePath);
+};
+/**
+* ensures a repository is cloned and up-to-date.
+* @param remote the remote URL
+* @param cachePath the local cache path
+* @param branch optional branch to checkout
+*/
+const ensureRepo = async (remote, cachePath, branch) => {
+	if (existsSync(cachePath)) await updateRepo(cachePath, branch);
+	else await cloneRepo(remote, cachePath, branch);
+};
+
+//#endregion
+//#region src/lib/paths.ts
+/**
+* returns the cache directory for cgr.
+* uses `$XDG_CACHE_HOME/cgr` if set, otherwise falls back to:
+* - `~/.cache/cgr` on linux
+* - `~/Library/Caches/cgr` on macos
+* @returns the cache directory path
+*/
+const getCacheDir = () => {
+	const xdgCache = process.env["XDG_CACHE_HOME"];
+	if (xdgCache) return join(xdgCache, "cgr");
+	const home = homedir();
+	if (process.platform === "darwin") return join(home, "Library", "Caches", "cgr");
+	return join(home, ".cache", "cgr");
+};
+/**
+* returns the repos directory within the cache.
+* @returns the repos directory path
+*/
+const getReposDir = () => join(getCacheDir(), "repos");
+/**
+* parses a git remote URL and extracts host, owner, and repo.
+* supports HTTP(S), SSH, and bare URLs (assumes HTTPS).
+* @param remote the remote URL to parse
+* @returns parsed components or null if invalid
+*/
+const parseRemote = (remote) => {
+	const httpMatch = remote.match(/^https?:\/\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+	if (httpMatch) return {
+		host: httpMatch[1],
+		owner: httpMatch[2],
+		repo: httpMatch[3]
+	};
+	const sshMatch = remote.match(/^git@([^:]+):([^/]+)\/([^/]+?)(?:\.git)?$/);
+	if (sshMatch) return {
+		host: sshMatch[1],
+		owner: sshMatch[2],
+		repo: sshMatch[3]
+	};
+	const bareMatch = remote.match(/^([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+	if (bareMatch) return {
+		host: bareMatch[1],
+		owner: bareMatch[2],
+		repo: bareMatch[3]
+	};
+	return null;
+};
+/**
+* normalizes a remote URL by prepending https:// if no protocol is present.
+* @param remote the remote URL to normalize
+* @returns normalized URL with protocol
+*/
+const normalizeRemote = (remote) => {
+	if (remote.startsWith("https://") || remote.startsWith("http://") || remote.startsWith("git@")) return remote;
+	return `https://${remote}`;
+};
+/**
+* returns the cache path for a specific repository.
+* @param remote the remote URL
+* @returns the cache path or null if the remote URL is invalid
+*/
+const getRepoCachePath = (remote) => {
+	const parsed = parseRemote(remote);
+	if (!parsed) return null;
+	return join(getReposDir(), parsed.host, parsed.owner, parsed.repo);
+};
+
+//#endregion
+//#region src/commands/ask.ts
+const assetsDir = join(import.meta.dirname, "assets");
+const settingsPath = join(assetsDir, "settings.json");
+const systemPromptPath = join(assetsDir, "system-prompt.md");
+const schema$1 = object({
+	command: constant("ask"),
+	model: withDefault(option("-m", "--model", choice([
+		"opus",
+		"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)` }),
+	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
+*/
+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);
+	if (!cachePath) {
+		console.error(`error: could not determine cache path for: ${args.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);
+	}
+	const contextPrompt = `You are examining ${`${parsed.host}/${parsed.owner}/${parsed.repo}`} (checked out on ${args.branch ?? "default branch"}).`;
+	const claude = spawn("claude", [
+		"-p",
+		args.question,
+		"--model",
+		args.model,
+		"--settings",
+		settingsPath,
+		"--system-prompt-file",
+		systemPromptPath,
+		"--append-system-prompt",
+		contextPrompt
+	], {
+		cwd: cachePath,
+		stdio: "inherit"
+	});
+	claude.on("close", (code) => {
+		process.exit(code ?? 0);
+	});
+	claude.on("error", (err) => {
+		console.error(`error: failed to spawn claude: ${err}`);
+		process.exit(1);
+	});
+};
+
+//#endregion
+//#region src/commands/clean.ts
+const schema = object({
+	command: constant("clean"),
+	all: option("--all", { description: message`remove all cached repositories` }),
+	remote: optional(argument(string({ metavar: "URL" }), { description: message`specific remote URL to clean` }))
+});
+/**
+* formats a byte size in human-readable form.
+* @param bytes size in bytes
+* @returns formatted string
+*/
+const formatSize = (bytes) => {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+};
+/**
+* calculates the total size of a directory recursively.
+* @param dir directory path
+* @returns total size in bytes
+*/
+const getDirSize = (dir) => {
+	let size = 0;
+	try {
+		const entries = readdirSync(dir, { withFileTypes: true });
+		for (const entry of entries) {
+			const fullPath = join(dir, entry.name);
+			if (entry.isDirectory()) size += getDirSize(fullPath);
+			else size += statSync(fullPath).size;
+		}
+	} catch {}
+	return size;
+};
+/**
+* lists all cached repositories with their sizes.
+* @returns array of { path, displayPath, size } objects
+*/
+const listCachedRepos = () => {
+	const reposDir = getReposDir();
+	const repos = [];
+	if (!existsSync(reposDir)) return repos;
+	for (const host of readdirSync(reposDir)) {
+		const hostPath = join(reposDir, host);
+		if (!statSync(hostPath).isDirectory()) continue;
+		for (const owner of readdirSync(hostPath)) {
+			const ownerPath = join(hostPath, owner);
+			if (!statSync(ownerPath).isDirectory()) continue;
+			for (const repo of readdirSync(ownerPath)) {
+				const repoPath = join(ownerPath, repo);
+				if (!statSync(repoPath).isDirectory()) continue;
+				repos.push({
+					path: repoPath,
+					displayPath: `${host}/${owner}/${repo}`,
+					size: getDirSize(repoPath)
+				});
+			}
+		}
+	}
+	return repos;
+};
+/**
+* prompts the user for confirmation.
+* @param msg the prompt message
+* @returns promise that resolves to true if confirmed
+*/
+const confirm = (msg) => new Promise((resolve) => {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	rl.question(`${msg} [y/N] `, (answer) => {
+		rl.close();
+		resolve(answer.toLowerCase() === "y");
+	});
+});
+/**
+* handles the clean command.
+* @param args parsed command arguments
+*/
+const handler = async (args) => {
+	const reposDir = getReposDir();
+	if (args.all) {
+		if (!existsSync(reposDir)) {
+			console.log("no cached repositories found");
+			return;
+		}
+		const size = getDirSize(reposDir);
+		console.log(`removing all cached repositories (${formatSize(size)})`);
+		await rm(reposDir, { recursive: true });
+		console.log("done");
+		return;
+	}
+	if (args.remote) {
+		const cachePath = getRepoCachePath(args.remote);
+		if (!cachePath) {
+			console.error(`error: invalid remote URL: ${args.remote}`);
+			process.exit(1);
+		}
+		if (!existsSync(cachePath)) {
+			console.error(`error: repository not cached: ${args.remote}`);
+			process.exit(1);
+		}
+		const size = getDirSize(cachePath);
+		console.log(`removing ${cachePath} (${formatSize(size)})`);
+		await rm(cachePath, { recursive: true });
+		console.log("done");
+		return;
+	}
+	const repos = listCachedRepos();
+	if (repos.length === 0) {
+		console.log("no cached repositories 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;
+	}
+	console.log(`\n  total: ${formatSize(totalSize)}`);
+	console.log();
+	if (await confirm("remove all cached repositories?")) {
+		await rm(reposDir, { recursive: true });
+		console.log("done");
+	}
+};
+
+//#endregion
+//#region src/index.ts
+const result = run(or(command("ask", schema$1, { description: message`ask a question about a repository` }), command("clean", schema, { description: message`remove cached repositories` })), {
+	help: "both",
+	version: {
+		value: "0.1.0",
+		mode: "option"
+	},
+	brief: message`ask questions about git repositories using Claude Code`
+});
+switch (result.command) {
+	case "ask":
+		await handler$1(result);
+		break;
+	case "clean":
+		await handler(result);
+		break;
+}
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@oomfware/cgr",
+  "version": "0.1.0",
+  "description": "ask questions about git repositories using Claude Code",
+  "license": "0BSD",
+  "repository": {
+    "type": "git",
+    "url": "https://codeberg.org/oomfware/cgr"
+  },
+  "bin": {
+    "cgr": "./dist/index.mjs"
+  },
+  "files": [
+    "dist/",
+    "src/",
+    "!src/**/*.bench.ts",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@optique/core": "^0.9.1",
+    "@optique/run": "^0.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "bumpp": "^10.4.0",
+    "oxfmt": "^0.26.0",
+    "oxlint": "^1.41.0",
+    "tsdown": "^0.19.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "fmt": "oxfmt",
+    "lint": "oxlint"
+  }
+}

package/src/assets/settings.json

@@ -0,0 +1,48 @@
+{
+	"permissions": {
+		"allow": [
+			"Read",
+			"Glob",
+			"Grep",
+			"WebFetch",
+			"WebSearch",
+
+			"Bash(git blame:*)",
+			"Bash(git branch:*)",
+			"Bash(git checkout:*)",
+			"Bash(git diff:*)",
+			"Bash(git log:*)",
+			"Bash(git show:*)",
+			"Bash(git status:*)",
+			"Bash(git tag:*)",
+
+			"Bash(cat:*)",
+			"Bash(file:*)",
+			"Bash(find:*)",
+			"Bash(grep:*)",
+			"Bash(head:*)",
+			"Bash(ls:*)",
+			"Bash(stat:*)",
+			"Bash(tail:*)",
+			"Bash(tree:*)",
+			"Bash(wc:*)",
+
+			"Bash(awk:*)",
+			"Bash(cut:*)",
+			"Bash(diff:*)",
+			"Bash(jq:*)",
+			"Bash(sed:*)",
+			"Bash(sort:*)",
+			"Bash(tr:*)",
+			"Bash(uniq:*)",
+			"Bash(xargs:*)",
+
+			"Bash(basename:*)",
+			"Bash(dirname:*)",
+			"Bash(realpath:*)",
+
+			"Bash(du:*)"
+		],
+		"deny": ["*"]
+	}
+}

package/src/assets/system-prompt.md

@@ -0,0 +1,46 @@
+You are a code research assistant analyzing an external repository. Your goal is to answer the
+user's question accurately and thoroughly by exploring the codebase.
+
+## Available tools
+
+**File exploration:**
+
+- `Read` - Read file contents
+- `Glob` - Find files by pattern (e.g., `**/*.ts`, `src/**/*.test.js`)
+- `Grep` - Search file contents with regex
+
+**Git commands:**
+
+- `git log` - View commit history
+- `git show` - Inspect commits, files at specific revisions
+- `git diff` - Compare changes between commits/branches
+- `git blame` - See who changed each line and when
+- `git branch` - List branches
+- `git tag` - List tags
+- `git checkout` - Switch branches, tags, or view files at specific commits
+
+**External resources:**
+
+- `WebSearch` - Search the web for documentation, issues, discussions
+- `WebFetch` - Fetch specific URLs (docs, GitHub issues, etc.)
+
+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

package/src/commands/ask.ts

@@ -0,0 +1,104 @@
+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 { ensureRepo } from '../lib/git.ts';
+import { getRepoCachePath, normalizeRemote, parseRemote } from '../lib/paths.ts';
+
+// resolve asset paths relative to the bundle (dist/index.mjs -> dist/assets/)
+const assetsDir = join(import.meta.dirname, 'assets');
+const settingsPath = join(assetsDir, 'settings.json');
+const systemPromptPath = join(assetsDir, 'system-prompt.md');
+
+export const schema = object({
+	command: constant('ask'),
+	model: withDefault(
+		option('-m', '--model', choice(['opus', '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)`,
+	}),
+	question: argument(string({ metavar: 'QUESTION' }), {
+		description: message`question to ask about the repository`,
+	}),
+});
+
+export type Args = InferValue<typeof schema>;
+
+/**
+ * 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);
+	}
+
+	// get cache path
+	const cachePath = getRepoCachePath(args.remote);
+	if (!cachePath) {
+		console.error(`error: could not determine cache path for: ${args.remote}`);
+		process.exit(1);
+	}
+
+	// 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}`);
+		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',
+	});
+
+	claude.on('close', (code) => {
+		process.exit(code ?? 0);
+	});
+
+	claude.on('error', (err) => {
+		console.error(`error: failed to spawn claude: ${err}`);
+		process.exit(1);
+	});
+};

package/src/commands/clean.ts

@@ -0,0 +1,189 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import { join } from 'node:path';
+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';
+
+export const schema = object({
+	command: constant('clean'),
+	all: option('--all', { description: message`remove all cached repositories` }),
+	remote: optional(
+		argument(string({ metavar: 'URL' }), {
+			description: message`specific remote URL to clean`,
+		}),
+	),
+});
+
+export type Args = InferValue<typeof schema>;
+
+/**
+ * formats a byte size in human-readable form.
+ * @param bytes size in bytes
+ * @returns formatted string
+ */
+const formatSize = (bytes: number): string => {
+	if (bytes < 1024) {
+		return `${bytes} B`;
+	}
+	if (bytes < 1024 * 1024) {
+		return `${(bytes / 1024).toFixed(1)} KB`;
+	}
+	if (bytes < 1024 * 1024 * 1024) {
+		return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	}
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+};
+
+/**
+ * calculates the total size of a directory recursively.
+ * @param dir directory path
+ * @returns total size in bytes
+ */
+const getDirSize = (dir: string): number => {
+	let size = 0;
+	try {
+		const entries = readdirSync(dir, { withFileTypes: true });
+		for (const entry of entries) {
+			const fullPath = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				size += getDirSize(fullPath);
+			} else {
+				size += statSync(fullPath).size;
+			}
+		}
+	} catch {
+		// ignore errors (e.g., permission denied)
+	}
+	return size;
+};
+
+/**
+ * lists all cached repositories with their sizes.
+ * @returns array of { path, displayPath, size } objects
+ */
+const listCachedRepos = (): {
+	path: string;
+	displayPath: string;
+	size: number;
+}[] => {
+	const reposDir = getReposDir();
+	const repos: { path: string; displayPath: string; size: number }[] = [];
+
+	if (!existsSync(reposDir)) {
+		return repos;
+	}
+
+	// iterate hosts
+	for (const host of readdirSync(reposDir)) {
+		const hostPath = join(reposDir, host);
+		if (!statSync(hostPath).isDirectory()) {
+			continue;
+		}
+
+		// iterate owners
+		for (const owner of readdirSync(hostPath)) {
+			const ownerPath = join(hostPath, owner);
+			if (!statSync(ownerPath).isDirectory()) {
+				continue;
+			}
+
+			// iterate repos
+			for (const repo of readdirSync(ownerPath)) {
+				const repoPath = join(ownerPath, repo);
+				if (!statSync(repoPath).isDirectory()) {
+					continue;
+				}
+
+				repos.push({
+					path: repoPath,
+					displayPath: `${host}/${owner}/${repo}`,
+					size: getDirSize(repoPath),
+				});
+			}
+		}
+	}
+
+	return repos;
+};
+
+/**
+ * prompts the user for confirmation.
+ * @param msg the prompt message
+ * @returns promise that resolves to true if confirmed
+ */
+const confirm = (msg: string): Promise<boolean> =>
+	new Promise((resolve) => {
+		const rl = createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+		rl.question(`${msg} [y/N] `, (answer) => {
+			rl.close();
+			resolve(answer.toLowerCase() === 'y');
+		});
+	});
+
+/**
+ * handles the clean command.
+ * @param args parsed command arguments
+ */
+export const handler = async (args: Args): Promise<void> => {
+	const reposDir = getReposDir();
+
+	// clean all
+	if (args.all) {
+		if (!existsSync(reposDir)) {
+			console.log('no cached repositories found');
+			return;
+		}
+		const size = getDirSize(reposDir);
+		console.log(`removing all cached repositories (${formatSize(size)})`);
+		await rm(reposDir, { recursive: true });
+		console.log('done');
+		return;
+	}
+
+	// clean specific remote
+	if (args.remote) {
+		const cachePath = getRepoCachePath(args.remote);
+		if (!cachePath) {
+			console.error(`error: invalid remote URL: ${args.remote}`);
+			process.exit(1);
+		}
+		if (!existsSync(cachePath)) {
+			console.error(`error: repository not cached: ${args.remote}`);
+			process.exit(1);
+		}
+		const size = getDirSize(cachePath);
+		console.log(`removing ${cachePath} (${formatSize(size)})`);
+		await rm(cachePath, { recursive: true });
+		console.log('done');
+		return;
+	}
+
+	// list repos and prompt for confirmation
+	const repos = listCachedRepos();
+	if (repos.length === 0) {
+		console.log('no cached repositories 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;
+	}
+	console.log(`\n  total: ${formatSize(totalSize)}`);
+	console.log();
+
+	const confirmed = await confirm('remove all cached repositories?');
+	if (confirmed) {
+		await rm(reposDir, { recursive: true });
+		console.log('done');
+	}
+};

package/src/index.ts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { command, message, or } from '@optique/core';
+import { run } from '@optique/run';
+
+import * as ask from './commands/ask.ts';
+import * as clean from './commands/clean.ts';
+
+const parser = or(
+	command('ask', ask.schema, {
+		description: message`ask a question about a repository`,
+	}),
+	command('clean', clean.schema, {
+		description: message`remove cached repositories`,
+	}),
+);
+
+const result = run(parser, {
+	help: 'both',
+	version: { value: '0.1.0', mode: 'option' },
+	brief: message`ask questions about git repositories using Claude Code`,
+});
+
+switch (result.command) {
+	case 'ask':
+		await ask.handler(result);
+		break;
+	case 'clean':
+		await clean.handler(result);
+		break;
+}

package/src/lib/git.ts

@@ -0,0 +1,106 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+
+/**
+ * executes a git command and returns the result.
+ * @param args git command arguments
+ * @param cwd working directory
+ * @returns promise that resolves when the command completes
+ */
+const git = (args: string[], cwd?: string): Promise<void> =>
+	new Promise((resolve, reject) => {
+		const proc = spawn('git', args, {
+			cwd,
+			stdio: 'inherit',
+		});
+		proc.on('close', (code) => {
+			if (code === 0) {
+				resolve();
+			} else {
+				reject(new Error(`git ${args[0]} failed with code ${code}`));
+			}
+		});
+		proc.on('error', reject);
+	});
+
+/**
+ * executes a git command and captures stdout.
+ * @param args git command arguments
+ * @param cwd working directory
+ * @returns promise that resolves with stdout
+ */
+const gitOutput = (args: string[], cwd?: string): Promise<string> =>
+	new Promise((resolve, reject) => {
+		const proc = spawn('git', args, {
+			cwd,
+			stdio: ['inherit', 'pipe', 'inherit'],
+		});
+		let output = '';
+		proc.stdout!.on('data', (data: Buffer) => {
+			output += data.toString();
+		});
+		proc.on('close', (code) => {
+			if (code === 0) {
+				resolve(output.trim());
+			} else {
+				reject(new Error(`git ${args[0]} failed with code ${code}`));
+			}
+		});
+		proc.on('error', reject);
+	});
+
+/**
+ * clones a repository to the cache path.
+ * @param remote the remote URL
+ * @param cachePath the local cache path
+ * @param branch optional branch to checkout
+ */
+export const cloneRepo = async (remote: string, cachePath: string, branch?: string): Promise<void> => {
+	await mkdir(dirname(cachePath), { recursive: true });
+	const args = ['clone'];
+	if (branch) {
+		args.push('--branch', branch);
+	}
+	args.push(remote, cachePath);
+	await git(args);
+};
+
+/**
+ * updates an existing repository in the cache.
+ * discards any local modifications, staged changes, and untracked files.
+ * @param cachePath the local cache path
+ * @param branch optional branch to checkout (uses default branch if not specified)
+ */
+export const updateRepo = async (cachePath: string, branch?: string): Promise<void> => {
+	await git(['fetch', 'origin'], cachePath);
+
+	// determine the branch to use
+	let targetBranch = branch;
+	if (!targetBranch) {
+		// get the default branch from origin
+		const defaultRef = await gitOutput(['symbolic-ref', 'refs/remotes/origin/HEAD'], cachePath);
+		targetBranch = defaultRef.replace('refs/remotes/origin/', '');
+	}
+
+	// discard all local changes before checkout to avoid conflicts
+	await git(['reset', '--hard', 'HEAD'], cachePath);
+	await git(['clean', '-fd'], cachePath);
+	await git(['checkout', '-f', targetBranch], cachePath);
+	await git(['reset', '--hard', `origin/${targetBranch}`], cachePath);
+};
+
+/**
+ * ensures a repository is cloned and up-to-date.
+ * @param remote the remote URL
+ * @param cachePath the local cache path
+ * @param branch optional branch to checkout
+ */
+export const ensureRepo = async (remote: string, cachePath: string, branch?: string): Promise<void> => {
+	if (existsSync(cachePath)) {
+		await updateRepo(cachePath, branch);
+	} else {
+		await cloneRepo(remote, cachePath, branch);
+	}
+};

package/src/lib/paths.ts

@@ -0,0 +1,92 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * returns the cache directory for cgr.
+ * uses `$XDG_CACHE_HOME/cgr` if set, otherwise falls back to:
+ * - `~/.cache/cgr` on linux
+ * - `~/Library/Caches/cgr` on macos
+ * @returns the cache directory path
+ */
+export const getCacheDir = (): string => {
+	const xdgCache = process.env['XDG_CACHE_HOME'];
+	if (xdgCache) {
+		return join(xdgCache, 'cgr');
+	}
+	const home = homedir();
+	if (process.platform === 'darwin') {
+		return join(home, 'Library', 'Caches', 'cgr');
+	}
+	return join(home, '.cache', 'cgr');
+};
+
+/**
+ * returns the repos directory within the cache.
+ * @returns the repos directory path
+ */
+export const getReposDir = (): string => join(getCacheDir(), 'repos');
+
+/**
+ * parses a git remote URL and extracts host, owner, and repo.
+ * supports HTTP(S), SSH, and bare URLs (assumes HTTPS).
+ * @param remote the remote URL to parse
+ * @returns parsed components or null if invalid
+ */
+export const parseRemote = (remote: string): { host: string; owner: string; repo: string } | null => {
+	// HTTP(S): https://github.com/user/repo or https://github.com/user/repo.git
+	const httpMatch = remote.match(/^https?:\/\/([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+	if (httpMatch) {
+		return {
+			host: httpMatch[1]!,
+			owner: httpMatch[2]!,
+			repo: httpMatch[3]!,
+		};
+	}
+
+	// SSH: git@github.com:user/repo.git or git@github.com:user/repo
+	const sshMatch = remote.match(/^git@([^:]+):([^/]+)\/([^/]+?)(?:\.git)?$/);
+	if (sshMatch) {
+		return {
+			host: sshMatch[1]!,
+			owner: sshMatch[2]!,
+			repo: sshMatch[3]!,
+		};
+	}
+
+	// bare URL: github.com/user/repo (assumes HTTPS)
+	const bareMatch = remote.match(/^([^/]+)\/([^/]+)\/([^/]+?)(?:\.git)?$/);
+	if (bareMatch) {
+		return {
+			host: bareMatch[1]!,
+			owner: bareMatch[2]!,
+			repo: bareMatch[3]!,
+		};
+	}
+
+	return null;
+};
+
+/**
+ * normalizes a remote URL by prepending https:// if no protocol is present.
+ * @param remote the remote URL to normalize
+ * @returns normalized URL with protocol
+ */
+export const normalizeRemote = (remote: string): string => {
+	if (remote.startsWith('https://') || remote.startsWith('http://') || remote.startsWith('git@')) {
+		return remote;
+	}
+	return `https://${remote}`;
+};
+
+/**
+ * returns the cache path for a specific repository.
+ * @param remote the remote URL
+ * @returns the cache path or null if the remote URL is invalid
+ */
+export const getRepoCachePath = (remote: string): string | null => {
+	const parsed = parseRemote(remote);
+	if (!parsed) {
+		return null;
+	}
+	return join(getReposDir(), parsed.host, parsed.owner, parsed.repo);
+};