Every AI commit tool generates a message, calls git commit, and dies on hook failure. commit-mint parses the failure, hands you a recovery menu (copy errors to clipboard, skip hooks, re-stage and retry), and caches the message so cmint -r resumes exactly where you stopped.

cmint runs your pre-commit checks, generates a conventional commit message with AI, attempts the commit, and on failure shows a recovery menu with the parsed error report ready to paste into a coding agent.

Quick Start

npm install -g @kyubiware/commit-mint

cmint config  # set your API key and preferred provider

cmint # interactive cli for committing changes

Why commit-mint?

• Checks run before the AI call. A failing check short-circuits before any API call. With lint-staged, the hook fires after the message is already finalized — a broken check wastes the message.
• Failures get a recovery menu, not raw stderr. Output from biome, tsc, vitest/jest, eslint, and lint-staged is parsed into structured errors and presented in a 6-option menu.
• Live retry. Fix the error in another terminal, pick "Retry checks" in the menu — no need to exit and re-run cmint.
• Auto-group mode. Ten changed files across three concerns become three commits, each with its own AI-generated message.
• Message caching on failure. Cached to ~/.cache/commit-mint/. cmint -r re-attempts with the same message after you fix the underlying issue.

Comparison

Command Reference

cmint             # interactive: stage → checks → review → commit
cmint -a          # auto-group, generate messages, commit everything
cmint -a 3        # auto-group into exactly 3 commits
cmint -s          # stage all tracked files in single commit, skip staging menu
cmint config      # edit provider, model, locale, etc.
cmint update      # update cmint to the latest published version

Pre-flight Checks (.cmintrc)

.cmintrc is commit-mint's pre-commit check system. The config syntax is identical to lint-staged — glob keys mapping to shell commands — but the checks run inside commit-mint's flow, not as a separate git hook.

Already using lint-staged? Rename your config file to .cmintrc — same syntax, no changes needed.

Run cmint config to auto-generate one, or create it manually:

// .cmintrc.ts
export default {
    "*.{js,ts,json}": "biome check --write --no-errors-on-unmatched --error-on-warnings",
    "*.ts": () => ["tsc --noEmit", "vitest run --passWithNoTests", "npm run build"],
};

(This is the actual .cmintrc.ts commit-mint ships with for its own development.)

When a check fails:

Pre-commit check failed
  • [biome] src/services/ai.ts:12:1 lint/suspicious/noExplicitAny — Unexpected any...
  • [tsc] src/services/ai.ts:55:18 — error TS2345: Argument of type 'string' is...

What do you want to do?
  Copy error report to clipboard
  View full error output
  Retry checks
  Skip checks and commit
  Cancel

• Copy error report — copies the raw stderr to clipboard (formatted for an AI agent).
• View full error output — shows the raw stderr.
• Retry checks — re-runs the same checks. Fix in another terminal, hit enter, no restart.
• Skip checks and commit — proceed to commit despite the failure.
• Cancel — exit. The message is cached so cmint -r re-attempts with the same message.

For tsc failures specifically, the summary includes up to 3 file:line:column diagnostics inline, with a +N more line if there are more.

Config shape, file name patterns, and glob matching rules are documented in the API Reference.

Recovery Menu

When a git hook blocks the commit, commit-mint parses the output and shows:

Pre-commit hook failed
  • [biome] src/cli.ts — unused variable
  • [vitest] 1 test failed in test/cli.test.ts

What do you want to do?
  Copy error report to clipboard
  View full error output
  Skip hooks and commit (--no-verify)
  Re-stage files and retry
  Edit commit message
  Cancel

Six options, none are dead ends:

• Copy error report — raw stderr to clipboard, formatted for an AI agent.
• View full error output — show the unparsed stderr in a note.
• Skip hooks — commit with --no-verify. Use when the failure is understood and not worth blocking on.
• Re-stage — git add -A, retry the commit. Picks up fixes you make in another terminal without restarting cmint. If re-stage still fails, the menu re-shows the errors.
• Edit — tweak the AI message, then retry.
• Cancel — exit. The message is cached; cmint -r re-attempts with the same message after you fix the underlying issue.

Hook progress is shown in real time during the commit — [STARTED] / [COMPLETED] / [FAILED] markers from each task are streamed to stderr as they happen.

Errors are parsed from lint-staged, biome, tsc, vitest/jest, and eslint. Unrecognized output falls back to a single raw-stderr entry.

API Reference

Subcommands

Flags

Config Keys

Stored in ~/.commit-mint (INI format). Run cmint config to edit.

