@residue/cli 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# @residue/cli
+
+## 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.",
@@ -4425,7 +4453,7 @@ function setup(opts) {
 // 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.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)");

package/package.json

@@ -1,6 +1,11 @@
 {
 	"name": "@residue/cli",
-	"version": "0.0.1",
+	"version": "0.0.2",
+	"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/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

@@ -24,9 +24,10 @@ program
 	.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 }),
 		),
 	);
 

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(),