Add local repo mode with session branches

Adds `--repo <url> --pat <token>` to auto-clone a GitHub repo locally,
create a session branch (gitclaw/session-<id>), run the agent, auto-commit
changes, and push the session branch. Supports resuming sessions via
`--session <branch>`. Works for both CLI and SDK (`query({ repo: {...} })`).

- New: src/session.ts — session lifecycle (clone, branch, commit, push, finalize)
- Modified: src/sdk-types.ts — LocalRepoOptions type, repo field on QueryOptions
- Modified: src/index.ts — --repo, --pat, --session CLI flags with finalize on exit
- Modified: src/sdk.ts — repo option support with finalize on success/error
- Modified: src/exports.ts — export LocalRepoOptions, LocalSession, initLocalSession
- New: examples/local-repo.ts — SDK usage example

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: shreyas-lyzr

examples/local-repo.ts

@@ -0,0 +1,56 @@
+import { query } from "../dist/exports.js";
+
+/**
+ * Local Repo Mode — clone a GitHub repo, run an agent on it,
+ * auto-commit changes, and push to a session branch.
+ *
+ * Usage:
+ *   GITHUB_TOKEN=ghp_xxx npx tsx examples/local-repo.ts
+ */
+
+const REPO_URL = "https://github.com/shreyas-lyzr/agent-designer";
+const TOKEN = process.env.GITHUB_TOKEN || process.env.GIT_TOKEN || "";
+
+if (!TOKEN) {
+	console.error("Set GITHUB_TOKEN or GIT_TOKEN env var");
+	process.exit(1);
+}
+
+async function main() {
+	console.log("Starting local repo session...\n");
+
+	const stream = query({
+		prompt: "Read the README and summarize what this project does.",
+		model: "openai:gpt-4o-mini",
+		repo: {
+			url: REPO_URL,
+			token: TOKEN,
+			// dir: "/tmp/my-custom-dir",  // optional — defaults to cwd
+			// session: "gitclaw/session-abc123",  // resume an existing session
+		},
+	});
+
+	for await (const msg of stream) {
+		switch (msg.type) {
+			case "delta":
+				process.stdout.write(msg.content);
+				break;
+			case "assistant":
+				console.log(`\n\n[done] model=${msg.model} tokens=${msg.usage?.totalTokens}`);
+				break;
+			case "tool_use":
+				console.log(`\n[tool_use] ${msg.toolName}(${JSON.stringify(msg.args)})`);
+				break;
+			case "tool_result":
+				console.log(`[tool_result] ${msg.content.slice(0, 200)}`);
+				break;
+			case "system":
+				console.log(`[${msg.subtype}] ${msg.content}`);
+				break;
+		}
+	}
+
+	console.log("\nSession complete — changes committed and pushed to session branch.");
+}
+
+main().catch(console.error);

package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitclaw",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A universal git-native agent powered by pi-agent-core",
   "type": "module",
   "main": "./dist/exports.js",

src/exports.ts

