{"_id":"@404-pf/commit-echo","_rev":"2-1807131f44b512bf7aed3f75cfa0237e","name":"@404-pf/commit-echo","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@404-pf/commit-echo","version":"0.1.0","keywords":["git","commit","cli","llm","ai"],"license":"MIT","_id":"@404-pf/commit-echo@0.1.0","maintainers":[{"name":"404-page-found","email":"Lucas20220605@gmail.com"}],"homepage":"https://github.com/404-PF/commit-echo#readme","bugs":{"url":"https://github.com/404-PF/commit-echo/issues"},"bin":{"commit-echo":"dist/index.js"},"dist":{"shasum":"dc1c68f1fda03324ab86f1517cf9a43b8e3d4aad","tarball":"https://registry.npmjs.org/@404-pf/commit-echo/-/commit-echo-0.1.0.tgz","fileCount":33,"integrity":"sha512-J+HZeKVWWPEWTn5lKsmL1rYbLDi1lj7iJ9JIelauwnaNwRUI1a9YLI4VlSY/KKh/K8+X6lLOx+hAwnpx2odQ+w==","signatures":[{"sig":"MEUCIDHeFW1gQ/9fo6506suenILaEJP5LmXCOhzuCFdUlbWFAiEAltLKFelfPsOCiKuoRnAH2pY9kYvFm0OTir6QFABDPyI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@404-pf%2fcommit-echo@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":83482},"type":"module","engines":{"node":">=24.0.0"},"exports":{".":"./dist/index.js"},"gitHead":"ef728b283589a420335ffbae961c9eebf3886b78","scripts":{"build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"404-page-found","email":"Lucas20220605@gmail.com"},"repository":{"url":"git+https://github.com/404-PF/commit-echo.git","type":"git"},"_npmVersion":"11.12.1","description":"LLM-powered CLI that learns your Git commit style and auto-suggests personalized commit messages","directories":{},"_nodeVersion":"24.15.0","dependencies":{"commander":"^13.1.0","picocolors":"^1.1.1","@clack/prompts":"^0.9.1"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^24.0.0"},"_npmOperationalInternal":{"tmp":"tmp/commit-echo_0.1.0_1779785688485_0.948823757094122","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@404-pf/commit-echo","version":"0.2.0","description":"LLM-powered CLI that learns your Git commit style and auto-suggests personalized commit messages","type":"module","bin":{"commit-echo":"dist/index.js"},"exports":{".":"./dist/index.js"},"engines":{"node":">=24.0.0"},"scripts":{"build":"tsc","test":"npm run build && node --test tests/**/*.test.mjs","prepublishOnly":"npm run build","start":"node dist/index.js","format":"prettier --write \"src/**/*.ts\"","format:check":"prettier --check \"src/**/*.ts\""},"keywords":["git","commit","cli","llm","ai"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/404-PF/commit-echo.git"},"publishConfig":{"access":"public","provenance":true},"dependencies":{"@clack/prompts":"^0.9.1","commander":"^13.1.0","picocolors":"^1.1.1"},"devDependencies":{"@types/node":"^24.0.0","prettier":"^3.8.3","typescript":"^5.7.0"},"gitHead":"e036c0f96307c4a5a3610d1a38a5781576b07d23","_id":"@404-pf/commit-echo@0.2.0","bugs":{"url":"https://github.com/404-PF/commit-echo/issues"},"homepage":"https://github.com/404-PF/commit-echo#readme","_nodeVersion":"24.18.0","_npmVersion":"11.16.0","dist":{"integrity":"sha512-kbBs1y3pwjHYPD3EVvY23yYl35nAxk/slGnQTLb8tdc5b2HSNH6E0o8B+il94rp6nWb3EFsWQmoHyL+Zil2LWg==","shasum":"63408bfb11082eafd214fc4b973fed91f9f109e4","tarball":"https://registry.npmjs.org/@404-pf/commit-echo/-/commit-echo-0.2.0.tgz","fileCount":47,"unpackedSize":262749,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@404-pf%2fcommit-echo@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC7Z7Bsqq7GOxOeMmzJecF0VsRZl9U6Xhba5eD87AC6xwIgOC2twlkmb+cMwMYRQYdWrAOWsL6CPmFpfUXSAnqMCnM="}]},"_npmUser":{"name":"404-page-found","email":"Lucas20220605@gmail.com"},"directories":{},"maintainers":[{"name":"404-page-found","email":"Lucas20220605@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/commit-echo_0.2.0_1783245374593_0.20627432360222708"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-26T08:54:48.327Z","modified":"2026-07-05T09:56:15.081Z","0.1.0":"2026-05-26T08:54:48.618Z","0.2.0":"2026-07-05T09:56:14.733Z"},"bugs":{"url":"https://github.com/404-PF/commit-echo/issues"},"license":"MIT","homepage":"https://github.com/404-PF/commit-echo#readme","keywords":["git","commit","cli","llm","ai"],"repository":{"type":"git","url":"git+https://github.com/404-PF/commit-echo.git"},"description":"LLM-powered CLI that learns your Git commit style and auto-suggests personalized commit messages","maintainers":[{"name":"404-page-found","email":"Lucas20220605@gmail.com"}],"readme":"# commit-echo\n\n[![npm version](https://img.shields.io/npm/v/@404-pf/commit-echo)](https://www.npmjs.com/package/@404-pf/commit-echo)\n[![License](https://img.shields.io/npm/l/@404-pf/commit-echo)](LICENSE)\n[![Node.js version](https://img.shields.io/node/v/@404-pf/commit-echo)](https://www.npmjs.com/package/@404-pf/commit-echo)\n\nLLM-powered CLI that learns your Git commit style and auto-suggests personalized commit messages.\n\n## Features\n\n- **Style learning** — Adapts to your commit conventions over time by analyzing your history\n- **Multi-provider** — Works with OpenAI, Anthropic, Ollama, and OpenAI-compatible endpoints\n- **Interactive setup** — Guided wizard to configure your provider and model\n- **Git hook integration** — Optional `prepare-commit-msg` hook installation from `commit-echo init --install-hook`\n- **Non-destructive** — Review and edit suggestions before committing\n\n## Installation\n\n```bash\nnpm install -g @404-pf/commit-echo\n```\n\n## Development\n\nTo build and run the CLI locally without a global install:\n\n```bash\nnpm install\nnpm run build\nnode dist/index.js suggest\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full setup and contribution workflow.\n\n## Usage\n\n```bash\n# Full flow: diff, suggest, pick, commit\ncommit-echo\n\n# Auto-accept and commit first suggestion\ncommit-echo --yes\n\n# Interactive setup wizard\ncommit-echo init\n\n# Interactive setup and install a prepare-commit-msg hook\ncommit-echo init --install-hook\n\n# Generate suggestions without committing\ncommit-echo suggest\n\n# Auto-select first suggestion (no commit)\ncommit-echo suggest --yes\n\n# View learned style profile\ncommit-echo history\n```\n\nNote: The non-interactive flags `--yes`, `-y`, and `--auto` expect staged changes (run `git add`). If no staged changes are found when auto-committing is requested, the command will print an error and exit with a non-zero status.\n\n### `suggest` Options\n\n| Flag | Default | Description |\n|---|---|---|\n| `--commit` | `false` | Commit the selected suggestion instead of just displaying it |\n| `-y, --yes` | `false` | Automatically select the first suggestion and skip prompts |\n| `--auto` | `false` | Alias for `--yes` |\n| `-v, --verbose` | `false` | Print diagnostic information (model, style profile stats, truncation) |\n| `-d, --show-diff` | `false` | Print the diff content that will be sent to the LLM |\n| `-m, --model <model>` | — | Override the configured LLM model for this invocation |\n| `--max-diff-size <n>` | — | Override the configured maximum diff size for this invocation |\n| `--stream` | `false` | Stream suggestions as they are generated (progressive output) |\n| `-n, --dry-run` | `false` | Show the LLM input without generating suggestions |\n| `--no-commit` | — | Deprecated alias; `suggest` already skips committing unless `--commit` is passed |\n\n> **Note:** The `--stream` flag is supported for OpenAI-compatible and Anthropic providers. Cohere does not support streaming.\n\n## Requirements\n\n- Node.js >= 24.0.0\n- A Git repository with staged changes\n- An API key for your chosen LLM provider\n\n## Configuration\n\nRun `commit-echo init` to configure your provider and model. Configuration is stored in `~/.config/commit-echo/config.json`.\n\nIf you want `git commit` to prefill the first suggestion automatically, run `commit-echo init --install-hook` from inside a Git repository. This installs both a `prepare-commit-msg` hook (prefills the first suggestion) and a `post-commit` hook (logs the committed message for style learning). The hooks skip merge commits, cherry-picks, amend flows, and any commit where a message was already supplied.\n\n### Options\n\n| Option | Default | Description |\n|---|---|---|\n| `provider` | — | LLM provider key (e.g., `openai`, `anthropic`, `ollama`) |\n| `model` | — | Model name to use for generation |\n| `historySize` | `50` | Number of recent commits to learn style from |\n| `maxDiffSize` | `4000` | Maximum diff size (in characters) sent to the LLM. Diffs exceeding this limit are intelligently truncated — file headers are preserved while line-level content is dropped from overflow files. Adjust upward for large refactors or generated-file changes. |\n\n### Environment Variable Overrides\n\nAll scalar configuration options can be overridden with `COMMIT_ECHO_*` environment variables. Environment variables take precedence over values in `config.json`, which is useful for CI pipelines, testing, and switching between projects without editing the config file. (Prompt templates are not overridable via environment variables.)\n\n| Config Option | Environment Variable |\n|---|---|\n| `provider` | `COMMIT_ECHO_PROVIDER` |\n| `model` | `COMMIT_ECHO_MODEL` |\n| `baseUrl` | `COMMIT_ECHO_BASE_URL` |\n| `apiKey` | `COMMIT_ECHO_API_KEY` |\n| `historySize` | `COMMIT_ECHO_HISTORY_SIZE` |\n| `maxDiffSize` | `COMMIT_ECHO_MAX_DIFF_SIZE` |\n\nExample (macOS / Linux):\n\n```bash\nexport COMMIT_ECHO_PROVIDER=anthropic\nexport COMMIT_ECHO_MODEL=claude-sonnet-4-20250514\nexport COMMIT_ECHO_API_KEY=sk-ant-...\ncommit-echo suggest\n```\n\n### Adjusting `maxDiffSize`\n\n`maxDiffSize` controls how many diff characters are sent to the LLM. When a staged diff is larger than the limit, `commit-echo` preserves file headers and trims overflow file bodies before generating suggestions. The status output reports this as truncation, so raise the value when important context is being omitted.\n\nFor typical feature or fix commits, the default `4000` characters keeps prompts small. For large refactors, generated files, or commits that touch many files, set `maxDiffSize` to `10000` or higher in `~/.config/commit-echo/config.json`:\n\n```json\n{\n  \"maxDiffSize\": 10000\n}\n```\n\n### Custom Prompt Templates\n\nYou can override the built-in system and user prompts by setting `systemPromptTemplate` and/or `userPromptTemplate` in `config.json`. This is useful for enforcing project-specific commit conventions (e.g., Jira ticket prefixes, Gerrit Change-Id footers, Signed-off-by lines).\n\nRun `commit-echo init` and answer \"Yes\" when asked about custom prompt templates, or edit `config.json` directly:\n\n```json\n{\n  \"systemPromptTemplate\": \"You are a commit assistant for the Acme project.\\nAlways include a Jira ticket reference.\\n\\n{{profile}}\",\n  \"userPromptTemplate\": \"Generate 3 conventional commits for this diff on branch {{branch}}:\\n\\n{{diff}}\"\n}\n```\n\n#### Template Variables\n\n| Variable | Description |\n|----------|-------------|\n| `{{diff}}` | The git diff text |\n| `{{profile}}` | The learned style profile summary |\n| `{{branch}}` | Current git branch name |\n| `{{message}}` | *(reserved)* Previous commit message context |\n\nIf a custom template is not set, the built-in prompt is used as a fallback.\n\n## Quickstart\n\n### Environment\n\nSet the API key for the provider you plan to use before running the setup wizard or generating suggestions. The table below lists all built-in providers, their API key environment variables, and whether a key is required.\n\n| Provider key | Display name | API key env var | Required? |\n|---|---|---|---|\n| `openai` | OpenAI | `OPENAI_API_KEY` | Yes |\n| `anthropic` | Anthropic | `ANTHROPIC_API_KEY` | Yes |\n| `google` | Google Gemini | `GOOGLE_API_KEY` | Yes |\n| `mistral` | Mistral | `MISTRAL_API_KEY` | Yes |\n| `groq` | Groq | `GROQ_API_KEY` | Yes |\n| `cohere` | Cohere | `COHERE_API_KEY` | Yes |\n| `deepseek` | DeepSeek | `DEEPSEEK_API_KEY` | Yes |\n| `ollama` | Ollama | `OLLAMA_API_KEY` | No / optional for local Ollama |\n| `together` | Together AI | `TOGETHER_API_KEY` | Yes |\n| `fireworks` | Fireworks AI | `FIREWORKS_API_KEY` | Yes |\n| `example` | Example (no API key) | — | No |\n\n> **Note:** Ollama uses the local server at `http://localhost:11434/v1` and normally does not require an API key; the env var is only relevant if your local setup expects one.\n>\n> **Tip:** The `example` provider returns canned responses and requires no API key. It is useful for local testing and trying out `commit-echo` without connecting to an LLM. Set `provider` to `example` in your config to use it.\n\nExample (macOS / Linux):\n\n```bash\nexport OPENAI_API_KEY=sk-example\n```\n\nExample (Windows PowerShell):\n\n```powershell\n$env:OPENAI_API_KEY = \"sk-example\"\n```\n\nExample (Windows CMD):\n\n```cmd\nset OPENAI_API_KEY=sk-example\n```\n\n### Full flow: review staged changes and commit\n\n```bash\ngit add .\ncommit-echo\n```\n\nSample output:\n\n```text\ncommit-echo\n  1. feat: add release summary command\n  2. fix: guard empty commit history\n  3. docs: clarify init workflow\n```\n\n### Interactive setup\n\n```bash\ncommit-echo init\n```\n\nWhat it does:\n- lets you pick a provider\n- helps you choose a model\n- saves the config to `~/.config/commit-echo/config.json`\n\n### Generate suggestions without committing\n\n```bash\ncommit-echo suggest\n```\n\n`commit-echo suggest --no-commit` is still accepted as a deprecated compatibility alias.\n\nSample output:\n\n```text\nSuggestions generated:\n  1. fix: handle empty staged diff\n  2. test: cover custom provider validation\n  3. chore: refresh package metadata\n```\n\n### Stream suggestions as they are generated\n\nUse `--stream` to print LLM output incrementally instead of waiting behind a spinner. Supported for OpenAI-compatible and Anthropic providers; use non-streaming mode for Cohere. Pair with `--yes` for a non-interactive workflow that streams output and auto-commits the first suggestion.\n\n```bash\ncommit-echo suggest --stream\ncommit-echo suggest --stream --yes\n```\n\n### Inspect suggestion diagnostics with `--verbose`\n\nUse verbose mode when you want to confirm which model handled the request, how much commit history was folded into the style profile, or whether the diff had to be truncated before sending it to the provider.\n\n```bash\ncommit-echo suggest --verbose\n```\n\nSample output:\n\n```text\nSuggestions generated:\nModel: gpt-4o\nStyle profile: 5 commit(s), avg length 31.4, imperative rate 80.0%, common prefixes: feat, fix, docs\nTruncation: not applied\n  1. fix: handle empty staged diff\n  2. test: cover custom provider validation\n  3. chore: refresh package metadata\n```\n\nVerbose fields:\n\n- `Model` shows the resolved model name after any `--model` override is applied.\n- `Style profile` summarizes the recent commit history used for tone and structure: how many commits were sampled, the average subject length, the share of imperative subjects, and the most common prefixes.\n- `Truncation` tells you whether `maxDiffSize` trimmed the staged diff before generation. If truncation happens, the CLI also prints a warning with the original and reduced character counts.\n\n### View learned style history\n\n```bash\ncommit-echo history\n```\n\nSample output:\n\n```text\nRecent commit style\n- prefix frequency: fix, feat, docs\n- average subject length: 42\n- recent bodies: 6\n```\n\n## Troubleshooting\n\n- **`No configuration found`** — run `commit-echo init` first.\n- **`No changes detected`** — stage files with `git add` or make an unstaged edit before running `commit-echo suggest`.\n- **Provider auth errors** — confirm the matching environment variable (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or your custom provider key) is set in the same shell session.\n- **Wrong repository context** — run the command inside a Git repository so `commit-echo` can read the diff and history.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}