code-agent-auto-commit 1.0.0

package/dist/core/exec.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCommand = runCommand;
+exports.runCommandOrThrow = runCommandOrThrow;
+const node_child_process_1 = require("node:child_process");
+function runCommand(command, args, cwd) {
+    const result = (0, node_child_process_1.spawnSync)(command, args, {
+        cwd,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return {
+        exitCode: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+}
+function runCommandOrThrow(command, args, cwd) {
+    const result = runCommand(command, args, cwd);
+    if (result.exitCode !== 0) {
+        throw new Error(`${command} ${args.join(" ")} failed: ${result.stderr.trim() || "unknown error"}`);
+    }
+    return result.stdout;
+}

package/dist/core/filter.d.ts

@@ -0,0 +1,2 @@
+export declare function matchesAnyPattern(value: string, patterns: string[]): boolean;
+export declare function shouldIncludePath(value: string, include: string[], exclude: string[]): boolean;

package/dist/core/filter.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchesAnyPattern = matchesAnyPattern;
+exports.shouldIncludePath = shouldIncludePath;
+function escapeRegex(value) {
+    return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+}
+function patternToRegex(pattern) {
+    let source = "^";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                source += ".*";
+                i += 1;
+            }
+            else {
+                source += "[^/]*";
+            }
+        }
+        else if (ch === "?") {
+            source += ".";
+        }
+        else {
+            source += escapeRegex(ch);
+        }
+    }
+    source += "$";
+    return new RegExp(source);
+}
+function matchesAnyPattern(value, patterns) {
+    if (patterns.length === 0) {
+        return false;
+    }
+    return patterns.some((pattern) => patternToRegex(pattern).test(value));
+}
+function shouldIncludePath(value, include, exclude) {
+    if (include.length > 0 && !matchesAnyPattern(value, include)) {
+        return false;
+    }
+    if (exclude.length > 0 && matchesAnyPattern(value, exclude)) {
+        return false;
+    }
+    return true;
+}

package/dist/core/fs.d.ts

@@ -0,0 +1,7 @@
+export declare function getUserConfigHome(): string;
+export declare function getProjectConfigPath(worktree: string): string;
+export declare function getGlobalConfigPath(): string;
+export declare function ensureDirForFile(filePath: string): void;
+export declare function readJsonFile<T>(filePath: string): T | undefined;
+export declare function writeJsonFile(filePath: string, value: unknown): void;
+export declare function writeTextFile(filePath: string, content: string): void;

