@synmux/claude-commit 1.0.1 → 1.0.3

package/README.md

@@ -20,18 +20,24 @@ feat(auth): add error handling and refresh token rotation to login
 Want more details? See [WALKTHROUGH.md](WALKTHROUGH.md).
 
 ```plaintext
-staged diff ──split──▶ [chunk, …] ──sonnet──▶ summaries ──sonnet──▶ commit message
+staged diff ──ignore──▶ ──split──▶ [chunk, …] ──sonnet──▶ summaries ──sonnet──▶ 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`, which carries a native
    1M-token context). Diffs larger than 1M tokens simply produce more chunks.
+   Paths listed in [`ignore`](#ignoring-paths-entirely) are dropped first and
+   never read at all; changes under configured
+   [low-priority paths](#low-priority-paths) are summarized separately, so churn
+   cannot crowd out the code.
 2. **Write** - the summaries are handed to the same model (`sonnet`) to write the
    final commit message according to your formatting rules. The message is the
    whole point of the tool, and its input is tiny, so a strong model here costs
    almost nothing extra.
 
-Both stages run through the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview).
+Either stage can run on a local [Ollama](#ollama-models) model instead; by
+default both go through the
+[Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview).
 
 ## Install
 
@@ -64,6 +70,9 @@ instead (pay-as-you-go), opt in explicitly in your configuration:
 { "allowApiKey": true }
 ```
 
+Ollama models sit outside all of this: they run on a server you control, over
+plain HTTP, with no credential at all. See [Ollama models](#ollama-models).
+
 ## Usage
 
 ```sh
@@ -88,6 +97,11 @@ and asks for confirmation before committing. Pass `-y` to skip the prompt, or
 | `-p, --prompt <text>`                    | Extra instructions appended to the prompt                                               |
 | `--model-summary <model>`                | Model used to summarize the diff (default `sonnet`)                                     |
 | `--model-final <model>`                  | Model used to write the message (default `sonnet`)                                      |
+| `--skip-armored`                         | Omit armored/encoded lines (age/gpg armor, base64 blobs) from the summarized diff       |
+| `--no-low-priority-paths`                | Ignore `lowPriorityPaths` for this run, so every change weighs the same                 |
+| `--no-ignore`                            | Disregard `ignore` for this run, so every staged change is read                         |
+| `--ollama-host <url>`                    | Base URL of the Ollama server for `ollama:` models                                      |
+| `--ollama-context <tokens>`              | Context window requested from Ollama models                                             |
 | `-d, --dry-run`                          | Print the message to stdout without committing                                          |
 | `-y, --yes`                              | Commit without asking for confirmation                                                  |
 | `--no-spinner`                           | Disable the progress spinner                                                            |
@@ -151,7 +165,7 @@ keys are valid at every level:
   "interactive": true,
   "interactiveCount": 3,
   "interactiveTemperature": 1,
-  "spinner": "bouncingBall",
+  "spinner": "material",
   "models": {
     "summary": "sonnet",
     "final": "sonnet"
@@ -159,6 +173,13 @@ keys are valid at every level:
   "maxChunkTokens": 600000,
   "charsPerToken": 3.5,
   "skipArmored": false,
+  "lowPriorityPaths": [],
+  "ignore": [],
+  "ollama": {
+    "host": "http://localhost:11434",
+    "context": "auto",
+    "keepAlive": null
+  },
   "allowApiKey": false
 }
 ```
@@ -166,10 +187,12 @@ keys are valid at every level:
 `spinner` chooses the progress animation: any name from the
 [cli-spinners](https://github.com/sindresorhus/cli-spinners) set bundled with
 [ora](https://github.com/sindresorhus/ora) (`"dots"`, `"moon"`, `"pong"`,
-`"bouncingBall"`, ...). Unknown names are ignored and the default
-`bouncingBall` is used. `--no-spinner` disables the animated spinner, but final
+`"material"`, ...). Unknown names are ignored and the default
+`material` is used. `--no-spinner` disables the animated spinner, but final
 status lines still print.
 
+The `material` spinner is chosen because it's fucking cool. Fight me.
+
 `maxChunkTokens` is a cap, not a promise: at run time it is clamped to the
 summary model's context window minus a fixed reserve (1M-window models such as
 current Sonnet/Opus keep the full budget; Haiku, older pinned model ids, and
@@ -193,6 +216,186 @@ every `chezmoi re-add` re-encrypts nondeterministically and produces megabytes
 of churned armor. Drop a `.claude-commit.json` with `{ "skipArmored": true }`
 in the repo root to enable it per-repo.
 
+### Low-priority paths
+
+Some paths change a lot without meaning much - generated docs, lockfiles,
+vendored snapshots, build output. Left alone, a commit that touches twenty
+lines of code and regenerates two thousand lines of tooling gets a subject
+line about the tooling. `lowPriorityPaths` lists gitignore-style patterns for
+those paths:
+
+```json
+{
+  "lowPriorityPaths": [".agents/skills/*-skilld", "bun.lock", "!bun.lock.keep"]
+}
+```
+
+Changes under matching paths are summarised separately and briefly, and the
+model is told that the subject line - and the commit type, scope and gitmoji
+where you use them - comes from the _other_ changes, however small they are.
+The low-priority changes are mentioned in the subject only if they fit, and in
+the body (with `multiline`) only after the primary changes. When _every_
+changed file is low priority there is nothing for it to yield to, so the
+changes are described normally, exactly as if no patterns were configured.
+
+Pattern rules follow `.gitignore` conventions, so trunk or gitignore lines can
+usually be copied in:
+
+- A pattern with a `/` in it is anchored at the repository root and matches a
+  path or any directory above it - `.agents/skills/*-skilld` covers every file
+  inside each matching directory.
+- A pattern without a `/` matches any path segment at any depth - `bun.lock`
+  matches `packages/app/bun.lock`; `*-skilld` matches everything inside any
+  `*-skilld` directory.
+- `*` matches dotfiles and does not cross `/`; `**` does; `{a,b}` expands. A
+  leading `/` or `./` anchors, a trailing `/` is ignored. The anchoring
+  decision looks at the whole pattern, so a `/` inside a brace group anchors
+  all of its alternatives - prefer one pattern per intent.
+- A leading `!` negates, and the last matching pattern wins:
+  `["docs/**", "!docs/adr/**"]` deprioritises docs except the ADRs.
+- Patterns are always matched against repository-root-relative paths with
+  `/` separators, whichever directory you run `cco` from. A backslash in a
+  pattern is an escape (`\[`, `\{`, `\!` for the literal characters), so
+  Windows-style `dist\**` matches nothing.
+- Patterns are not validated: a typo such as an unbalanced `{` is parsed
+  rather than rejected and may match something unexpected, so check the
+  `--verbose` match counts when you add one.
+
+A rename into or out of a low-priority path counts as primary (both sides
+must match). The nearest config layer that sets the key wins outright - lists
+are never merged - so `"lowPriorityPaths": []` in a project opts out of a
+global list, and a project that wants the global patterns plus its own must
+repeat them. `--no-low-priority-paths` switches the feature off for one run,
+which is handy when the churn _is_ the story, or for comparing messages while
+tuning patterns.
+
+This changes how changes are _weighted_ in the message, not how much of the
+diff is read: low-priority content is still summarised in full, at the same
+cost. To skip content outright, see `skipArmored`. Under `--verbose`, `cco`
+reports how many files matched (`low-priority paths: matched 3 of 41 files`),
+which is the only way to tell a pattern that matched nothing from one that
+matched everything and was promoted.
+
+### Ignoring paths entirely
+
+`lowPriorityPaths` still reads everything it deprioritises, and pays for it.
+Some content is worth neither the tokens nor the time: a vendored dependency
+tree, a generated API client, a data fixture that changes wholesale.
+
+`ignore` takes the same gitignore-style patterns and removes those file
+sections from the diff **before anything else looks at it** - before the
+low-priority partition, before chunking, before any model call:
+
+```json
+{ "ignore": ["vendor/**", "**/__snapshots__", "*.generated.ts"] }
+```
+
+The stages compose in the order their names suggest:
+
+```text
+diff ─ ignore ─▶ ─ skipArmored ─▶ ─ lowPriorityPaths ─▶ chunks ─▶ summaries
+```
+
+Two things worth being clear about:
+
+- **The files are still committed.** `ignore` governs what the model reads,
+  never what git stages. `cco` is writing a message, not choosing a changeset.
+- **When it matches _everything_, `cco` stops** with an error naming the
+  directive, rather than inventing a message about changes you told it not to
+  read. This is deliberately unlike `lowPriorityPaths`, which promotes its
+  partition in the same situation - "this matters less" can degrade
+  gracefully, "do not look at this" has nothing to degrade to. Pass
+  `--no-ignore` for that one commit.
+
+As with `lowPriorityPaths`, a section is dropped only when it names at least
+one path and _all_ of them match, so a rename out of an ignored directory
+survives. `--verbose` reports the count
+(`ignore: dropped 3 of 41 files before reading`).
+
+## Ollama models
+
+Any model can be run on a local (or self-hosted) [Ollama](https://ollama.com)
+server instead of Claude, by prefixing its name with `ollama:`. Everything
+after the prefix is the Ollama model name **verbatim**, tag included:
+
+```json
+{
+  "models": {
+    "summary": "ollama:ornith-1.5:35b",
+    "final": "sonnet"
+  }
+}
+```
+
+The two stages resolve independently, so that mixed setup is the interesting
+one: reading the diff is the bulk of the work and the most sensitive thing
+`cco` touches, so it runs locally and free, while the final message - one
+short, quality-sensitive call on a summary - still goes to Claude. The prefix
+works anywhere a model name does, including the flags:
+
+```sh
+cco --model-summary ollama:ornith-1.5:35b --dry-run -v
+```
+
+The server needs no credential. `cco` talks to Ollama's native `/api/chat`
+endpoint, not either of its OpenAI/Anthropic compatibility layers, because
+only the native API can set a context length.
+
+### Context length is the setting that matters
+
+Ollama picks a context window for each model from available VRAM (4k / 32k /
+256k tiers, capped at the model's trained maximum), and a prompt that
+exceeds it is truncated **silently** - HTTP 200, oldest content dropped,
+nothing on the response to say so. A summary written from half a diff is
+worse than no summary, so `cco` never lets that number stay implicit: it
+sends an explicit window on every request, sizes its diff chunks against the
+same number, and checks the token counts afterwards to catch a truncation
+that happened anyway (in which case it re-splits the chunk and retries,
+exactly as it does for a Claude context overflow).
+
+Where the number comes from is `ollama.context`:
+
+```json
+{
+  "ollama": {
+    "host": "http://localhost:11434",
+    "context": "auto",
+    "keepAlive": "10m"
+  }
+}
+```
+
+- `context` - `"auto"` (the default) **asks the server** rather than
+  guessing: the model is preloaded with no window set, so Ollama applies
+  its own VRAM-based choice, and `cco` reads that choice back from
+  `/api/ps` before sizing anything. That is the largest window Ollama
+  believes this machine can actually run - 131072 for a Gemma model on a
+  large Mac, 4096 for the same model on a small laptop - resolved once per
+  model per run, and shown under `--verbose`. A number pins the window
+  instead: lower it when memory is tight (usage scales with it, multiplied
+  by `OLLAMA_NUM_PARALLEL`), or raise it past the tier if you know your
+  hardware better than the server does. A smaller window is never a
+  correctness problem - `cco` just splits the diff into more chunks.
+- `host` - defaults to `$OLLAMA_HOST`, then `http://localhost:11434`. A bare
+  `box.local:11434` gains an `http://`, matching Ollama's own convention.
+- `keepAlive` - how long the server keeps the model loaded after a request: a
+  duration string (`"10m"`), seconds as a number, `0` to unload immediately,
+  or negative to pin it. `null` leaves the server's own default. Pinning is
+  worth it if you commit often; a 35b model takes a while to load.
+
+### What differs from a Claude model
+
+- **Cost is reported as zero**, because local inference is not billed. In a
+  mixed run, `--verbose`'s total is exactly the Claude half.
+- **Structured output** is requested through Ollama's `format` field. A model
+  or server that cannot honour it (Ollama Cloud does not support it at all)
+  falls back to plain-text parsing automatically.
+- **A missing model is an error, not a download.** `cco` tells you to run
+  `ollama pull <model>` rather than pulling tens of gigabytes on your behalf.
+- **Reasoning is never requested**, and any the model volunteers is
+  discarded - models disagree about whether thinking can even be switched
+  off, and asking is a good way to earn a 400.
+
 ## Development
 
 ```sh

package/index.ts

@@ -9,10 +9,36 @@ export type {
   GenerateOptions,
   GenerateProgress,
   GenerateResult,
+  IgnoreStats,
+  LowPriorityStats,
+  OllamaContextWindow,
 } from "./src/generate";
-export { runPrompt } from "./src/agent";
+export { runClaudePrompt, runPrompt } from "./src/agent";
 export type { RunPromptOptions } from "./src/agent";
-export { splitDiff } from "./src/diff";
+export {
+  probeOllamaContext,
+  resolveOllamaContext,
+  resolveOllamaHost,
+  runOllamaPrompt,
+} from "./src/ollama";
+export {
+  DEFAULT_OLLAMA_CONTEXT,
+  DEFAULT_OLLAMA_CONTEXT_TOKENS,
+  DEFAULT_OLLAMA_HOST,
+  isOllamaModel,
+  OLLAMA_PREFIX,
+  parseModelRef,
+} from "./src/models";
+export type { ModelProvider, ModelRef } from "./src/models";
+export {
+  applyIgnorePatterns,
+  partitionDiff,
+  sectionPaths,
+  splitDiff,
+} from "./src/diff";
+export type { DiffPartition, IgnoreResult } from "./src/diff";
+export { createPathMatcher, matchesPathPatterns } from "./src/paths";
+export type { PathMatcher } from "./src/paths";
 export {
   DEFAULT_CONFIG,
   loadFileConfig,
@@ -32,8 +58,11 @@ export {
 export * as git from "./src/git";
 export { ClaudeCommitError } from "./src/errors";
 export type {
+  ChangePriority,
   Config,
+  DiffSummary,
   ModelConfig,
+  OllamaConfig,
   PartialConfig,
   ModelResult,
   FileChange,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synmux/claude-commit",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Generate git commit messages with Claude, using your Claude Code subscription.",
   "main": "index.ts",
   "module": "index.ts",
@@ -16,36 +16,48 @@
     "index.ts"
   ],
   "claude-commit": {
+    "allowApiKey": false,
+    "charsPerToken": 3.5,
     "conventionalCommits": true,
-    "gitmoji": true,
-    "multiline": true,
-    "template": null,
     "customPrompt": null,
+    "gitmoji": true,
     "interactive": false,
-    "interactiveCount": 3,
+    "interactiveCount": 10,
     "interactiveTemperature": 1,
-    "spinner": "bouncingBall",
+    "lowPriorityPaths": [
+      ".agents/**",
+      ".claude/**",
+      "bun.lock",
+      ".serena"
+    ],
+    "maxChunkTokens": 1000000,
     "models": {
-      "summary": "sonnet",
-      "final": "sonnet"
+      "summary": "fable",
+      "final": "fable"
     },
-    "maxChunkTokens": 600000,
-    "charsPerToken": 3.5,
-    "allowApiKey": false
+    "multiline": true,
+    "ollama": {
+      "host": "http://localhost:11434",
+      "context": "auto",
+      "keepAlive": "10m"
+    },
+    "skipArmored": true,
+    "spinner": "pong",
+    "template": null
   },
   "devDependencies": {
-    "@anthropic-ai/claude-code": "^2.1.218",
+    "@anthropic-ai/claude-code": "^2.1.241",
     "@trunkio/launcher": "^1.3.4",
-    "@types/bun": "^1.3.14",
+    "@types/bun": "^1.4.0",
     "prettier": "3.9.4",
-    "skilld": "^2.0.0"
+    "skilld": "^2.3.0"
   },
   "peerDependencies": {
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.218",
-    "@opentui/core": "^0.4.5",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.241",
+    "@opentui/core": "^0.5.7",
     "cli-spinners": "^3.4.0",
     "commander": "^15.0.0",
     "ora": "^9.4.1"

package/src/agent.ts

@@ -1,6 +1,13 @@
 /**
- * Thin wrapper around the Claude Agent SDK that turns a single prompt into a
- * single text completion.
+ * The model-call layer: {@link runPrompt} turns one prompt into one text
+ * completion, routing to whichever backend the model name asks for.
+ *
+ * A bare model name goes to Claude, through the Agent SDK, below. An
+ * `ollama:`-prefixed one goes to `src/ollama.ts` instead. Both return the
+ * same {@link ModelResult}, so the pipeline in `src/generate.ts` - and the
+ * injectable runner its tests use - never learns which provider ran.
+ *
+ * The Claude path, in detail:
  *
  * The Agent SDK spawns a bundled `claude` binary, so authentication follows
  * Claude Code's own resolution order over the environment we hand it. By
@@ -19,47 +26,12 @@ import {
   type SDKMessage,
 } from "@anthropic-ai/claude-agent-sdk";
 import { ClaudeCommitError } from "./errors";
-import type { ModelResult } from "./types";
+import { parseModelRef } from "./models";
+import { runOllamaPrompt } from "./ollama";
+import type { ModelResult, RunPromptOptions } from "./types";
 
-export interface RunPromptOptions {
-  /** Model string (alias like `sonnet`, `haiku`, 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;
-}
+export type { RunPromptOptions } from "./types";
 
-/**
- * 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",
@@ -195,11 +167,11 @@ export function buildQueryOptions(
 }
 
 /**
- * Run a single prompt and return the model's text response.
+ * Run a single prompt against a Claude model via the Agent SDK.
  *
  * Throws {@link ClaudeCommitError} on any model/authentication/quota failure.
  */
-export async function runPrompt(
+export async function runClaudePrompt(
   prompt: string,
   opts: RunPromptOptions,
 ): Promise<ModelResult> {
@@ -285,3 +257,24 @@ export async function runPrompt(
     ...(structured !== undefined ? { structured } : {}),
   };
 }
+
+/**
+ * Run a single prompt against whichever provider `opts.model` names, and
+ * return its text response.
+ *
+ * This is the single seam every caller uses; `generate.ts` accepts a
+ * replacement of exactly this shape so the pipeline can be tested without a
+ * model of either kind.
+ *
+ * Throws {@link ClaudeCommitError} on any model, authentication, transport
+ * or quota failure.
+ */
+export async function runPrompt(
+  prompt: string,
+  opts: RunPromptOptions,
+): Promise<ModelResult> {
+  const { provider } = parseModelRef(opts.model);
+  return provider === "ollama"
+    ? runOllamaPrompt(prompt, opts)
+    : runClaudePrompt(prompt, opts);
+}