@@ -5,6 +5,7 @@ export { query, tool } from "./sdk.js";
 export type {
 	Query,
 	QueryOptions,
+	LocalRepoOptions,
 	SandboxOptions,
 	GCMessage,
 	GCAssistantMessage,
@@ -32,5 +33,9 @@ export type { EnvConfig } from "./config.js";
 export type { SandboxConfig, SandboxContext } from "./sandbox.js";
 export { createSandboxContext } from "./sandbox.js";
 
+// Session
+export type { LocalSession } from "./session.js";
+export { initLocalSession } from "./session.js";
+
 // Loader (escape hatch)
 export { loadAgent } from "./loader.js";

src/index.ts

@@ -16,6 +16,8 @@ import { formatComplianceWarnings } from "./compliance.js";
 import { readFile, mkdir, writeFile, stat, access } from "fs/promises";
 import { join, resolve } from "path";
 import { execSync } from "child_process";
+import { initLocalSession } from "./session.js";
+import type { LocalSession } from "./session.js";
 
 // ANSI helpers
 const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
@@ -31,6 +33,9 @@ interface ParsedArgs {
 	sandbox?: boolean;
 	sandboxRepo?: string;
 	sandboxToken?: string;
+	repo?: string;
+	pat?: string;
+	session?: string;
 }
 
 function parseArgs(argv: string[]): ParsedArgs {
@@ -42,6 +47,9 @@ function parseArgs(argv: string[]): ParsedArgs {
 	let sandbox = false;
 	let sandboxRepo: string | undefined;
 	let sandboxToken: string | undefined;
+	let repo: string | undefined;
+	let pat: string | undefined;
+	let session: string | undefined;
 
 	for (let i = 0; i < args.length; i++) {
 		switch (args[i]) {
@@ -71,6 +79,16 @@ function parseArgs(argv: string[]): ParsedArgs {
 			case "--sandbox-token":
 				sandboxToken = args[++i];
 				break;
+			case "--repo":
+			case "-r":
+				repo = args[++i];
+				break;
+			case "--pat":
+				pat = args[++i];
+				break;
+			case "--session":
+				session = args[++i];
+				break;
 			default:
 				if (!args[i].startsWith("-")) {
 					prompt = args[i];
@@ -79,7 +97,7 @@ function parseArgs(argv: string[]): ParsedArgs {
 		}
 	}
 
-	return { model, dir, prompt, env, sandbox, sandboxRepo, sandboxToken };
+	return { model, dir, prompt, env, sandbox, sandboxRepo, sandboxToken, repo, pat, session };
 }
 
 function handleEvent(
@@ -257,11 +275,41 @@ async function ensureRepo(dir: string, model?: string): Promise<string> {
 }
 
 async function main(): Promise<void> {
-	const { model, dir: rawDir, prompt, env, sandbox: useSandbox, sandboxRepo, sandboxToken } = parseArgs(process.argv);
+	const { model, dir: rawDir, prompt, env, sandbox: useSandbox, sandboxRepo, sandboxToken, repo, pat, session: sessionBranch } = parseArgs(process.argv);
 
-	// If no --dir given interactively, ask for it
+	// If --repo is given, derive a default dir from the repo URL (skip interactive prompt)
 	let dir = rawDir;
-	if (dir === process.cwd() && !prompt) {
+	let localSession: LocalSession | undefined;
+
+	if (repo) {
+		// Validate mutually exclusive flags
+		if (useSandbox) {
+			console.error(red("Error: --repo and --sandbox are mutually exclusive"));
+			process.exit(1);
+		}
+
+		const token = pat || process.env.GITHUB_TOKEN || process.env.GIT_TOKEN;
+		if (!token) {
+			console.error(red("Error: --pat, GITHUB_TOKEN, or GIT_TOKEN is required with --repo"));
+			process.exit(1);
+		}
+
+		// Default dir: /tmp/gitclaw/<repo-name> if no --dir given
+		if (dir === process.cwd()) {
+			const repoName = repo.split("/").pop()?.replace(/\.git$/, "") || "repo";
+			dir = resolve(`/tmp/gitclaw/${repoName}`);
+		}
+
+		localSession = initLocalSession({
+			url: repo,
+			token,
+			dir,
+			session: sessionBranch,
+		});
+		dir = localSession.dir;
+		console.log(dim(`Local session: ${localSession.branch} (${localSession.dir})`));
+	} else if (dir === process.cwd() && !prompt) {
+		// No --repo: interactive prompt for dir
 		const answer = await askQuestion(green("? ") + bold("Repository path") + dim(" (. for current dir)") + green(": "));
 		if (answer) {
 			dir = resolve(answer === "." ? process.cwd() : answer);
@@ -282,8 +330,10 @@ async function main(): Promise<void> {
 		console.log(dim(`Sandbox ready (repo: ${sandboxCtx.repoPath})`));
 	}
 
-	// Ensure the target is a valid gitclaw repo (skip in sandbox mode — gitmachine clones the repo)
-	if (!useSandbox) {
+	// Ensure the target is a valid gitclaw repo (skip in sandbox/local-repo mode)
+	if (localSession) {
+		// Already cloned and scaffolded by initLocalSession
+	} else if (!useSandbox) {
 		dir = await ensureRepo(dir, model);
 	} else {
 		dir = resolve(dir);
@@ -420,6 +470,10 @@ async function main(): Promise<void> {
 			}
 			throw err;
 		} finally {
+			if (localSession) {
+				console.log(dim("Finalizing session..."));
+				localSession.finalize();
+			}
 			if (sandboxCtx) {
 				console.log(dim("Stopping sandbox..."));
 				await sandboxCtx.gitMachine.stop();
@@ -445,6 +499,10 @@ async function main(): Promise<void> {
 
 			if (trimmed === "/quit" || trimmed === "/exit") {
 				rl.close();
+				if (localSession) {
+					console.log(dim("Finalizing session..."));
+					localSession.finalize();
+				}
 				await stopSandbox();
 				process.exit(0);
 			}
@@ -523,6 +581,9 @@ async function main(): Promise<void> {
 		} else {
 			console.log("\nBye!");
 			rl.close();
+			if (localSession) {
+				try { localSession.finalize(); } catch { /* best-effort */ }
+			}
 			stopSandbox().finally(() => process.exit(0));
 		}
 	});

src/sdk-types.ts

@@ -100,6 +100,15 @@ export interface GCToolDefinition {
 	handler: (args: any, signal?: AbortSignal) => Promise<string | { text: string; details?: any }>;
 }
 
+// ── Local repo options ──────────────────────────────────────────────────
+
+export interface LocalRepoOptions {
+	url: string;
+	token: string;
+	dir?: string;
+	session?: string;
+}
+
 // ── Sandbox options ─────────────────────────────────────────────────────
 
 export interface SandboxOptions {
@@ -126,6 +135,7 @@ export interface QueryOptions {
 	replaceBuiltinTools?: boolean;
 	allowedTools?: string[];
 	disallowedTools?: string[];
+	repo?: LocalRepoOptions;
 	sandbox?: SandboxOptions | boolean;
 	hooks?: GCHooks;
 	maxTurns?: number;

src/sdk.ts

@@ -10,6 +10,8 @@ import { loadHooksConfig, runHooks, wrapToolWithHooks } from "./hooks.js";
 import { loadDeclarativeTools } from "./tool-loader.js";
 import { buildTypeboxSchema } from "./tool-loader.js";
 import { wrapToolWithProgrammaticHooks } from "./sdk-hooks.js";
+import { initLocalSession } from "./session.js";
+import type { LocalSession } from "./session.js";
 import type {
 	GCMessage,
 	GCAssistantMessage,
@@ -120,10 +122,32 @@ export function query(options: QueryOptions): Query {
 
 	// Sandbox context (hoisted for cleanup in catch)
 	let sandboxCtx: SandboxContext | undefined;
+	// Local session (hoisted for cleanup in catch)
+	let localSession: LocalSession | undefined;
 
 	// Async initialization + run
 	const runPromise = (async () => {
-		const dir = options.dir ?? process.cwd();
+		// Validate mutually exclusive options
+		if (options.repo && options.sandbox) {
+			throw new Error("repo and sandbox options are mutually exclusive");
+		}
+
+		let dir = options.dir ?? process.cwd();
+
+		// Local repo mode
+		if (options.repo) {
+			const token = options.repo.token || process.env.GITHUB_TOKEN || process.env.GIT_TOKEN;
+			if (!token) {
+				throw new Error("repo.token, GITHUB_TOKEN, or GIT_TOKEN is required with repo option");
+			}
+			localSession = initLocalSession({
+				url: options.repo.url,
+				token,
+				dir: options.repo.dir || dir,
+				session: options.repo.session,
+			});
+			dir = localSession.dir;
+		}
 
 		// 1. Load agent
 		const loaded = await loadAgent(dir, options.model, options.env);
@@ -397,6 +421,11 @@ export function query(options: QueryOptions): Query {
 			}
 		}
 
+		// Finalize local session if active
+		if (localSession) {
+			try { localSession.finalize(); } catch { /* best-effort */ }
+		}
+
 		// Stop sandbox if active
 		if (sandboxCtx) {
 			await sandboxCtx.gitMachine.stop().catch(() => {});
@@ -405,6 +434,11 @@ export function query(options: QueryOptions): Query {
 		// Ensure channel finishes even if no agent_end event
 		channel.finish();
 	})().catch(async (err) => {
+		// Finalize local session on error
+		if (localSession) {
+			try { localSession.finalize(); } catch { /* best-effort */ }
+		}
+
 		// Stop sandbox on error
 		if (sandboxCtx) {
 			await sandboxCtx.gitMachine.stop().catch(() => {});