package/dist/core/fs.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getUserConfigHome = getUserConfigHome;
+exports.getProjectConfigPath = getProjectConfigPath;
+exports.getGlobalConfigPath = getGlobalConfigPath;
+exports.ensureDirForFile = ensureDirForFile;
+exports.readJsonFile = readJsonFile;
+exports.writeJsonFile = writeJsonFile;
+exports.writeTextFile = writeTextFile;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+function getUserConfigHome() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    if (xdg && xdg.trim().length > 0) {
+        return xdg;
+    }
+    return node_path_1.default.join(node_os_1.default.homedir(), ".config");
+}
+function getProjectConfigPath(worktree) {
+    return node_path_1.default.join(worktree, ".code-agent-auto-commit.json");
+}
+function getGlobalConfigPath() {
+    return node_path_1.default.join(getUserConfigHome(), "code-agent-auto-commit", "config.json");
+}
+function ensureDirForFile(filePath) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+}
+function readJsonFile(filePath) {
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return undefined;
+    }
+    const content = node_fs_1.default.readFileSync(filePath, "utf8");
+    return JSON.parse(content);
+}
+function writeJsonFile(filePath, value) {
+    ensureDirForFile(filePath);
+    node_fs_1.default.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+function writeTextFile(filePath, content) {
+    ensureDirForFile(filePath);
+    node_fs_1.default.writeFileSync(filePath, content, "utf8");
+}

package/dist/core/git.d.ts

@@ -0,0 +1,10 @@
+import type { ChangedFile, CommitSummary, PushProvider } from "../types";
+export declare function ensureGitRepository(worktree: string): void;
+export declare function listChangedFiles(worktree: string): ChangedFile[];
+export declare function hasStagedChanges(worktree: string): boolean;
+export declare function stagePath(worktree: string, filePath: string): void;
+export declare function commit(worktree: string, message: string): string;
+export declare function getStagedSummary(worktree: string, onlyPath?: string): CommitSummary;
+export declare function getCurrentBranch(worktree: string): string;
+export declare function getRemoteUrl(worktree: string, remote: string): string;
+export declare function push(worktree: string, remote: string, branch: string, provider: PushProvider): void;

package/dist/core/git.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureGitRepository = ensureGitRepository;
+exports.listChangedFiles = listChangedFiles;
+exports.hasStagedChanges = hasStagedChanges;
+exports.stagePath = stagePath;
+exports.commit = commit;
+exports.getStagedSummary = getStagedSummary;
+exports.getCurrentBranch = getCurrentBranch;
+exports.getRemoteUrl = getRemoteUrl;
+exports.push = push;
+const exec_1 = require("./exec");
+function assertGitRepo(worktree) {
+    const result = (0, exec_1.runCommand)("git", ["-C", worktree, "rev-parse", "--is-inside-work-tree"], worktree);
+    if (result.exitCode !== 0 || result.stdout.trim() !== "true") {
+        throw new Error(`Not a git repository: ${worktree}`);
+    }
+}
+function ensureGitRepository(worktree) {
+    assertGitRepo(worktree);
+}
+function listChangedFiles(worktree) {
+    assertGitRepo(worktree);
+    const output = (0, exec_1.runCommandOrThrow)("git", ["-C", worktree, "status", "--porcelain", "-z"], worktree);
+    if (!output) {
+        return [];
+    }
+    const files = [];
+    let offset = 0;
+    while (offset < output.length) {
+        const statusPair = output.slice(offset, offset + 2);
+        offset += 3;
+        const firstNull = output.indexOf("\0", offset);
+        if (firstNull === -1) {
+            break;
+        }
+        const firstPath = output.slice(offset, firstNull);
+        offset = firstNull + 1;
+        const indexStatus = statusPair[0];
+        const worktreeStatus = statusPair[1];
+        const isRenameOrCopy = indexStatus === "R" || indexStatus === "C" || worktreeStatus === "R" || worktreeStatus === "C";
+        if (isRenameOrCopy) {
+            const secondNull = output.indexOf("\0", offset);
+            if (secondNull === -1) {
+                break;
+            }
+            const secondPath = output.slice(offset, secondNull);
+            offset = secondNull + 1;
+            files.push({
+                path: secondPath,
+                originalPath: firstPath,
+                indexStatus,
+                worktreeStatus,
+            });
+        }
+        else {
+            files.push({
+                path: firstPath,
+                indexStatus,
+                worktreeStatus,
+            });
+        }
+    }
+    return files;
+}
+function hasStagedChanges(worktree) {
+    const result = (0, exec_1.runCommand)("git", ["-C", worktree, "diff", "--cached", "--quiet"], worktree);
+    return result.exitCode !== 0;
+}
+function stagePath(worktree, filePath) {
+    (0, exec_1.runCommandOrThrow)("git", ["-C", worktree, "add", "-A", "--", filePath], worktree);
+}
+function commit(worktree, message) {
+    (0, exec_1.runCommandOrThrow)("git", ["-C", worktree, "commit", "-m", message], worktree);
+    return (0, exec_1.runCommandOrThrow)("git", ["-C", worktree, "rev-parse", "HEAD"], worktree).trim();
+}
+function getStagedSummary(worktree, onlyPath) {
+    const pathArgs = onlyPath ? ["--", onlyPath] : [];
+    const nameStatus = (0, exec_1.runCommandOrThrow)("git", ["-C", worktree, "diff", "--cached", "--name-status", ...pathArgs], worktree).trim();
+    const diffStat = (0, exec_1.runCommandOrThrow)("git", ["-C", worktree, "diff", "--cached", "--stat", ...pathArgs], worktree).trim();
+    const patchRaw = (0, exec_1.runCommandOrThrow)("git", ["-C", worktree, "diff", "--cached", ...pathArgs], worktree);
+    const patch = patchRaw.slice(0, 12000);
+    return {
+        nameStatus,
+        diffStat,
+        patch,
+    };
+}
+function getCurrentBranch(worktree) {
+    return (0, exec_1.runCommandOrThrow)("git", ["-C", worktree, "rev-parse", "--abbrev-ref", "HEAD"], worktree).trim();
+}
+function getRemoteUrl(worktree, remote) {
+    return (0, exec_1.runCommandOrThrow)("git", ["-C", worktree, "remote", "get-url", remote], worktree).trim();
+}
+function validateProvider(provider, remoteUrl) {
+    const lower = remoteUrl.toLowerCase();
+    if (provider === "github" && !lower.includes("github")) {
+        throw new Error(`Remote URL does not look like GitHub: ${remoteUrl}`);
+    }
+    if (provider === "gitlab" && !lower.includes("gitlab")) {
+        throw new Error(`Remote URL does not look like GitLab: ${remoteUrl}`);
+    }
+}
+function push(worktree, remote, branch, provider) {
+    const remoteUrl = getRemoteUrl(worktree, remote);
+    validateProvider(provider, remoteUrl);
+    (0, exec_1.runCommandOrThrow)("git", ["-C", worktree, "push", remote, branch], worktree);
+}

package/dist/core/run.d.ts

@@ -0,0 +1,2 @@
+import type { LoadConfigOptions, RunContext, RunResult } from "../types";
+export declare function runAutoCommit(context: RunContext, configOptions: LoadConfigOptions): Promise<RunResult>;

package/dist/core/run.js

@@ -0,0 +1,148 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAutoCommit = runAutoCommit;
+const node_path_1 = __importDefault(require("node:path"));
+const ai_1 = require("./ai");
+const config_1 = require("./config");
+const filter_1 = require("./filter");
+const git_1 = require("./git");
+function normalizeFallbackType(prefix) {
+    const value = prefix.toLowerCase();
+    if (/(^|[^a-z])(feat|feature)([^a-z]|$)/.test(value)) {
+        return "feat";
+    }
+    if (/(^|[^a-z])(fix|bugfix|hotfix)([^a-z]|$)/.test(value)) {
+        return "fix";
+    }
+    if (/(^|[^a-z])(refector|refactor|chore|docs|style|test|perf|build|ci|revert)([^a-z]|$)/.test(value)) {
+        return "refector";
+    }
+    return "refector";
+}
+function fallbackSingleMessage(prefix, count) {
+    const suffix = count === 1 ? "file" : "files";
+    return `${normalizeFallbackType(prefix)}: update ${count} ${suffix}`;
+}
+function fallbackPerFileMessage(prefix, file) {
+    const type = normalizeFallbackType(prefix);
+    const primary = file.indexStatus !== " " ? file.indexStatus : file.worktreeStatus;
+    const name = node_path_1.default.basename(file.path);
+    if (primary === "A") {
+        return `${type}: add ${name}`;
+    }
+    if (primary === "D") {
+        return `${type}: remove ${name}`;
+    }
+    if (primary === "R") {
+        return `${type}: rename ${name}`;
+    }
+    return `${type}: update ${name}`;
+}
+function uniqueSorted(files) {
+    const seen = new Set();
+    const out = [];
+    for (const file of files) {
+        if (seen.has(file.path)) {
+            continue;
+        }
+        seen.add(file.path);
+        out.push(file);
+    }
+    out.sort((a, b) => a.path.localeCompare(b.path));
+    return out;
+}
+function filterFiles(files, include, exclude) {
+    return files.filter((file) => (0, filter_1.shouldIncludePath)(file.path, include, exclude));
+}
+async function buildMessage(prefix, maxLength, aiConfig, stagedPath, fallback, worktree) {
+    const summary = (0, git_1.getStagedSummary)(worktree, stagedPath);
+    const generated = await (0, ai_1.generateCommitMessage)(aiConfig, summary, maxLength);
+    if (generated) {
+        return generated;
+    }
+    if (fallback.length <= maxLength) {
+        return fallback;
+    }
+    return `${normalizeFallbackType(prefix)}: update changes`;
+}
+async function runAutoCommit(context, configOptions) {
+    const { config } = (0, config_1.loadConfig)(configOptions);
+    const worktree = node_path_1.default.resolve(context.worktree ?? config.worktree);
+    if (!config.enabled) {
+        return {
+            skipped: true,
+            reason: "disabled",
+            worktree,
+            committed: [],
+            pushed: false,
+        };
+    }
+    (0, git_1.ensureGitRepository)(worktree);
+    const changed = uniqueSorted(filterFiles((0, git_1.listChangedFiles)(worktree), config.filters.include, config.filters.exclude));
+    if (changed.length === 0) {
+        return {
+            skipped: true,
+            reason: "no changes",
+            worktree,
+            committed: [],
+            pushed: false,
+        };
+    }
+    const commits = [];
+    if (config.commit.mode === "single") {
+        for (const file of changed) {
+            (0, git_1.stagePath)(worktree, file.path);
+        }
+        if (!(0, git_1.hasStagedChanges)(worktree)) {
+            return {
+                skipped: true,
+                reason: "no staged changes",
+                worktree,
+                committed: [],
+                pushed: false,
+            };
+        }
+        const fallback = fallbackSingleMessage(config.commit.fallbackPrefix, changed.length);
+        const message = await buildMessage(config.commit.fallbackPrefix, config.commit.maxMessageLength, config.ai, undefined, fallback, worktree);
+        const hash = (0, git_1.commit)(worktree, message);
+        commits.push({
+            hash,
+            message,
+            files: changed.map((item) => item.path),
+        });
+    }
+    else {
+        if ((0, git_1.hasStagedChanges)(worktree)) {
+            throw new Error("per-file mode requires a clean staging area before auto-commit");
+        }
+        for (const file of changed) {
+            (0, git_1.stagePath)(worktree, file.path);
+            if (!(0, git_1.hasStagedChanges)(worktree)) {
+                continue;
+            }
+            const fallback = fallbackPerFileMessage(config.commit.fallbackPrefix, file);
+            const message = await buildMessage(config.commit.fallbackPrefix, config.commit.maxMessageLength, config.ai, file.path, fallback, worktree);
+            const hash = (0, git_1.commit)(worktree, message);
+            commits.push({
+                hash,
+                message,
+                files: [file.path],
+            });
+        }
+    }
+    let pushed = false;
+    if (commits.length > 0 && config.push.enabled) {
+        const branch = config.push.branch || (0, git_1.getCurrentBranch)(worktree);
+        (0, git_1.push)(worktree, config.push.remote, branch, config.push.provider);
+        pushed = true;
+    }
+    return {
+        skipped: false,
+        worktree,
+        committed: commits,
+        pushed,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { loadConfig, initConfigFile, resolveConfigPath, updateConfigWorktree } from "./core/config";
+export { runAutoCommit } from "./core/run";
+export { installOpenCodeAdapter, uninstallOpenCodeAdapter, opencodeAdapterStatus } from "./adapters/opencode";
+export { installCodexAdapter, uninstallCodexAdapter, codexAdapterStatus } from "./adapters/codex";
+export { installClaudeAdapter, uninstallClaudeAdapter, claudeAdapterStatus } from "./adapters/claude";
+export type { AutoCommitConfig, CommitMode, PushProvider, ToolName, InstallScope, RunResult, RunContext, } from "./types";

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeAdapterStatus = exports.uninstallClaudeAdapter = exports.installClaudeAdapter = exports.codexAdapterStatus = exports.uninstallCodexAdapter = exports.installCodexAdapter = exports.opencodeAdapterStatus = exports.uninstallOpenCodeAdapter = exports.installOpenCodeAdapter = exports.runAutoCommit = exports.updateConfigWorktree = exports.resolveConfigPath = exports.initConfigFile = exports.loadConfig = void 0;
+var config_1 = require("./core/config");
+Object.defineProperty(exports, "loadConfig", { enumerable: true, get: function () { return config_1.loadConfig; } });
+Object.defineProperty(exports, "initConfigFile", { enumerable: true, get: function () { return config_1.initConfigFile; } });
+Object.defineProperty(exports, "resolveConfigPath", { enumerable: true, get: function () { return config_1.resolveConfigPath; } });
+Object.defineProperty(exports, "updateConfigWorktree", { enumerable: true, get: function () { return config_1.updateConfigWorktree; } });
+var run_1 = require("./core/run");
+Object.defineProperty(exports, "runAutoCommit", { enumerable: true, get: function () { return run_1.runAutoCommit; } });
+var opencode_1 = require("./adapters/opencode");
+Object.defineProperty(exports, "installOpenCodeAdapter", { enumerable: true, get: function () { return opencode_1.installOpenCodeAdapter; } });
+Object.defineProperty(exports, "uninstallOpenCodeAdapter", { enumerable: true, get: function () { return opencode_1.uninstallOpenCodeAdapter; } });
+Object.defineProperty(exports, "opencodeAdapterStatus", { enumerable: true, get: function () { return opencode_1.opencodeAdapterStatus; } });
+var codex_1 = require("./adapters/codex");
+Object.defineProperty(exports, "installCodexAdapter", { enumerable: true, get: function () { return codex_1.installCodexAdapter; } });
+Object.defineProperty(exports, "uninstallCodexAdapter", { enumerable: true, get: function () { return codex_1.uninstallCodexAdapter; } });
+Object.defineProperty(exports, "codexAdapterStatus", { enumerable: true, get: function () { return codex_1.codexAdapterStatus; } });
+var claude_1 = require("./adapters/claude");
+Object.defineProperty(exports, "installClaudeAdapter", { enumerable: true, get: function () { return claude_1.installClaudeAdapter; } });
+Object.defineProperty(exports, "uninstallClaudeAdapter", { enumerable: true, get: function () { return claude_1.uninstallClaudeAdapter; } });
+Object.defineProperty(exports, "claudeAdapterStatus", { enumerable: true, get: function () { return claude_1.claudeAdapterStatus; } });

package/dist/test/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/config.test.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const config_1 = require("../core/config");
+(0, node_test_1.default)("init and update config file", () => {
+    const tempDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "code-agent-auto-commit-"));
+    const configPath = node_path_1.default.join(tempDir, ".code-agent-auto-commit.json");
+    const created = (0, config_1.initConfigFile)(configPath, tempDir);
+    strict_1.default.equal(created.version, 1);
+    strict_1.default.equal(created.worktree, tempDir);
+    const loaded = (0, config_1.loadConfig)({ explicitPath: configPath, worktree: tempDir });
+    strict_1.default.equal(loaded.config.worktree, tempDir);
+    const nextDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), "code-agent-auto-commit-next-"));
+    const updated = (0, config_1.updateConfigWorktree)(configPath, nextDir);
+    strict_1.default.equal(updated.worktree, nextDir);
+});

