@synmux/claude-commit 0.1.0

package/README.md

@@ -0,0 +1,177 @@
+# `claude-commit`
+
+Generate high-quality git commit messages with Claude — using your **Claude Code
+subscription**, not an API key.
+
+`claude-commit` reads your staged diff, has a strong model summarize it, and a fast
+model turn that summary into a well-formed commit message. It handles diffs of any
+size (including ones too large to fit in a single context window), and supports
+Conventional Commits, gitmoji, first-line templates, custom instructions, and an
+interactive mode for choosing between several options.
+
+```console
+$ cco -c
+✔ Committed
+feat(auth): add error handling and refresh token rotation to login
+```
+
+## How it works
+
+Want more details? See [WALKTHROUGH.md](WALKTHROUGH.md).
+
+```plaintext
+staged diff ──split──▶ [chunk, …] ──sonnet[1m]──▶ summaries ──haiku──▶ commit message
+```
+
+1. **Summarize** — the diff is split into chunks that fit the context window and
+   each chunk is summarized by a strong model (`sonnet[1m]`, Sonnet with a 1M-token
+   context). Diffs larger than 1M tokens simply produce more chunks.
+2. **Write** — the summaries are handed to a fast model (`haiku`) that writes the
+   final commit message according to your formatting rules.
+
+Both stages run through the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview).
+
+## Install
+
+Requires [Bun](https://bun.sh).
+
+```sh
+bun install
+bun link            # makes `cco` and `claude-commit` available on your PATH
+```
+
+Or run it directly without linking:
+
+```sh
+bun run bin/cco.ts --help
+```
+
+## Authentication
+
+`claude-commit` uses the Claude Agent SDK and, by default, always authenticates
+with your Claude Code subscription session (run `claude login` once). Usage is
+bundled with your Claude Code usage — no separate API bill.
+
+To protect you from surprise pay-as-you-go charges, API credentials in your
+environment (`ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`) are **ignored by
+default**: they are stripped from the environment passed to the model
+subprocess, and a one-line notice is printed to stderr. To bill an API key
+instead (pay-as-you-go), opt in explicitly in your configuration:
+
+```json
+{ "allowApiKey": true }
+```
+
+## Usage
+
+```sh
+cco [options]
+```
+
+By default `cco` summarizes your **staged** changes, generates a message, shows it,
+and asks for confirmation before committing. Pass `-y` to skip the prompt, or
+`--dry-run` to print the message without committing.
+
+### Options
+
+| Flag                                     | Description                                                                             |
+| ---------------------------------------- | --------------------------------------------------------------------------------------- |
+| `-i, --interactive` / `--no-interactive` | Choose between several options in an interactive TUI, or skip it when enabled in config |
+| `-n, --count <n>`                        | Number of options to generate in interactive mode (default 3)                           |
+| `-a, --all`                              | Stage all changes (`git add -A`) before committing                                      |
+| `-c, --conventional`                     | Format as a [Conventional Commit](https://www.conventionalcommits.org)                  |
+| `-g, --gitmoji`                          | Prefix the subject with a [gitmoji](https://gitmoji.dev)                                |
+| `-m, --multiline` / `--no-multiline`     | Write a multi-line commit (subject + body), or force a single line                      |
+| `-t, --template <tpl>`                   | Template for the first line, e.g. `"[PROJ-1] {message}"`                                |
+| `-p, --prompt <text>`                    | Extra instructions appended to the prompt                                               |
+| `--model-summary <model>`                | Model used to summarize the diff (default `sonnet[1m]`)                                 |
+| `--model-final <model>`                  | Model used to write the message (default `haiku`)                                       |
+| `-d, --dry-run`                          | Print the message to stdout without committing                                          |
+| `-y, --yes`                              | Commit without asking for confirmation                                                  |
+| `--no-spinner`                           | Disable the progress spinner                                                            |
+| `--config <path>`                        | Path to a config file                                                                   |
+| `-v, --verbose`                          | Print summaries, cost and debug output                                                  |
+
+### Examples
+
+```sh
+cco                      # generate, confirm, and commit staged changes
+cco -a -c                # stage everything and write a Conventional Commit
+cco -c -g -m             # conventional + gitmoji + a body
+cco -i -n 5              # pick from 5 options interactively
+cco --dry-run | cat      # print a message without committing (TUI-free, pipe-safe)
+git commit -F <(cco -d)  # use the message with your own git invocation
+```
+
+In a pipe (no TTY) there is no spinner and no confirmation prompt — `cco` just
+generates and commits (or prints, with `--dry-run`).
+
+## Interactive mode
+
+`cco -i` opens a TUI listing several candidate messages to choose from. The
+options are generated with a higher temperature (`interactiveTemperature`) for
+more variety. Use the arrow keys to move between options, `Enter` to commit the
+highlighted option, `e` to edit it in your `$EDITOR` first, and `q`/`Esc` to
+cancel.
+
+To make interactive mode the default without typing `-i` every time, set
+`"interactive": true` in your config (see below); opt out of a single run with
+`--no-interactive`. When there is no interactive terminal — in a pipe, a CI job,
+or with `--dry-run` — `cco` ignores the setting and falls back to the
+non-interactive flow rather than failing.
+
+## Configuration
+
+Configuration is layered, from lowest to highest precedence:
+
+1. Built-in defaults.
+2. **A global user config** at `~/.config/claude-commit/config.json` (or
+   `$XDG_CONFIG_HOME/claude-commit/config.json`) — your personal defaults across
+   every project. The `.claude-commit.json` / `.claude-commitrc.json` /
+   `.claude-commitrc` names are also accepted in that directory.
+3. A `claude-commit` key in the repo's `package.json`.
+4. The nearest `.claude-commit.json` / `.claude-commitrc.json` / `.claude-commitrc`,
+   searched from the current directory up to the repo root.
+5. CLI flags.
+
+So a global config sets your personal defaults and any project further down the
+tree can override them. Note that the `config.json` name is recognised **only** in
+the global directory; inside a project, use one of the dotted filenames. The same
+keys are valid at every level:
+
+```json
+{
+  "conventionalCommits": true,
+  "gitmoji": true,
+  "multiline": true,
+  "template": null,
+  "customPrompt": "Reference the ticket id from the branch name when present.",
+  "interactive": true,
+  "interactiveCount": 3,
+  "interactiveTemperature": 1,
+  "models": {
+    "summary": "sonnet[1m]",
+    "final": "haiku"
+  },
+  "maxChunkTokens": 600000,
+  "charsPerToken": 3.5,
+  "allowApiKey": false
+}
+```
+
+## Development
+
+```sh
+bun test          # run the test suite
+bun run typecheck # tsc --noEmit
+```
+
+## Did you vibe this?
+
+I distinguish vibe coding and AI-assisted development by
+_where you live as the developer_. If you live in the code, it's AI-assisted dev.
+If you just shout at a chat and hope for the best, that's vibe coding.
+
+This was AI-assisted development.
+
+Thanks for coming to my TED talk.

package/bin/cco.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env bun
+/**
+ * Executable entry point for `cco` / `claude-commit`.
+ */
+import { run } from "../src/cli";
+import { color } from "../src/ui/colors";
+
+run(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((err) => {
+    // Unexpected (non-ClaudeCommitError) failures: print a stack for debugging.
+    process.stderr.write(
+      `${color("31", "unexpected error:")} ${err?.stack ?? err}\n`,
+    );
+    process.exitCode = 1;
+  });

package/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Library entry point for `claude-commit`.
+ *
+ * Re-exports the building blocks so the commit-message pipeline can be used
+ * programmatically. The CLI lives in `bin/cco.ts` (`src/cli.ts`).
+ */
+export { generateCommit } from "./src/generate";
+export type {
+  GenerateOptions,
+  GenerateProgress,
+  GenerateResult,
+} from "./src/generate";
+export { runPrompt } from "./src/agent";
+export type { RunPromptOptions } from "./src/agent";
+export { splitDiff } from "./src/diff";
+export {
+  DEFAULT_CONFIG,
+  loadFileConfig,
+  resolveConfig,
+  mergeConfig,
+  mergePartial,
+  sanitizePartial,
+} from "./src/config";
+export {
+  buildSummarySystem,
+  buildSummaryUser,
+  buildFinalSystem,
+  buildFinalUser,
+  parseOptions,
+  cleanMessage,
+} from "./src/prompts";
+export * as git from "./src/git";
+export { ClaudeCommitError } from "./src/errors";
+export type {
+  Config,
+  ModelConfig,
+  PartialConfig,
+  ModelResult,
+  FileChange,
+} from "./src/types";

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@synmux/claude-commit",
+  "version": "0.1.0",
+  "description": "Generate git commit messages with Claude, using your Claude Code subscription.",
+  "main": "index.ts",
+  "module": "index.ts",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "cco": "bin/cco.ts",
+    "claude-commit": "bin/cco.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "index.ts"
+  ],
+  "claude-commit": {
+    "conventionalCommits": true,
+    "gitmoji": true,
+    "multiline": true,
+    "template": null,
+    "customPrompt": null,
+    "interactive": false,
+    "interactiveCount": 3,
+    "interactiveTemperature": 1,
+    "models": {
+      "summary": "sonnet[1m]",
+      "final": "haiku"
+    },
+    "maxChunkTokens": 600000,
+    "charsPerToken": 3.5,
+    "allowApiKey": false
+  },
+  "devDependencies": {
+    "@anthropic-ai/claude-code": "^2.1.198",
+    "@trunkio/launcher": "^1.3.4",
+    "@types/bun": "^1.3.14",
+    "prettier": "3.9.4",
+    "skilld": "^2.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.198",
+    "@opentui/core": "^0.4.2",
+    "commander": "^15.0.0"
+  },
+  "scripts": {
+    "start": "bun run bin/cco.ts",
+    "test": "bun test",
+    "format": "bun run prettier --write . && bun run trunk fmt -a",
+    "lint": "bun run trunk check -a",
+    "lint:fix": "bun run trunk check -a --fix",
+    "typecheck": "bun run tsc --noEmit",
+    "prepare": "bun run skilld prepare || true"
+  }
+}

package/src/agent.ts

@@ -0,0 +1,253 @@
+/**
+ * Thin wrapper around the Claude Agent SDK that turns a single prompt into a
+ * single text completion.
+ *
+ * The Agent SDK spawns a bundled `claude` binary, so authentication follows
+ * Claude Code's own resolution order over the environment we hand it. By
+ * default the API credential variables (`ANTHROPIC_API_KEY` /
+ * `ANTHROPIC_AUTH_TOKEN`) are stripped from that environment, forcing the
+ * `claude login` subscription session so the cost is bundled with Claude Code
+ * usage; the `allowApiKey` config option passes them through for explicit
+ * pay-as-you-go billing. We deliberately disable every tool (`tools: []`) and
+ * load no settings (`settingSources: []`) so the run is a clean, isolated,
+ * prompt-in/text-out request.
+ */
+import {
+  query,
+  type Options,
+  type SDKMessage,
+} from "@anthropic-ai/claude-agent-sdk";
+import { ClaudeCommitError } from "./errors";
+import type { ModelResult } from "./types";
+
+export interface RunPromptOptions {
+  /** Model string (alias like `haiku`, `sonnet[1m]`, or a full model id). */
+  model: string;
+  /** Full custom system prompt. */
+  system: string;
+  /** Receives assistant text as it streams in (enables partial messages). */
+  onText?: (delta: string) => void;
+  /** Abort the in-flight request. */
+  abortController?: AbortController;
+  /** Receives the underlying CLI's stderr (for `--verbose`). */
+  onStderr?: (data: string) => void;
+  /**
+   * Sampling temperature. Passed to the model via `CLAUDE_CODE_EXTRA_BODY`.
+   * Used to add variety when generating several interactive options. Models
+   * that don't accept a temperature override will reject the request, so the
+   * caller should be prepared to retry without it.
+   */
+  temperature?: number;
+  /**
+   * Request a structured JSON response matching this schema. The parsed object
+   * is returned on {@link ModelResult.structured}. Models that don't support
+   * structured outputs will reject the request, so the caller should be
+   * prepared to retry without it.
+   */
+  outputFormat?: { type: "json_schema"; schema: Record<string, unknown> };
+  /**
+   * Allow API credentials from the environment to reach the SDK subprocess.
+   * Defaults to false: `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN` are
+   * stripped so the run is billed to the Claude subscription.
+   */
+  allowApiKey?: boolean;
+}
+
+/**
+ * Environment variables that carry Claude API credentials. Their presence
+ * switches the spawned `claude` binary from subscription auth to
+ * pay-as-you-go API billing, so they are stripped from the subprocess
+ * environment unless the user opts in via the `allowApiKey` config option.
+ */
+export const GATED_CREDENTIAL_VARS = [
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_AUTH_TOKEN",
+] as const;
+
+/**
+ * Names of the gated credential variables present in `env`. An empty string
+ * counts as present, since presence alone perturbs credential resolution.
+ */
+export function presentCredentialVars(
+  env: Record<string, string | undefined>,
+): string[] {
+  return GATED_CREDENTIAL_VARS.filter((name) => env[name] !== undefined);
+}
+
+export interface SubprocessEnvOptions {
+  /** Environment to derive the subprocess environment from (usually `process.env`). */
+  baseEnv: Record<string, string | undefined>;
+  /**
+   * Pass API credential variables through instead of stripping them.
+   * Defaults to false so the gate fails safe when a caller omits it.
+   */
+  allowApiKey?: boolean;
+  /** Sampling temperature to inject via `CLAUDE_CODE_EXTRA_BODY`, preserving any existing extra body. */
+  temperature?: number;
+}
+
+/**
+ * Build the environment for the Claude Agent SDK subprocess, or return
+ * `undefined` when the parent environment can be inherited unchanged.
+ *
+ * Unless `allowApiKey` is set, API credential variables are removed so the
+ * spawned `claude` binary always authenticates with the user's subscription
+ * session — an exported `ANTHROPIC_API_KEY` must never silently switch
+ * billing to pay-as-you-go.
+ */
+export function buildSubprocessEnv(
+  opts: SubprocessEnvOptions,
+): Record<string, string | undefined> | undefined {
+  const { baseEnv, allowApiKey = false, temperature } = opts;
+  const stripped = allowApiKey ? [] : presentCredentialVars(baseEnv);
+  if (stripped.length === 0 && temperature == null) return undefined;
+
+  const env = { ...baseEnv };
+  for (const name of stripped) delete env[name];
+
+  if (temperature != null) {
+    let extra: Record<string, unknown> = {};
+    const existing = baseEnv.CLAUDE_CODE_EXTRA_BODY;
+    if (existing) {
+      try {
+        const parsed: unknown = JSON.parse(existing);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+          extra = parsed as Record<string, unknown>;
+        }
+      } catch {
+        /* ignore a malformed existing value */
+      }
+    }
+    env.CLAUDE_CODE_EXTRA_BODY = JSON.stringify({ ...extra, temperature });
+  }
+
+  return env;
+}
+
+/** Map a known SDK assistant error code to a friendlier, actionable message. */
+function describeAssistantError(code: string): string {
+  switch (code) {
+    case "authentication_failed":
+    case "oauth_org_not_allowed":
+      return (
+        "Authentication failed. Run `claude login` to sign in with your Claude " +
+        "subscription, or set ANTHROPIC_API_KEY and enable `allowApiKey` in " +
+        "your claude-commit config."
+      );
+    case "billing_error":
+      return "Billing error from the Claude API. Check your plan or API credits.";
+    case "rate_limit":
+      return "Rate limited by the Claude API. Try again shortly.";
+    case "overloaded":
+      return "The Claude API is overloaded. Try again shortly.";
+    case "model_not_found":
+      return "The requested model was not found. Check the configured model name.";
+    case "max_output_tokens":
+      return "The model hit its output limit before finishing.";
+    default:
+      return `Model request failed (${code}).`;
+  }
+}
+
+/**
+ * Run a single prompt and return the model's text response.
+ *
+ * Throws {@link ClaudeCommitError} on any model/authentication/quota failure.
+ */
+export async function runPrompt(
+  prompt: string,
+  opts: RunPromptOptions,
+): Promise<ModelResult> {
+  const subprocessEnv = buildSubprocessEnv({
+    baseEnv: process.env,
+    allowApiKey: opts.allowApiKey ?? false,
+    ...(opts.temperature != null ? { temperature: opts.temperature } : {}),
+  });
+  const options: Options = {
+    model: opts.model,
+    systemPrompt: opts.system,
+    tools: [], // pure text completion: no Bash/Read/Edit/etc.
+    maxTurns: 1,
+    settingSources: [], // ignore user/project/local settings, CLAUDE.md, MCP, plugins
+    includePartialMessages: Boolean(opts.onText),
+    ...(opts.abortController ? { abortController: opts.abortController } : {}),
+    ...(opts.onStderr ? { stderr: opts.onStderr } : {}),
+    ...(subprocessEnv ? { env: subprocessEnv } : {}),
+    ...(opts.outputFormat ? { outputFormat: opts.outputFormat } : {}),
+  };
+
+  let resultText: string | null = null;
+  let costUsd = 0;
+  let model: string | undefined;
+  let structured: unknown;
+  let assistantError: string | undefined;
+
+  let response;
+  try {
+    response = query({ prompt, options });
+    for await (const message of response as AsyncIterable<SDKMessage>) {
+      switch (message.type) {
+        case "stream_event": {
+          if (opts.onText) {
+            const event = message.event as {
+              type?: string;
+              delta?: { type?: string; text?: string };
+            };
+            if (
+              event.type === "content_block_delta" &&
+              event.delta?.type === "text_delta"
+            ) {
+              opts.onText(event.delta.text ?? "");
+            }
+          }
+          break;
+        }
+        case "assistant": {
+          if (message.error) assistantError = message.error;
+          break;
+        }
+        case "result": {
+          costUsd = message.total_cost_usd ?? 0;
+          // The served model is the (only) key of modelUsage, when present.
+          const usedModels = Object.keys(message.modelUsage ?? {});
+          if (usedModels.length > 0) model = usedModels[0];
+          if (message.subtype === "success") {
+            resultText = message.result;
+            structured = message.structured_output;
+          } else {
+            const detail =
+              "errors" in message && message.errors.length
+                ? message.errors.join("; ")
+                : message.subtype;
+            throw new ClaudeCommitError(`Model run failed: ${detail}`);
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    }
+  } catch (err) {
+    if (err instanceof ClaudeCommitError) throw err;
+    if (opts.abortController?.signal.aborted) {
+      throw new ClaudeCommitError("Generation was cancelled.");
+    }
+    throw new ClaudeCommitError(
+      `Failed to call the Claude Agent SDK: ${(err as Error).message}`,
+    );
+  }
+
+  if (assistantError) {
+    throw new ClaudeCommitError(describeAssistantError(assistantError));
+  }
+  if (resultText === null) {
+    throw new ClaudeCommitError("The model returned no result.");
+  }
+
+  return {
+    text: resultText.trim(),
+    costUsd,
+    ...(model ? { model } : {}),
+    ...(structured !== undefined ? { structured } : {}),
+  };
+}