@synmux/claude-commit 0.1.4 → 1.0.0

package/README.md

@@ -157,6 +157,7 @@ keys are valid at every level:
   },
   "maxChunkTokens": 600000,
   "charsPerToken": 3.5,
+  "skipArmored": false,
   "allowApiKey": false
 }
 ```
@@ -167,6 +168,23 @@ current Sonnet/Opus keep the full budget; Haiku, older pinned model ids, and
 unrecognised models are floored at 200k), so a single chunk can never overflow
 the model.
 
+Chunk sizes come from a content-classified token estimate, not a flat
+`charsPerToken` ratio: armored or encoded lines (age/gpg armor, base64 blobs,
+git binary patches) tokenize at roughly **one token per character** on current
+Claude models, so they are budgeted at that rate while ordinary text keeps the
+configured ratio. If the backend still rejects a chunk as too long, cco
+re-splits just that chunk with a halved budget and retries - the rejection is
+free, so the API is the final arbiter.
+
+`skipArmored` (or the `--skip-armored` flag) goes further and replaces each
+run of armored lines with a one-line `[cco: N armored/encoded lines omitted]`
+marker before summarizing. Ciphertext is unreadable to the model anyway, so
+this is the recommended setting for encrypted-file repos - for example a
+[chezmoi](https://www.chezmoi.io) source directory with age encryption, where
+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.
+
 ## Development
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synmux/claude-commit",
-  "version": "0.1.4",
+  "version": "1.0.0",
   "description": "Generate git commit messages with Claude, using your Claude Code subscription.",
   "main": "index.ts",
   "module": "index.ts",
@@ -40,7 +40,7 @@
     "skilld": "^2.0.0"
   },
   "peerDependencies": {
-    "typescript": "^7.0.2"
+    "typescript": "^6.0.3"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.218",

package/src/agent.ts

@@ -163,9 +163,14 @@ function describeAssistantError(code: string): string {
  *   even when the `skills` option is omitted entirely.
  * - `tools: []` and `plugins: []` drop all built-in tools and plugins.
  *
- * Omitting any of these leaks the user's global Claude Code configuration
- * into the request - observed at ~850k tokens of MCP tool definitions, which
- * overflows the context window before the diff is even counted.
+ * Omitting any of these lets the user's global Claude Code configuration
+ * (MCP tool schemas, skill listings - easily hundreds of thousands of tokens
+ * on a busy setup) into every request; with all of them set, live probes
+ * measure ~170 input tokens per request. Historical note: the 2026-07
+ * "Prompt is too long" failures were ultimately caused by underestimating
+ * the token density of armored diff content (see `estimateDiffTokens`), not
+ * by this leak - the isolation is hygiene and cost control, not the fix for
+ * that bug.
  */
 export function buildQueryOptions(
   opts: RunPromptOptions,

package/src/cli.ts

@@ -39,6 +39,7 @@ interface CliOptions {
   spinner?: boolean;
   config?: string;
   verbose?: boolean;
+  skipArmored?: boolean;
 }
 
 function buildProgram(): Command {
@@ -72,6 +73,11 @@ function buildProgram(): Command {
     .option("-p, --prompt <text>", "extra instructions appended to the prompt")
     .option("--model-summary <model>", "model used to summarize the diff")
     .option("--model-final <model>", "model used to write the final message")
+    .option(
+      "--skip-armored",
+      "omit armored/encoded lines (age/gpg armor, base64 blobs) from the " +
+        "summarized diff; recommended for chezmoi-style encrypted repos",
+    )
     .option("-d, --dry-run", "print the message to stdout without committing")
     .option("-y, --yes", "commit without asking for confirmation")
     .option("--no-spinner", "disable the progress spinner")
@@ -106,6 +112,7 @@ function flagsToConfig(opts: CliOptions): PartialConfig {
   if (opts.interactive !== undefined) cfg.interactive = opts.interactive;
   if (opts.template !== undefined) cfg.template = opts.template;
   if (opts.prompt !== undefined) cfg.customPrompt = opts.prompt;
+  if (opts.skipArmored !== undefined) cfg.skipArmored = opts.skipArmored;
   if (opts.count !== undefined && Number.isFinite(opts.count)) {
     cfg.interactiveCount = Math.max(1, opts.count);
   }

package/src/config.ts

@@ -27,6 +27,7 @@ export const DEFAULT_CONFIG: Config = {
   },
   maxChunkTokens: 600_000,
   charsPerToken: 3.5,
+  skipArmored: false,
   allowApiKey: false,
 };
 
@@ -90,6 +91,7 @@ export function sanitizePartial(raw: unknown): PartialConfig {
   bool("gitmoji");
   bool("multiline");
   bool("interactive");
+  bool("skipArmored");
   bool("allowApiKey");
 
   if (typeof obj.template === "string") out.template = obj.template;

package/src/diff.ts

@@ -8,6 +8,8 @@
  * every piece so each chunk remains a self-contained, interpretable diff.
  */
 
+import { estimateDiffTokens, isOpaqueLine } from "./tokens";
+
 const FILE_HEADER = "diff --git ";
 const HUNK_HEADER = "@@";
 
@@ -152,3 +154,93 @@ export function splitDiff(diff: string, maxChars: number): string[] {
   }
   return packUnits(units, maxChars);
 }
+
+/** Character budget for `text` such that its classified token estimate fits `maxTokens`. */
+function charBudgetFor(
+  text: string,
+  maxTokens: number,
+  charsPerToken: number,
+): number {
+  const density =
+    text.length / Math.max(1, estimateDiffTokens(text, charsPerToken));
+  return Math.max(1, Math.floor(maxTokens * density));
+}
+
+/**
+ * Split a diff so that every chunk's *classified token estimate* fits
+ * `maxTokens`.
+ *
+ * `splitDiff` budgets in characters, but token density varies wildly by
+ * content: prose and code sit near the configured `charsPerToken` (~3.5)
+ * while base64/armor lines measure near 1 char/token. Sizing every chunk
+ * with one blended ratio lets an armor-heavy region overflow, so after an
+ * initial blended-density split, any chunk still over budget is re-split
+ * using its own (denser) ratio until everything fits or no further split is
+ * possible. An unsplittable oversized chunk is kept - the overflow retry in
+ * the generation pipeline is the backstop for that case.
+ */
+/**
+ * Minimum consecutive opaque lines before a run is redacted. A lone long
+ * unbroken line (a URL, a hash pin, a long path) can carry real meaning; an
+ * armored blob never arrives alone.
+ */
+const MIN_REDACT_RUN = 3;
+
+/**
+ * Replace each run of opaque (armored/encoded) lines with a single marker
+ * line. The marker keeps the surrounding diff structure interpretable and
+ * tells the summary model what was elided, so it can still report that an
+ * encrypted file changed - without paying ~1 token per character to send
+ * ciphertext the model cannot read anyway.
+ */
+export function redactOpaqueRuns(diff: string): string {
+  const out: string[] = [];
+  let run: string[] = [];
+  const flush = () => {
+    if (run.length >= MIN_REDACT_RUN) {
+      out.push(`[cco: ${run.length} armored/encoded lines omitted]`);
+    } else {
+      out.push(...run);
+    }
+    run = [];
+  };
+  for (const line of diff.split("\n")) {
+    if (isOpaqueLine(line)) {
+      run.push(line);
+    } else {
+      flush();
+      out.push(line);
+    }
+  }
+  flush();
+  return out.join("\n");
+}
+
+export function splitDiffToFit(
+  diff: string,
+  maxTokens: number,
+  charsPerToken: number,
+): string[] {
+  const queue = splitDiff(diff, charBudgetFor(diff, maxTokens, charsPerToken));
+  const fitted: string[] = [];
+  while (queue.length > 0) {
+    const chunk = queue.shift()!;
+    if (estimateDiffTokens(chunk, charsPerToken) <= maxTokens) {
+      fitted.push(chunk);
+      continue;
+    }
+    // Over budget: the chunk's own density is at least as dense as the
+    // blend it was sized with, so this budget is strictly smaller than the
+    // chunk - splitDiff will attempt a real split.
+    const pieces = splitDiff(
+      chunk,
+      charBudgetFor(chunk, maxTokens, charsPerToken),
+    );
+    if (pieces.length <= 1) {
+      fitted.push(chunk);
+      continue;
+    }
+    queue.unshift(...pieces);
+  }
+  return fitted;
+}

package/src/errors.ts

@@ -2,3 +2,14 @@
 export class ClaudeCommitError extends Error {
   override name = "ClaudeCommitError";
 }
+
+/**
+ * True when `error` is the backend rejecting a request for exceeding the
+ * model's context window. Matched on message text because the Agent SDK
+ * surfaces the rejection only as an error string. Used to trigger a
+ * re-split-and-retry: the rejection happens before the model runs, so it is
+ * not billed.
+ */
+export function isPromptTooLongError(error: unknown): boolean {
+  return error instanceof Error && /prompt is too long/i.test(error.message);
+}

package/src/generate.ts

@@ -5,14 +5,18 @@
  *        ──final model──▶ commit message(s)
  *
  * The summary model (default `sonnet`) reads each diff chunk and writes a
- * factual summary; chunking keeps each request within the model's context
- * window. The final model (default `sonnet`) turns the summaries into the commit
+ * factual summary; chunks are sized by a content-classified token estimate
+ * (`splitDiffToFit`) so each request fits the model's context window, and a
+ * chunk the backend still rejects as too long is re-split with a halved
+ * budget and retried - the rejection happens before the model runs and is
+ * not billed, so the API acts as the final arbiter of token counts. The
+ * final model (default `sonnet`) turns the summaries into the commit
  * message(s), applying the configured formatting rules.
  */
 import { runPrompt } from "./agent";
-import { splitDiff } from "./diff";
-import { clampChunkTokens, tokensToChars } from "./tokens";
-import { ClaudeCommitError } from "./errors";
+import { redactOpaqueRuns, splitDiffToFit } from "./diff";
+import { clampChunkTokens } from "./tokens";
+import { ClaudeCommitError, isPromptTooLongError } from "./errors";
 import {
   buildFinalSystem,
   buildFinalUser,
@@ -37,6 +41,12 @@ export interface GenerateOptions {
   count?: number;
   progress?: GenerateProgress;
   abortController?: AbortController;
+  /**
+   * Model runner used for every prompt; injectable so tests can exercise the
+   * pipeline (including overflow retries) without real model calls.
+   * Defaults to {@link runPrompt}.
+   */
+  runner?: typeof runPrompt;
 }
 
 export interface GenerateResult {
@@ -50,49 +60,100 @@ export interface GenerateResult {
   costUsd: number;
 }
 
+/**
+ * Floor for overflow-retry halving. Below this a chunk is essentially
+ * prompt-sized already, so a "prompt is too long" rejection indicates
+ * something other than chunk sizing and is surfaced instead of retried.
+ */
+const MIN_RETRY_CHUNK_TOKENS = 8_000;
+
 /** Run the full pipeline over a staged diff. */
 export async function generateCommit(
   diff: string,
   config: Config,
   options: GenerateOptions = {},
 ): Promise<GenerateResult> {
-  const { count = 1, progress = {}, abortController } = options;
+  const {
+    count = 1,
+    progress = {},
+    abortController,
+    runner = runPrompt,
+  } = options;
+
+  const effectiveDiff = config.skipArmored ? redactOpaqueRuns(diff) : diff;
 
   // The configured chunk budget is clamped to the summary model's context
   // window so a single chunk (plus prompt scaffolding and response headroom)
-  // can never overflow it, whatever `maxChunkTokens` says.
+  // can never overflow it, whatever `maxChunkTokens` says. Chunks are sized
+  // by a content-classified token estimate: opaque content (age/gpg armor,
+  // binary patches) measures near 1 char/token, so a plain chars-based
+  // budget underestimates armor-heavy diffs more than threefold.
   const chunkTokens = clampChunkTokens(
     config.models.summary,
     config.maxChunkTokens,
   );
-  const maxChars = tokensToChars(chunkTokens, config.charsPerToken);
-  const chunks = splitDiff(diff, maxChars);
+  const chunks = splitDiffToFit(
+    effectiveDiff,
+    chunkTokens,
+    config.charsPerToken,
+  );
   if (chunks.length === 0) {
     throw new ClaudeCommitError("There are no staged changes to summarize.");
   }
 
-  // Stage 1: summarize each chunk.
+  // Stage 1: summarize each chunk, via a work queue so an oversized chunk
+  // can be re-split and retried in place. The estimate is calibrated, but
+  // only the backend knows the true token count; its "prompt is too long"
+  // rejection is free, so treat it as the final arbiter: halve the budget,
+  // re-split just that chunk, and continue where we left off.
   const summarySystem = buildSummarySystem();
   const summaries: string[] = [];
   let costUsd = 0;
 
-  for (let i = 0; i < chunks.length; i++) {
+  const queue = chunks.map((chunk) => ({ chunk, tokenBudget: chunkTokens }));
+  while (queue.length > 0) {
+    const task = queue.shift()!;
+    const position = summaries.length;
+    const total = summaries.length + queue.length + 1;
     progress.onPhase?.(
-      chunks.length > 1
-        ? `Reading diff (part ${i + 1}/${chunks.length})`
+      total > 1
+        ? `Reading diff (part ${position + 1}/${total})`
         : "Reading diff",
     );
-    const result = await runPrompt(
-      buildSummaryUser(chunks[i]!, i, chunks.length),
-      {
-        model: config.models.summary,
-        system: summarySystem,
-        allowApiKey: config.allowApiKey,
-        ...(abortController ? { abortController } : {}),
-      },
-    );
-    summaries.push(result.text);
-    costUsd += result.costUsd;
+    try {
+      const result = await runner(
+        buildSummaryUser(task.chunk, position, total),
+        {
+          model: config.models.summary,
+          system: summarySystem,
+          allowApiKey: config.allowApiKey,
+          ...(abortController ? { abortController } : {}),
+        },
+      );
+      summaries.push(result.text);
+      costUsd += result.costUsd;
+    } catch (error) {
+      const halvedBudget = Math.floor(task.tokenBudget / 2);
+      if (
+        !isPromptTooLongError(error) ||
+        halvedBudget < MIN_RETRY_CHUNK_TOKENS
+      ) {
+        throw error;
+      }
+      const pieces = splitDiffToFit(
+        task.chunk,
+        halvedBudget,
+        config.charsPerToken,
+      );
+      if (pieces.length === 1 && pieces[0] === task.chunk) {
+        // Nothing left to split on (a single oversized hunk): retrying the
+        // identical request would loop forever, so surface the error.
+        throw error;
+      }
+      queue.unshift(
+        ...pieces.map((chunk) => ({ chunk, tokenBudget: halvedBudget })),
+      );
+    }
   }
 
   // Stage 2: write the commit message(s) from the summaries.
@@ -126,7 +187,7 @@ export async function generateCommit(
   let lastError: unknown;
   for (const attempt of attempts) {
     try {
-      const result = await runPrompt(
+      const result = await runner(
         buildFinalUser(summaries, count, attempt.structured),
         {
           ...baseOpts,
@@ -171,7 +232,14 @@ export async function generateCommit(
     throw new ClaudeCommitError("The model did not produce a commit message.");
   }
 
-  return { messages: deduped, summaries, chunkCount: chunks.length, costUsd };
+  // Report chunks actually processed: overflow retries can split further
+  // than the initial estimate planned.
+  return {
+    messages: deduped,
+    summaries,
+    chunkCount: summaries.length,
+    costUsd,
+  };
 }
 
 function dedupe(items: string[]): string[] {

package/src/tokens.ts

@@ -60,3 +60,50 @@ export function clampChunkTokens(
     contextWindowTokens(model) - CONTEXT_RESERVE_TOKENS,
   );
 }
+
+/**
+ * Chars-per-token for "opaque" content: base64/base85 armor (age, gpg, git
+ * binary patches), long hashes, and similar high-entropy runs. Measured
+ * against the live API on age-armor diff content (2026-07-23): ~1.14
+ * chars/token - the current Claude tokenizer finds almost no merges in
+ * random base64. Note that generic BPE vocabularies (tiktoken-class)
+ * compress base64 roughly 3x better, so swapping in a third-party "real"
+ * tokenizer would underestimate this content class just like a plain
+ * chars/3.5 heuristic does. 1.0 leaves a small safety margin under the
+ * measured value.
+ */
+export const OPAQUE_CHARS_PER_TOKEN = 1.0;
+
+/**
+ * A diff line whose content (after an optional one-character diff marker) is
+ * one long unbroken run with no whitespace - the signature of encoded blobs
+ * rather than prose or code. Misclassifying dense text (e.g. minified JS) as
+ * opaque merely over-reserves, which is the safe direction.
+ */
+const OPAQUE_LINE = /^[+\- ]?\S{40,}$/;
+
+/** Whether a single diff line should be estimated at the opaque ratio. */
+export function isOpaqueLine(line: string): boolean {
+  return OPAQUE_LINE.test(line);
+}
+
+/**
+ * Estimate tokens for diff text with per-line content classification:
+ * opaque lines at {@link OPAQUE_CHARS_PER_TOKEN}, everything else at the
+ * configured `charsPerToken`. A single blended ratio underestimates
+ * armor-heavy diffs more than threefold, which is exactly how a chunk that
+ * looks within budget can overflow the model's real context window.
+ */
+export function estimateDiffTokens(
+  text: string,
+  charsPerToken: number,
+): number {
+  if (charsPerToken <= 0) throw new Error("charsPerToken must be positive");
+  let tokens = 0;
+  for (const line of text.split("\n")) {
+    const lineChars = line.length + 1; // account for the newline
+    tokens +=
+      lineChars / (isOpaqueLine(line) ? OPAQUE_CHARS_PER_TOKEN : charsPerToken);
+  }
+  return Math.ceil(tokens);
+}

package/src/types.ts

@@ -49,6 +49,15 @@ export interface Config {
   maxChunkTokens: number;
   /** Approximate characters-per-token ratio used for chunk-size estimation. */
   charsPerToken: number;
+  /**
+   * Replace runs of armored/encoded diff lines (age/gpg armor, base64 blobs,
+   * git binary patch bodies) with a one-line `[... lines omitted]` marker
+   * before summarizing. Ciphertext is unreadable to the model and tokenizes
+   * at roughly one token per character, so skipping it makes commits in
+   * encrypted-file repos (e.g. chezmoi with age) fast and cheap without
+   * losing anything a summary could actually use.
+   */
+  skipArmored: boolean;
   /**
    * Allow API credentials from the environment (`ANTHROPIC_API_KEY` /
    * `ANTHROPIC_AUTH_TOKEN`) to be used, billing pay-as-you-go instead of the