@residue/cli 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# @residue/cli
+
+## 0.0.3
+
+### Patch Changes
+
+- Add status command, common workflows docs, versioning policy.
+
+## 0.0.2
+
+### Patch Changes
+
+- Add per-project login support with `--local` flag. Running `residue login --local` saves config to `.residue/config` in the project root instead of the global `~/.residue/config`. The sync command now resolves config locally first before falling back to global.
+
+## 0.0.1
+
+### Features
+
+- Initial release
+- `residue login` to save worker URL and auth token
+- `residue init` to install git hooks (post-commit, pre-push)
+- `residue setup` for agent adapters (claude-code, pi)
+- `residue capture` for post-commit session tagging
+- `residue sync` for pre-push session upload via presigned R2 URLs
+- `residue push` as manual sync alias
+- `residue session start` and `residue session end` for agent adapters
+- `residue hook claude-code` for Claude Code native hook protocol
+- Claude Code and Pi agent adapters

package/README.md

@@ -0,0 +1,44 @@
+# @residue/cli
+
+CLI that captures AI agent conversations and links them to git commits.
+
+Part of [residue](https://residue.dev) -- see the full docs at [residue.dev](https://residue.dev).
+
+## Install
+
+```bash
+bun add -g @residue/cli
+```
+
+## Quick Start
+
+```bash
+# Save your worker URL and auth token
+residue login --url https://your-worker.workers.dev --token YOUR_TOKEN
+
+# Install git hooks in your repo
+residue init
+
+# Set up an agent adapter
+residue setup claude-code    # for Claude Code
+residue setup pi             # for pi coding agent
+```
+
+After setup, conversations are captured automatically. Commit and push as usual.
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `residue login` | Save worker URL + auth token |
+| `residue init` | Install git hooks (post-commit, pre-push) |
+| `residue setup <agent>` | Configure an agent adapter |
+| `residue push` | Manually upload pending sessions |
+| `residue capture` | Tag pending sessions with current commit (hook) |
+| `residue sync` | Upload sessions to worker (hook) |
+| `residue session start` | Register a new session (adapter) |
+| `residue session end` | Mark a session as ended (adapter) |
+
+## License
+
+MIT

package/dist/index.js

@@ -3895,10 +3895,9 @@ function getConfigDir() {
 function getConfigPath() {
   return join4(getConfigDir(), "config");
 }
-function readConfig() {
+function readConfigFromPath(configPath) {
   return ResultAsync.fromPromise((async () => {
-    const path = getConfigPath();
-    const file = Bun.file(path);
+    const file = Bun.file(configPath);
     const isExists = await file.exists();
     if (!isExists)
       return null;
@@ -3906,13 +3905,36 @@ function readConfig() {
     return JSON.parse(text);
   })(), toCliError({ message: "Failed to read config", code: "CONFIG_ERROR" }));
 }
-function writeConfig(config) {
+function writeConfigToPath(opts) {
   return ResultAsync.fromPromise((async () => {
-    const dir = getConfigDir();
+    const dir = join4(opts.configPath, "..");
     await mkdir4(dir, { recursive: true });
-    await Bun.write(getConfigPath(), JSON.stringify(config, null, 2));
+    await Bun.write(opts.configPath, JSON.stringify(opts.config, null, 2));
   })(), toCliError({ message: "Failed to write config", code: "CONFIG_ERROR" }));
 }
+function readConfig() {
+  return readConfigFromPath(getConfigPath());
+}
+function writeConfig(config) {
+  return writeConfigToPath({ configPath: getConfigPath(), config });
+}
+function readLocalConfig(projectRoot) {
+  return readConfigFromPath(join4(projectRoot, ".residue", "config"));
+}
+function writeLocalConfig(opts) {
+  return writeConfigToPath({
+    configPath: join4(opts.projectRoot, ".residue", "config"),
+    config: opts.config
+  });
+}
+function resolveConfig() {
+  return getProjectRoot().andThen((projectRoot) => readLocalConfig(projectRoot)).orElse(() => okAsync(null)).andThen((localConfig) => {
+    if (localConfig !== null) {
+      return okAsync(localConfig);
+    }
+    return readConfig();
+  });
+}
 
 // src/commands/login.ts
 var log4 = createLogger("login");
@@ -3924,7 +3946,13 @@ function login(opts) {
     }));
   }
   const cleanUrl = opts.url.replace(/\/+$/, "");
-  return writeConfig({ worker_url: cleanUrl, token: opts.token }).map(() => {
+  const config = { worker_url: cleanUrl, token: opts.token };
+  if (opts.isLocal) {
+    return getProjectRoot().andThen((projectRoot) => writeLocalConfig({ projectRoot, config }).map(() => {
+      log4.info(`Logged in to ${cleanUrl} (project-local config)`);
+    }));
+  }
+  return writeConfig(config).map(() => {
     log4.info(`Logged in to ${cleanUrl}`);
   });
 }
@@ -4117,7 +4145,7 @@ function resolveRemote(remoteUrl) {
 }
 function sync(opts) {
   return safeTry(async function* () {
-    const config = yield* readConfig();
+    const config = yield* resolveConfig();
     if (!config) {
       return err(new CliError({
         message: "Not configured. Run 'residue login' first.",
@@ -4422,10 +4450,145 @@ function setup(opts) {
   });
 }
 
+// src/commands/status.ts
+import { readFile as readFile4, stat as stat5 } from "fs/promises";
+import { join as join6 } from "path";
+var log9 = createLogger("status");
+function checkFileExists(path) {
+  return ResultAsync.fromPromise(stat5(path).then(() => true), toCliError({ message: "Failed to check file", code: "IO_ERROR" })).orElse(() => okAsync(false));
+}
+function checkHookInstalled(opts) {
+  const hookPath = join6(opts.gitDir, "hooks", opts.hookName);
+  return ResultAsync.fromPromise(readFile4(hookPath, "utf-8").then((content) => content.includes(opts.needle)), toCliError({ message: "Failed to read hook", code: "IO_ERROR" })).orElse(() => okAsync(false));
+}
+function getGitDir() {
+  return ResultAsync.fromPromise((async () => {
+    const proc = Bun.spawn(["git", "rev-parse", "--git-dir"], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    await proc.exited;
+    return (await new Response(proc.stdout).text()).trim();
+  })(), toCliError({ message: "Failed to get git directory", code: "GIT_ERROR" }));
+}
+function status() {
+  return safeTry(async function* () {
+    const isRepo = yield* isGitRepo();
+    if (!isRepo) {
+      log9.info("Not a git repository.");
+      return ok(undefined);
+    }
+    const projectRoot = yield* getProjectRoot();
+    log9.info("Login");
+    const globalConfig = yield* readConfig();
+    if (globalConfig) {
+      log9.info(`  global: ${globalConfig.worker_url}`);
+    } else {
+      log9.info("  global: not configured");
+    }
+    const localConfig = yield* readLocalConfig(projectRoot);
+    if (localConfig) {
+      log9.info(`  local:  ${localConfig.worker_url}`);
+    } else {
+      log9.info("  local:  not configured");
+    }
+    const isActiveConfig = localConfig ?? globalConfig;
+    if (isActiveConfig) {
+      log9.info(`  active: ${isActiveConfig.worker_url}`);
+    } else {
+      log9.info('  active: none (run "residue login" to configure)');
+    }
+    log9.info("");
+    log9.info("Hooks");
+    const gitDir = yield* getGitDir();
+    const isPostCommitInstalled = yield* checkHookInstalled({
+      gitDir,
+      hookName: "post-commit",
+      needle: "residue capture"
+    });
+    log9.info(`  post-commit: ${isPostCommitInstalled ? "installed" : "not installed"}`);
+    const isPrePushInstalled = yield* checkHookInstalled({
+      gitDir,
+      hookName: "pre-push",
+      needle: "residue sync"
+    });
+    log9.info(`  pre-push:    ${isPrePushInstalled ? "installed" : "not installed"}`);
+    if (!isPostCommitInstalled || !isPrePushInstalled) {
+      log9.info('  run "residue init" to install missing hooks');
+    }
+    log9.info("");
+    log9.info("Adapters");
+    const isClaudeSetup = yield* checkFileExists(join6(projectRoot, ".claude", "settings.json"));
+    let isClaudeHookConfigured = false;
+    if (isClaudeSetup) {
+      isClaudeHookConfigured = yield* ResultAsync.fromPromise(readFile4(join6(projectRoot, ".claude", "settings.json"), "utf-8").then((content) => content.includes("residue hook claude-code")), toCliError({
+        message: "Failed to read claude settings",
+        code: "IO_ERROR"
+      })).orElse(() => okAsync(false));
+    }
+    log9.info(`  claude-code: ${isClaudeHookConfigured ? "configured" : "not configured"}`);
+    const isPiSetup = yield* checkFileExists(join6(projectRoot, ".pi", "extensions", "residue.ts"));
+    log9.info(`  pi:          ${isPiSetup ? "configured" : "not configured"}`);
+    log9.info("");
+    log9.info("Sessions");
+    const pendingPath = yield* getPendingPath(projectRoot);
+    const sessions = yield* readPending(pendingPath);
+    if (sessions.length === 0) {
+      log9.info("  no pending sessions");
+    } else {
+      const openSessions = sessions.filter((s) => s.status === "open");
+      const endedSessions = sessions.filter((s) => s.status === "ended");
+      const totalCommits = sessions.reduce((sum, s) => sum + s.commits.length, 0);
+      const sessionsWithCommits = sessions.filter((s) => s.commits.length > 0);
+      log9.info(`  total:   ${sessions.length}`);
+      log9.info(`  open:    ${openSessions.length}`);
+      log9.info(`  ended:   ${endedSessions.length}`);
+      log9.info(`  commits: ${totalCommits} across ${sessionsWithCommits.length} session(s)`);
+      const isReadyToSync = sessionsWithCommits.length > 0;
+      if (isReadyToSync) {
+        log9.info(`  ${sessionsWithCommits.length} session(s) ready to sync on next push`);
+      } else {
+        log9.info("  no sessions ready to sync (no commits captured yet)");
+      }
+    }
+    return ok(undefined);
+  });
+}
+// package.json
+var package_default = {
+  name: "@residue/cli",
+  version: "0.0.3",
+  repository: {
+    type: "git",
+    url: "https://github.com/butttons/residue",
+    directory: "packages/cli"
+  },
+  type: "module",
+  bin: {
+    residue: "./dist/index.js"
+  },
+  scripts: {
+    dev: "bun run src/index.ts",
+    build: "bun build src/index.ts --outfile dist/index.js --target bun",
+    test: "bun test",
+    typecheck: "tsc --noEmit"
+  },
+  devDependencies: {
+    "@types/bun": "latest",
+    "@types/debug": "^4.1.12",
+    typescript: "^5.7.0"
+  },
+  dependencies: {
+    commander: "^14.0.3",
+    debug: "^4.4.3",
+    neverthrow: "^8.2.0"
+  }
+};
+
 // src/index.ts
 var program2 = new Command;
-program2.name("residue").description("Capture AI agent conversations linked to git commits").version("0.0.1");
-program2.command("login").description("Save worker URL and auth token").requiredOption("--url <worker_url>", "Worker URL").requiredOption("--token <auth_token>", "Auth token").action(wrapCommand((opts) => login({ url: opts.url, token: opts.token })));
+program2.name("residue").description("Capture AI agent conversations linked to git commits").version(package_default.version);
+program2.command("login").description("Save worker URL and auth token").requiredOption("--url <worker_url>", "Worker URL").requiredOption("--token <auth_token>", "Auth token").option("--local", "Save config to this project instead of globally").action(wrapCommand((opts) => login({ url: opts.url, token: opts.token, isLocal: opts.local })));
 program2.command("init").description("Install git hooks in current repo").action(wrapCommand(() => init()));
 program2.command("setup").description("Configure an agent adapter for this project").argument("<agent>", "Agent to set up (claude-code, pi)").action(wrapCommand((agent) => setup({ agent })));
 var hook = program2.command("hook").description("Agent hook handlers (called by agent plugins)");
@@ -4440,4 +4603,5 @@ session.command("end").description("Mark an agent session as ended").requiredOpt
 program2.command("capture").description("Tag pending sessions with current commit SHA (called by post-commit hook)").action(wrapHookCommand(() => capture()));
 program2.command("sync").description("Upload pending sessions to worker (called by pre-push hook)").option("--remote-url <url>", "Remote URL (passed by pre-push hook)").action(wrapHookCommand((opts) => sync({ remoteUrl: opts.remoteUrl })));
 program2.command("push").description("Upload pending sessions to worker (manual trigger)").action(wrapCommand(() => push()));
+program2.command("status").description("Show current residue state for this project").action(wrapCommand(() => status()));
 program2.parse();

package/package.json

@@ -1,6 +1,11 @@
 {
 	"name": "@residue/cli",
-	"version": "0.0.1",
+	"version": "0.0.3",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/butttons/residue",
+		"directory": "packages/cli"
+	},
 	"type": "module",
 	"bin": {
 		"residue": "./dist/index.js"

package/src/commands/login.ts

@@ -1,5 +1,6 @@
 import { errAsync, type ResultAsync } from "neverthrow";
-import { writeConfig } from "@/lib/config";
+import { writeConfig, writeLocalConfig } from "@/lib/config";
+import { getProjectRoot } from "@/lib/pending";
 import { CliError } from "@/utils/errors";
 import { createLogger } from "@/utils/logger";
 
@@ -8,6 +9,7 @@ const log = createLogger("login");
 export function login(opts: {
 	url: string;
 	token: string;
+	isLocal?: boolean;
 }): ResultAsync<void, CliError> {
 	if (!opts.url.startsWith("http://") && !opts.url.startsWith("https://")) {
 		return errAsync(
@@ -19,8 +21,17 @@ export function login(opts: {
 	}
 
 	const cleanUrl = opts.url.replace(/\/+$/, "");
+	const config = { worker_url: cleanUrl, token: opts.token };
 
-	return writeConfig({ worker_url: cleanUrl, token: opts.token }).map(() => {
+	if (opts.isLocal) {
+		return getProjectRoot().andThen((projectRoot) =>
+			writeLocalConfig({ projectRoot, config }).map(() => {
+				log.info(`Logged in to ${cleanUrl} (project-local config)`);
+			}),
+		);
+	}
+
+	return writeConfig(config).map(() => {
 		log.info(`Logged in to ${cleanUrl}`);
 	});
 }

package/src/commands/status.ts

@@ -0,0 +1,180 @@
+import { readFile, stat } from "fs/promises";
+import { ok, okAsync, ResultAsync, safeTry } from "neverthrow";
+import { join } from "path";
+import { readConfig, readLocalConfig } from "@/lib/config";
+import { isGitRepo } from "@/lib/git";
+import { getPendingPath, getProjectRoot, readPending } from "@/lib/pending";
+import type { CliError } from "@/utils/errors";
+import { toCliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("status");
+
+function checkFileExists(path: string): ResultAsync<boolean, CliError> {
+	return ResultAsync.fromPromise(
+		stat(path).then(() => true),
+		toCliError({ message: "Failed to check file", code: "IO_ERROR" }),
+	).orElse(() => okAsync(false));
+}
+
+function checkHookInstalled(opts: {
+	gitDir: string;
+	hookName: string;
+	needle: string;
+}): ResultAsync<boolean, CliError> {
+	const hookPath = join(opts.gitDir, "hooks", opts.hookName);
+	return ResultAsync.fromPromise(
+		readFile(hookPath, "utf-8").then((content) =>
+			content.includes(opts.needle),
+		),
+		toCliError({ message: "Failed to read hook", code: "IO_ERROR" }),
+	).orElse(() => okAsync(false));
+}
+
+function getGitDir(): ResultAsync<string, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const proc = Bun.spawn(["git", "rev-parse", "--git-dir"], {
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			await proc.exited;
+			return (await new Response(proc.stdout).text()).trim();
+		})(),
+		toCliError({ message: "Failed to get git directory", code: "GIT_ERROR" }),
+	);
+}
+
+export function status(): ResultAsync<void, CliError> {
+	return safeTry(async function* () {
+		const isRepo = yield* isGitRepo();
+		if (!isRepo) {
+			log.info("Not a git repository.");
+			return ok(undefined);
+		}
+
+		const projectRoot = yield* getProjectRoot();
+
+		// -- Auth / Login state --
+		log.info("Login");
+
+		const globalConfig = yield* readConfig();
+		if (globalConfig) {
+			log.info(`  global: ${globalConfig.worker_url}`);
+		} else {
+			log.info("  global: not configured");
+		}
+
+		const localConfig = yield* readLocalConfig(projectRoot);
+		if (localConfig) {
+			log.info(`  local:  ${localConfig.worker_url}`);
+		} else {
+			log.info("  local:  not configured");
+		}
+
+		const isActiveConfig = localConfig ?? globalConfig;
+		if (isActiveConfig) {
+			log.info(`  active: ${isActiveConfig.worker_url}`);
+		} else {
+			log.info('  active: none (run "residue login" to configure)');
+		}
+
+		log.info("");
+
+		// -- Git hooks --
+		log.info("Hooks");
+
+		const gitDir = yield* getGitDir();
+
+		const isPostCommitInstalled = yield* checkHookInstalled({
+			gitDir,
+			hookName: "post-commit",
+			needle: "residue capture",
+		});
+		log.info(
+			`  post-commit: ${isPostCommitInstalled ? "installed" : "not installed"}`,
+		);
+
+		const isPrePushInstalled = yield* checkHookInstalled({
+			gitDir,
+			hookName: "pre-push",
+			needle: "residue sync",
+		});
+		log.info(
+			`  pre-push:    ${isPrePushInstalled ? "installed" : "not installed"}`,
+		);
+
+		if (!isPostCommitInstalled || !isPrePushInstalled) {
+			log.info('  run "residue init" to install missing hooks');
+		}
+
+		log.info("");
+
+		// -- Agent adapters --
+		log.info("Adapters");
+
+		const isClaudeSetup = yield* checkFileExists(
+			join(projectRoot, ".claude", "settings.json"),
+		);
+
+		let isClaudeHookConfigured = false;
+		if (isClaudeSetup) {
+			isClaudeHookConfigured = yield* ResultAsync.fromPromise(
+				readFile(join(projectRoot, ".claude", "settings.json"), "utf-8").then(
+					(content) => content.includes("residue hook claude-code"),
+				),
+				toCliError({
+					message: "Failed to read claude settings",
+					code: "IO_ERROR",
+				}),
+			).orElse(() => okAsync(false));
+		}
+
+		log.info(
+			`  claude-code: ${isClaudeHookConfigured ? "configured" : "not configured"}`,
+		);
+
+		const isPiSetup = yield* checkFileExists(
+			join(projectRoot, ".pi", "extensions", "residue.ts"),
+		);
+		log.info(`  pi:          ${isPiSetup ? "configured" : "not configured"}`);
+
+		log.info("");
+
+		// -- Pending sessions --
+		log.info("Sessions");
+
+		const pendingPath = yield* getPendingPath(projectRoot);
+		const sessions = yield* readPending(pendingPath);
+
+		if (sessions.length === 0) {
+			log.info("  no pending sessions");
+		} else {
+			const openSessions = sessions.filter((s) => s.status === "open");
+			const endedSessions = sessions.filter((s) => s.status === "ended");
+			const totalCommits = sessions.reduce(
+				(sum, s) => sum + s.commits.length,
+				0,
+			);
+			const sessionsWithCommits = sessions.filter((s) => s.commits.length > 0);
+
+			log.info(`  total:   ${sessions.length}`);
+			log.info(`  open:    ${openSessions.length}`);
+			log.info(`  ended:   ${endedSessions.length}`);
+			log.info(
+				`  commits: ${totalCommits} across ${sessionsWithCommits.length} session(s)`,
+			);
+
+			const isReadyToSync = sessionsWithCommits.length > 0;
+			if (isReadyToSync) {
+				log.info(
+					`  ${sessionsWithCommits.length} session(s) ready to sync on next push`,
+				);
+			} else {
+				log.info("  no sessions ready to sync (no commits captured yet)");
+			}
+		}
+
+		return ok(undefined);
+	});
+}

package/src/commands/sync.ts

@@ -1,5 +1,5 @@
 import { err, ok, okAsync, ResultAsync, safeTry } from "neverthrow";
-import { readConfig } from "@/lib/config";
+import { resolveConfig } from "@/lib/config";
 import { getCommitMeta, getRemoteUrl, parseRemote } from "@/lib/git";
 import type { CommitRef, PendingSession } from "@/lib/pending";
 import {
@@ -320,7 +320,7 @@ export function sync(opts?: {
 	remoteUrl?: string;
 }): ResultAsync<void, CliError> {
 	return safeTry(async function* () {
-		const config = yield* readConfig();
+		const config = yield* resolveConfig();
 		if (!config) {
 			return err(
 				new CliError({

package/src/index.ts

@@ -9,24 +9,28 @@ import { push } from "@/commands/push";
 import { sessionEnd } from "@/commands/session-end";
 import { sessionStart } from "@/commands/session-start";
 import { setup } from "@/commands/setup";
+import { status } from "@/commands/status";
 import { sync } from "@/commands/sync";
 import { wrapCommand, wrapHookCommand } from "@/utils/errors";
 
+import packageJson from "../package.json";
+
 const program = new Command();
 
 program
 	.name("residue")
 	.description("Capture AI agent conversations linked to git commits")
-	.version("0.0.1");
+	.version(packageJson.version);
 
 program
 	.command("login")
 	.description("Save worker URL and auth token")
 	.requiredOption("--url <worker_url>", "Worker URL")
 	.requiredOption("--token <auth_token>", "Auth token")
+	.option("--local", "Save config to this project instead of globally")
 	.action(
-		wrapCommand((opts: { url: string; token: string }) =>
-			login({ url: opts.url, token: opts.token }),
+		wrapCommand((opts: { url: string; token: string; local?: boolean }) =>
+			login({ url: opts.url, token: opts.token, isLocal: opts.local }),
 		),
 	);
 
@@ -96,4 +100,9 @@ program
 	.description("Upload pending sessions to worker (manual trigger)")
 	.action(wrapCommand(() => push()));
 
+program
+	.command("status")
+	.description("Show current residue state for this project")
+	.action(wrapCommand(() => status()));
+
 program.parse();

package/src/lib/config.ts

@@ -1,11 +1,15 @@
 /**
  * Config management for the residue CLI.
- * Manages ~/.residue/config (JSON file).
+ * Global config: ~/.residue/config
+ * Local (per-project) config: .residue/config (in project root)
+ *
+ * resolveConfig() checks local first, then falls back to global.
  */
 
 import { mkdir } from "fs/promises";
-import { ResultAsync } from "neverthrow";
+import { okAsync, ResultAsync } from "neverthrow";
 import { join } from "path";
+import { getProjectRoot } from "@/lib/pending";
 import type { CliError } from "@/utils/errors";
 import { toCliError } from "@/utils/errors";
 
@@ -26,11 +30,12 @@ export function getConfigPath(): string {
 	return join(getConfigDir(), "config");
 }
 
-export function readConfig(): ResultAsync<ResidueConfig | null, CliError> {
+function readConfigFromPath(
+	configPath: string,
+): ResultAsync<ResidueConfig | null, CliError> {
 	return ResultAsync.fromPromise(
 		(async () => {
-			const path = getConfigPath();
-			const file = Bun.file(path);
+			const file = Bun.file(configPath);
 			const isExists = await file.exists();
 			if (!isExists) return null;
 			const text = await file.text();
@@ -40,19 +45,74 @@ export function readConfig(): ResultAsync<ResidueConfig | null, CliError> {
 	);
 }
 
-export function writeConfig(
-	config: ResidueConfig,
-): ResultAsync<void, CliError> {
+function writeConfigToPath(opts: {
+	configPath: string;
+	config: ResidueConfig;
+}): ResultAsync<void, CliError> {
 	return ResultAsync.fromPromise(
 		(async () => {
-			const dir = getConfigDir();
+			const dir = join(opts.configPath, "..");
 			await mkdir(dir, { recursive: true });
-			await Bun.write(getConfigPath(), JSON.stringify(config, null, 2));
+			await Bun.write(opts.configPath, JSON.stringify(opts.config, null, 2));
 		})(),
 		toCliError({ message: "Failed to write config", code: "CONFIG_ERROR" }),
 	);
 }
 
+/**
+ * Read the global config from ~/.residue/config.
+ */
+export function readConfig(): ResultAsync<ResidueConfig | null, CliError> {
+	return readConfigFromPath(getConfigPath());
+}
+
+/**
+ * Write the global config to ~/.residue/config.
+ */
+export function writeConfig(
+	config: ResidueConfig,
+): ResultAsync<void, CliError> {
+	return writeConfigToPath({ configPath: getConfigPath(), config });
+}
+
+/**
+ * Read the local (per-project) config from .residue/config.
+ */
+export function readLocalConfig(
+	projectRoot: string,
+): ResultAsync<ResidueConfig | null, CliError> {
+	return readConfigFromPath(join(projectRoot, ".residue", "config"));
+}
+
+/**
+ * Write the local (per-project) config to .residue/config.
+ */
+export function writeLocalConfig(opts: {
+	projectRoot: string;
+	config: ResidueConfig;
+}): ResultAsync<void, CliError> {
+	return writeConfigToPath({
+		configPath: join(opts.projectRoot, ".residue", "config"),
+		config: opts.config,
+	});
+}
+
+/**
+ * Resolve config by checking local (per-project) first, then global.
+ * Returns the first one found, or null if neither exists.
+ */
+export function resolveConfig(): ResultAsync<ResidueConfig | null, CliError> {
+	return getProjectRoot()
+		.andThen((projectRoot) => readLocalConfig(projectRoot))
+		.orElse(() => okAsync(null as ResidueConfig | null))
+		.andThen((localConfig) => {
+			if (localConfig !== null) {
+				return okAsync(localConfig as ResidueConfig | null);
+			}
+			return readConfig();
+		});
+}
+
 export function configExists(): ResultAsync<boolean, CliError> {
 	return ResultAsync.fromPromise(
 		Bun.file(getConfigPath()).exists(),