API key lookup checks the env var first, then the INI file.

Environment Variables

Providers

All three use OpenAI-compatible APIs and have a generous free tier. Per- provider model overrides: set model_groq, model_cerebras, or model_mistral in ~/.commit-mint. Resolution order is model_<provider> → model → provider default.

Pre-flight Check Config

File names

Checked in this order. First match wins.

.cmintrc
.cmintrc.json
.cmintrc.mjs
.cmintrc.mts
.cmintrc.js
.cmintrc.ts
.cmintrc.cjs
.cmintrc.cts
cmint.config.mjs
cmint.config.mts
cmint.config.js
cmint.config.ts
cmint.config.cjs
cmint.config.cts

.ts/.cts/.cjs are loaded via jiti — use TypeScript syntax freely. .json is parsed as plain JSON. Everything else is loaded as ESM with import default.

Shape

A default export. Each key is a picomatch glob; each value is a command string, a string array, or a function that returns either.

String command:

export default {
    "*.ts": "eslint --fix", // runs `eslint --fix src/foo.ts src/bar.ts`
};

String array:

export default {
    "*.ts": ["eslint --fix", "prettier --write"],
};

Function command:

export default {
    "*.ts": (files) =>
        files.length > 5 ? `vitest run ${files.join(" ")}` : "vitest run",
};

Glob matching

• Globs without a / match at any depth (e.g. *.ts matches src/foo.ts and a/b/c.ts).
• Dotfiles are included.
• Paths with spaces are quoted before being appended.

Behavior

• Checks run after git add, before the AI call.
• Globs are processed in declaration order.
• Commands run sequentially per glob. All commands and all globs always run; failures are collected and returned together.
• 60s timeout per command. ENOENT (command not found) and timeouts are reported back to the menu as their own error.
• Skipped entirely with cmint -N or the c hotkey toggle.

Exit Codes

cmint --agent uses 7 documented exit codes. Interactive cmint always exits with 0 or 1.

Agent JSON Output Schema

The command returns a single JSON object to stdout. See the Agent Flow section for invocation patterns.

type AgentResult = {
    status: "success" | "no_changes" | "failure" | "cancelled";
    commits: Array<{
        message: string;
        hash: string;
        files: string[];
        groupName?: string;
    }>;
    errors?: string[];
};

Excluded Files

These patterns are filtered from AI generation by default:

package-lock.json
node_modules/**  dist/**  build/**  .next/**  coverage/**
*.log  *.min.js  *.min.css  *.lock  .DS_Store

When every staged file matches an exclude, commit-mint uses a hardcoded message: chore: update lockfile for lockfiles, chore: update generated files for the rest. In auto-group mode, lockfiles (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock, bun.lockb) are promoted alongside their companion manifest (e.g. package-lock.json stays with package.json).

Debug Logs

cmint --debug streams timestamped log lines to stderr. The same log is persisted to ~/.cache/commit-mint/debug.log with a --- session <ISO timestamp> --- header on every CLI invocation.

View the last session's log:

cmint logs              # entire last session
cmint logs -n 50        # last 50 lines

Requirements

• Node.js 18+
• git
• One of: GROQ_API_KEY, CEREBRAS_API_KEY, or MISTRAL_API_KEY (or run cmint config to set one)
• Optional, for clipboard copy: wl-copy, xclip, xsel, or pbcopy

Support

• GitHub Issues — bug reports and feature requests
• GitHub Discussions — questions and ideas
• npm — releases and install stats

Built With

• TypeScript — strict, ESM-only, tsdown bundler
• @clack/prompts + kolorist — interactive TUI primitives
• cleye — CLI argument parsing
• execa — subprocess execution with clean stderr capture
• groq-sdk — official Groq client
• picomatch — glob matching
• jiti — TypeScript config loader
• ini — INI config parsing
• semver — version comparison for cmint update

AI Agent Skill

If you're an AI coding agent, this section is for you.

Install commit-mint as a skill in OpenCode, Cursor, or any agent that loads npm skills:

npx skills add kyubiware/commit-mint

The skill teaches the agent the non-interactive agent flow:

1. Run cmint --agent (or cmint --agent --noCheck to skip pre-commit checks).
2. Parse the JSON AgentResult from stdout.
3. Read the process.exitCode against the Exit Codes table.

The agent never has to interact with the recovery menu — failures are surfaced as status: "failure" with an errors[] array, or one of the --agent-specific exit codes (3 = git, 4 = AI, 5 = check, 6 = hook).

For OpenCode, the skill is also shipped with the project at skills/cmint/SKILL.md.

License

MIT