{"id":31825177,"url":"https://github.com/kud/ai-conventional-commit-cli","last_synced_at":"2026-01-20T17:52:34.540Z","repository":{"id":318654175,"uuid":"1051278975","full_name":"kud/ai-conventional-commit-cli","owner":"kud","description":"AI‑assisted, style‑aware Conventional Commit generator \u0026 splitter. Opinionated CLI that learns your repo's commit style and produces polished single or multi commits – safely, quickly, repeatably. ","archived":false,"fork":false,"pushed_at":"2025-10-08T13:14:21.000Z","size":150,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-08T13:33:00.180Z","etag":null,"topics":["ai","cli","git","npm"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@kud/ai-conventional-commit-cli","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kud.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-05T18:11:00.000Z","updated_at":"2025-10-08T13:14:25.000Z","dependencies_parsed_at":"2025-10-08T13:33:06.035Z","dependency_job_id":null,"html_url":"https://github.com/kud/ai-conventional-commit-cli","commit_stats":null,"previous_names":["kud/ai-conventional-commit-cli"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/kud/ai-conventional-commit-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kud%2Fai-conventional-commit-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kud%2Fai-conventional-commit-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kud%2Fai-conventional-commit-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kud%2Fai-conventional-commit-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kud","download_url":"https://codeload.github.com/kud/ai-conventional-commit-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kud%2Fai-conventional-commit-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279007615,"owners_count":26084336,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-11T02:00:06.511Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cli","git","npm"],"created_at":"2025-10-11T15:51:33.462Z","updated_at":"2026-01-20T17:52:34.527Z","avatar_url":"https://github.com/kud.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ai-conventional-commit\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eAI‑assisted, style‑aware Conventional Commit generator \u0026 splitter\u003c/b\u003e\u003cbr/\u003e\n  Opinionated CLI that learns your repo's commit style and produces polished single or multi commits – safely, quickly, repeatably.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@kud/ai-conventional-commit-cli\"\u003e\u003cimg alt=\"npm version\" src=\"https://img.shields.io/npm/v/%40kud%2Fai-conventional-commit-cli?color=brightgreen\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@kud/ai-conventional-commit-cli\"\u003e\u003cimg alt=\"downloads\" src=\"https://img.shields.io/npm/dm/%40kud%2Fai-conventional-commit-cli\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"license\" src=\"https://img.shields.io/npm/l/%40kud%2Fai-conventional-commit-cli\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org\"\u003e\u003cimg alt=\"node version\" src=\"https://img.shields.io/node/v/%40kud%2Fai-conventional-commit-cli\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.conventionalcommits.org\"\u003e\u003cimg alt=\"Conventional Commits\" src=\"https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e TL;DR: Stage your changes, run `ai-conventional-commit` (or `split` for multiple commits), accept, done. Add `--style gitmoji` if you like emoji. Refine later with `refine`.\n\n---\n\n## Table of Contents\n\n- [Why](#why)\n- [Features](#features)\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [Command Reference](#command-reference)\n- [Examples](#examples)\n- [Gitmoji Modes](#gitmoji-modes)\n- [Privacy Modes](#privacy-modes)\n- [Configuration](#configuration-aiccrc)\n- [Refinement Workflow](#refinement-workflow)\n- [Plugin API](#plugin-api)\n- [Title Formatting Helper](#title-formatting-helper)\n- [Security](#security)\n- [Roadmap Ideas](#roadmap-ideas)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Why\n\nManual commit messages are often noisy, inconsistent, and context‑poor. This tool:\n\n- Learns _your_ recent commit style (length, scopes, emoji, prefixes)\n- Respects Conventional Commits \u0026 normalizes edge cases\n- Proposes **multi‑commit splits** when changes are logically separable\n- Lets you iteratively refine wording – without rewriting history prematurely\n\n## Features\n\n| Category           | Highlights                                                               |\n| ------------------ | ------------------------------------------------------------------------ |\n| Style Intelligence | Style fingerprint (avg length, scope ratio, gitmoji usage, top prefixes) |\n| Generation Modes   | Single, multi‑commit planning (`split`), iterative refinement (`refine`) |\n| Commit Splitting   | Real selective staging per proposed commit (no fake plan output)         |\n| Gitmoji            | Standard / emoji+type / pure emoji modes                                 |\n| Guardrails         | Title normalization, Conventional syntax enforcement, length checks      |\n| Privacy            | Tiered diff detail (low / medium / high)                                 |\n| Plugins            | Transform \u0026 validate hooks over candidates                               |\n| Determinism        | Mock provider for CI \u0026 tests (`AICC_DEBUG_PROVIDER=mock`)                |\n| UX                 | Timing output, scoped prompts, animated header (optional)                |\n\n## Install\n\nGlobal (recommended for daily use):\n\n```bash\nnpm install -g @kud/ai-conventional-commit-cli\n```\n\nLocal + npx:\n\n```bash\nnpm install --save-dev @kud/ai-conventional-commit-cli\nnpx ai-conventional-commit --help\n```\n\nFrom source (dev):\n\n```bash\nnpm install\nnpm run build\nnpm link\nai-conventional-commit --help\n```\n\nOptional shell alias:\n\n```bash\nalias aicc='ai-conventional-commit'\n```\n\n## Quick Start\n\n```bash\n# Stage changes\ngit add .\n\n# Generate a single commit suggestion\nai-conventional-commit\n\n# Auto-confirm without prompting (useful for automation)\nai-conventional-commit --yes\n\n# Propose multiple commits (interactive confirm + real selective staging)\nai-conventional-commit split\n\n# Add emoji decorations (gitmoji)\nai-conventional-commit --style gitmoji\n\n# Pure emoji style (emoji: subject)\nai-conventional-commit --style gitmoji-pure\n\n# Refine previous session's first commit (shorter wording)\nai-conventional-commit refine --shorter\n\n# Reword an existing commit (picker)\nai-conventional-commit reword\n\n# Reword HEAD directly (auto-amend)\nai-conventional-commit reword HEAD\n```\n\n## Command Reference\n\n### Reword Existing Commit\n\nReword (improve) the message of an existing non-merge commit without touching its diff.\n\n```\n# Interactive picker (last 20 commits)\nai-conventional-commit reword\n\n# Reword HEAD (auto-amend)\nai-conventional-commit reword HEAD\n\n# Reword older commit (shows interactive rebase instructions)\nai-conventional-commit reword \u003chash\u003e\n\n# With style/model overrides\nai-conventional-commit reword \u003chash\u003e --style gitmoji -m github-copilot/gpt-4.1\n```\n\nNotes:\n\n- Merge commits (multiple parents) are rejected.\n- If target is HEAD and accepted, the commit is amended in-place.\n- If not HEAD, printed instructions guide you through `git rebase -i --reword`.\n- Title formatting (gitmoji, normalization) matches other commands.\n\n| Command                              | Purpose                                     |\n| ------------------------------------ | ------------------------------------------- |\n| `ai-conventional-commit`             | Generate single commit suggestion (default) |\n| `ai-conventional-commit generate`    | Explicit alias of root                      |\n| `ai-conventional-commit split`       | Propose \u0026 execute multiple commits          |\n| `ai-conventional-commit refine`      | Refine last session (or indexed) commit     |\n| `ai-conventional-commit reword`      | AI-assisted reword of existing commit       |\n| `ai-conventional-commit models`      | List / pick models, save default            |\n| `ai-conventional-commit config show` | Show merged config + sources                |\n| `ai-conventional-commit config get`  | Get a single config value                   |\n| `ai-conventional-commit config set`  | Persist a global config value               |\n\nHelpful flags:\n\n- `--style \u003cstandard|gitmoji|gitmoji-pure\u003e`\n- `--model \u003cprovider/name\u003e` (override)\n- `-y, --yes` (auto-confirm without prompting)\n- `--scope \u003cscope\u003e` (refine)\n- `--shorter` / `--longer`\n\n## Examples\n\n### Single Commit (standard)\n\n```\nfeat(api): add pagination metadata to list endpoint\n\nAdds `total`, `limit`, `offset` fields to response; updates tests.\n```\n\n### Split Workflow (illustrative)\n\n```\n1. refactor(parser): simplify token scanning (no behavior change)\n2. feat(parser): support negated glob segments\n3. test(parser): add cases for brace + extglob combos\n```\n\nEach proposed commit is _actually_ staged \u0026 committed with only its files.\n\n### Refinement\n\n```\n$ ai-conventional-commit refine --scope cli --shorter\n✔ Updated: feat(cli): add split timing output\n```\n\n## Gitmoji Modes\n\n| Mode         | Example                   | Notes                                |\n| ------------ | ------------------------- | ------------------------------------ |\n| standard     | `feat: add search box`    | No emoji                             |\n| gitmoji      | `✨ feat: add search box` | Emoji + type retained                |\n| gitmoji-pure | `✨: add search box`      | Type removed; emoji acts as category |\n\nEnable via CLI flag `--style gitmoji|gitmoji-pure` or config `\"style\": \"gitmoji\"` / `\"style\": \"gitmoji-pure\"`.\n\n## Privacy Modes\n\n| Mode   | Data Sent                                              |\n| ------ | ------------------------------------------------------ |\n| low    | Hunk headers + first 40 changed/context lines per hunk |\n| medium | File + hunk hash + line counts + function context only |\n| high   | File names + aggregate add/remove counts only          |\n\nPick based on sensitivity; higher privacy may reduce stylistic richness.\n\n## Configuration (.aiccrc)\n\nResolves via cosmiconfig (JSON/YAML/etc). Example:\n\n```json\n{\n  \"model\": \"github-copilot/gpt-4.1\",\n  \"privacy\": \"low\",\n  \"style\": \"gitmoji\",\n  \"styleSamples\": 120,\n  \"plugins\": [\"./src/sample-plugin/example-plugin.ts\"],\n  \"maxTokens\": 512,\n  \"maxFileLines\": 1000,\n  \"skipFilePatterns\": [\n    \"**/package-lock.json\",\n    \"**/yarn.lock\",\n    \"**/*.d.ts\",\n    \"**/dist/**\"\n  ]\n}\n```\n\n### Configuration Options\n\n- **`maxFileLines`** (default: 1000): Skip file content in AI prompt if diff line count exceeds this threshold (per file). Files are still committed - the AI just sees the filename and stats instead of full content. Helps avoid token overflow from extremely large files.\n\n- **`skipFilePatterns`** (default: see below): Glob patterns for files whose content should be skipped in the AI prompt but still committed. Useful for generated files, lock files, and build artifacts.\n\n  **Default patterns:**\n  - Lock files: `**/package-lock.json`, `**/yarn.lock`, `**/pnpm-lock.yaml`, `**/bun.lockb`, `**/composer.lock`, `**/Gemfile.lock`, `**/Cargo.lock`, `**/poetry.lock`\n  - TypeScript declarations: `**/*.d.ts`\n  - Build output: `**/dist/**`, `**/build/**`, `**/.next/**`, `**/out/**`, `**/coverage/**`\n  - Minified files: `**/*.min.js`, `**/*.min.css`, `**/*.map`\n\n  To override, provide your own array in config. To disable entirely, set to `[]`.\n\nEnvironment overrides (prefix `AICC_`):\n\n### Configuration Precedence\n\nLowest to highest (later wins):\n\n1. Built-in defaults\n2. Global config file: `~/.config/ai-conventional-commit-cli/aicc.json` (or `$XDG_CONFIG_HOME`)\n3. Project config (.aiccrc via cosmiconfig)\n4. Environment variables (`AICC_*`)\n5. CLI flags (e.g. `--model`, `--style`)\n\nView the resolved configuration:\n\n```bash\nai-conventional-commit config show\nai-conventional-commit config show --json | jq\n```\n\nManage models:\n\n```bash\nai-conventional-commit models               # list (opencode pass-through)\nai-conventional-commit models --interactive      # interactive picker\nai-conventional-commit models --interactive --save # pick + persist globally\nai-conventional-commit models --current     # show active model + source\n```\n\n`MODEL`, `PRIVACY`, `STYLE`, `STYLE_SAMPLES`, `MAX_TOKENS`, `MAX_FILE_LINES`, `VERBOSE`, `YES`, `MODEL_TIMEOUT_MS`, `DEBUG`, `PRINT_LOGS`, `DEBUG_PROVIDER=mock`.\n\n**Note:** `skipFilePatterns` cannot be set via environment variable - use config file or accept defaults.\n\n## Refinement Workflow\n\n1. Generate (`ai-conventional-commit` or `split`) – session cached under `.git/.aicc-cache/last-session.json`.\n2. Run `refine` with flags (`--shorter`, `--longer`, `--scope=ui`).\n3. Accept or reject; refined output does _not_ auto‑amend history until you use it.\n\n## Plugin API\n\n```ts\ninterface PluginContext {\n  cwd: string;\n  env: NodeJS.ProcessEnv;\n}\ninterface Plugin {\n  name: string;\n  transformCandidates?(\n    candidates: CommitCandidate[],\n    ctx: PluginContext,\n  ): CommitCandidate[] | Promise\u003cCommitCandidate[]\u003e;\n  validateCandidate?(\n    candidate: CommitCandidate,\n    ctx: PluginContext,\n  ): string | string[] | void | Promise\u003cstring | string[] | void\u003e;\n}\n```\n\nRegister via `plugins` array. `transform` runs once over the candidate list; `validate` runs per chosen candidate before commit.\n\n### Example Plugin (lightweight scope normalizer)\n\n```ts\nexport default {\n  name: 'scope-normalizer',\n  transformCandidates(cands) {\n    return cands.map((c) =\u003e ({\n      ...c,\n      title: c.title.replace('(UI)', '(ui)'),\n    }));\n  },\n};\n```\n\n## Title Formatting Helper\n\nAll gitmoji + normalization logic: `src/title-format.ts` (`formatCommitTitle`). Tested in `test/title-format.test.ts`.\n\n## Security\n\nLightweight heuristic secret scan of commit body (add/removed lines) – not a substitute for dedicated scanners (e.g. gitleaks). Pair with your existing pipelines.\n\n## Roadmap Ideas\n\n- Embedding-based semantic clustering\n- Local model (Ollama) fallback\n- Streaming / partial UI updates\n- Commit plan editing (accept subset, re-cluster)\n- Scope inference heuristics\n- Extended secret scanning\n\n## Contributing\n\nPRs welcome. Please:\n\n- Keep dependencies minimal\n- Add tests for new formatting or parsing logic\n- Feature‑flag experimental behavior\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkud%2Fai-conventional-commit-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkud%2Fai-conventional-commit-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkud%2Fai-conventional-commit-cli/lists"}