package/dist/test/filter.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/filter.test.js

@@ -0,0 +1,14 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const filter_1 = require("../core/filter");
+(0, node_test_1.default)("include and exclude patterns are applied", () => {
+    strict_1.default.equal((0, filter_1.shouldIncludePath)("src/app.ts", ["src/**"], []), true);
+    strict_1.default.equal((0, filter_1.shouldIncludePath)("README.md", ["src/**"], []), false);
+    strict_1.default.equal((0, filter_1.shouldIncludePath)(".env", [], [".env", ".env.*"]), false);
+    strict_1.default.equal((0, filter_1.shouldIncludePath)("src/main.ts", [], ["*.md"]), true);
+});

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+export type CommitMode = "single" | "per-file";
+export type PushProvider = "github" | "gitlab" | "generic";
+export type ToolName = "opencode" | "codex" | "claude" | "manual";
+export type InstallScope = "project" | "global";
+export type AIProviderApi = "openai-completions" | "anthropic-messages";
+export interface CommitConfig {
+    mode: CommitMode;
+    fallbackPrefix: string;
+    maxMessageLength: number;
+}
+export interface AIConfig {
+    enabled: boolean;
+    timeoutMs: number;
+    model: string;
+    defaultProvider: string;
+    providers: Record<string, AIProviderConfig>;
+}
+export interface AIProviderConfig {
+    api: AIProviderApi;
+    baseUrl: string;
+    apiKey?: string;
+    apiKeyEnv?: string;
+    headers?: Record<string, string>;
+}
+export interface PushConfig {
+    enabled: boolean;
+    provider: PushProvider;
+    remote: string;
+    branch: string;
+}
+export interface FilterConfig {
+    include: string[];
+    exclude: string[];
+}
+export interface AutoCommitConfig {
+    version: 1;
+    enabled: boolean;
+    worktree: string;
+    commit: CommitConfig;
+    ai: AIConfig;
+    push: PushConfig;
+    filters: FilterConfig;
+}
+export interface ChangedFile {
+    path: string;
+    originalPath?: string;
+    indexStatus: string;
+    worktreeStatus: string;
+}
+export interface CommitSummary {
+    nameStatus: string;
+    diffStat: string;
+    patch: string;
+}
+export interface CommitRecord {
+    hash: string;
+    message: string;
+    files: string[];
+}
+export interface RunResult {
+    skipped: boolean;
+    reason?: string;
+    worktree: string;
+    committed: CommitRecord[];
+    pushed: boolean;
+}
+export interface RunContext {
+    tool: ToolName;
+    worktree?: string;
+    sessionID?: string;
+    event?: unknown;
+}
+export interface LoadConfigOptions {
+    explicitPath?: string;
+    worktree?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/docs/CONFIG.md

@@ -0,0 +1,72 @@
+# Configuration Reference
+
+`cac` reads JSON config from:
+
+1. `--config <path>` if provided
+2. `<worktree>/.code-agent-auto-commit.json` if it exists
+3. `~/.config/code-agent-auto-commit/config.json`
+
+## Schema
+
+```json
+{
+  "version": 1,
+  "enabled": true,
+  "worktree": "/absolute/path",
+  "commit": {
+    "mode": "single",
+    "fallbackPrefix": "chore(auto)",
+    "maxMessageLength": 72
+  },
+  "ai": {
+    "enabled": false,
+    "timeoutMs": 15000,
+    "model": "openai/gpt-4.1-mini",
+    "defaultProvider": "openai",
+    "providers": {
+      "openai": {
+        "api": "openai-completions",
+        "baseUrl": "https://api.openai.com/v1",
+        "apiKeyEnv": "OPENAI_API_KEY"
+      },
+      "anthropic": {
+        "api": "anthropic-messages",
+        "baseUrl": "https://api.anthropic.com/v1",
+        "apiKeyEnv": "ANTHROPIC_API_KEY"
+      }
+    }
+  },
+  "push": {
+    "enabled": false,
+    "provider": "github",
+    "remote": "origin",
+    "branch": ""
+  },
+  "filters": {
+    "include": [],
+    "exclude": [".env", ".env.*", "*.pem", "*.key", "*.p12"]
+  }
+}
+```
+
+## AI Provider Config (OpenClaw-style)
+
+- `ai.model`: supports `provider/model` format (example: `openai/gpt-4.1-mini`, `anthropic/claude-3-5-sonnet-latest`).
+- `ai.defaultProvider`: used when `ai.model` does not include a provider prefix.
+- `ai.providers.<name>.api`:
+  - `openai-completions` -> `POST /chat/completions`
+  - `anthropic-messages` -> `POST /messages`
+- `ai.providers.<name>.baseUrl`: provider endpoint base URL.
+- `ai.providers.<name>.apiKey` or `apiKeyEnv`: API key source (env preferred).
+- `ai.providers.<name>.headers`: optional custom headers.
+
+## Notes
+
+- `commit.mode`
+  - `single`: stage and commit all selected files together
+  - `per-file`: commit each selected file separately
+- `push.provider`
+  - `github`: remote URL must contain `github`
+  - `gitlab`: remote URL must contain `gitlab`
+  - `generic`: no provider URL validation
+- Keep API keys in environment variables when possible.