{"id":30522894,"url":"https://github.com/marclove/llmc","last_synced_at":"2025-09-03T04:35:19.928Z","repository":{"id":302736873,"uuid":"1013268683","full_name":"marclove/llmc","owner":"marclove","description":"AI-powered commit message generator that follows Conventional Commits specification. Simply run npx llmc and it will automatically generate a commit message from your staged changes and commit them for you","archived":false,"fork":false,"pushed_at":"2025-08-25T14:05:54.000Z","size":2157,"stargazers_count":8,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-27T01:03:51.991Z","etag":null,"topics":["claude","claude-code","cline","codex-cli","conventional-commit","conventional-commits","copilot","cursor","gemini-cli","llm","windsurf"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marclove.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}},"created_at":"2025-07-03T16:08:38.000Z","updated_at":"2025-07-31T04:50:37.000Z","dependencies_parsed_at":"2025-07-04T01:29:19.522Z","dependency_job_id":null,"html_url":"https://github.com/marclove/llmc","commit_stats":null,"previous_names":["marclove/registrar","marclove/llmc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/marclove/llmc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marclove%2Fllmc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marclove%2Fllmc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marclove%2Fllmc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marclove%2Fllmc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marclove","download_url":"https://codeload.github.com/marclove/llmc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marclove%2Fllmc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273392161,"owners_count":25097255,"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-09-03T02:00:09.631Z","response_time":76,"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":["claude","claude-code","cline","codex-cli","conventional-commit","conventional-commits","copilot","cursor","gemini-cli","llm","windsurf"],"created_at":"2025-08-26T19:42:37.104Z","updated_at":"2025-09-03T04:35:19.917Z","avatar_url":"https://github.com/marclove.png","language":"TypeScript","readme":"# llmc\n\nAI-powered commit message generator that follows Conventional Commits specification. Simply run `npx llmc` and it will automatically generate a commit message from your staged changes and commit them for you.\n\n![demo video](/llmc-demo.gif)\n\n## Features\n\n- 🤖 AI-generated commit messages using multiple providers (Anthropic, OpenAI, Google, etc.)\n- 📝 Follows [Conventional Commits](https://www.conventionalcommits.org/) specification\n- ⚙️ Configurable via TOML file with custom prompts\n- 🔄 Automatic retry logic with visual progress indicators\n- 🎨 Rich terminal UI with real-time status updates and timers\n- 🚀 Zero-config usage with sensible defaults\n- ✨ Automatically commits your changes after generating the message\n- 🔗 Git hook integration with message-only mode\n\n## Quick Start\n\n### Using npx (Recommended)\n\n```bash\n# Initialize a configuration file (optional)\nnpx llmc init\n\n# Stage your changes\ngit add .\n\n# Generate commit message and commit automatically\nnpx llmc\n\n# Or just generate the message without committing (for git hooks)\nnpx llmc --message-only\n\n# Check version\nnpx llmc -v\n\n# Show help\nnpx llmc -h\n```\n\nThat's it! llmc will:\n\n1. ✅ Check for staged changes\n2. 🤖 Generate a commit message using AI\n3. 📝 Commit your changes with the generated message\n4. 🎉 Show you the result with a beautiful progress interface\n\n### Installation\n\n```bash\nnpm install -g llmc\n```\n\n## Configuration\n\nTo configure llmc, you can create a `llmc.toml` file in your project root. The easiest way to get started is to run the `init` command:\n\n```bash\nnpx llmc init\n```\n\nThis will create a `llmc.toml` file with the default settings, which you can then customize.\n\nHere's an example of a `llmc.toml` file:\n\n```toml\nprovider = \"anthropic\"\nmodel = \"claude-sonnet-4-20250514\"\nmax_tokens = 250\ntemperature = 1.0\napi_key_name = \"ANTHROPIC_API_KEY\"\n\n# Optional: Custom prompt with ${diff} interpolation\nprompt = \"\"\"\nAnalyze this git diff and generate a commit message following Conventional Commits.\n\nGit diff:\n${diff}\n\nProvide a clear, concise commit message.\n\"\"\"\n```\n\n### Supported Providers\n\n- `anthropic` - Claude models (default)\n- `openai` - GPT models\n- `google` - Gemini models\n- `groq` - Fast inference\n- `cerebras` - High-performance models\n- `cohere` - Command models\n- `deepseek` - DeepSeek models\n- `mistral` - Mistral models\n- `perplexity` - Perplexity models\n- `replicate` - Replicate models\n- `togetherai` - Together AI models\n- `vercel` - Vercel AI models\n- `xai` - xAI models\n\n### Environment Variables\n\nSet the appropriate API key for your chosen provider:\n\n```bash\nexport ANTHROPIC_API_KEY=\"your-api-key\"\nexport OPENAI_API_KEY=\"your-api-key\"\nexport GOOGLE_API_KEY=\"your-api-key\"\n# ... etc\n```\n\n## Git Hook Integration\n\nFor git hook integration, use the `--message-only` or `--no-commit` flags to generate commit messages without automatically committing:\n\n```bash\nnpx llmc --message-only\nnpx llmc --no-commit  # Same as --message-only\n```\n\n### prepare-commit-msg Hook Setup\n\nCreate `.git/hooks/prepare-commit-msg`:\n\n```bash\n#!/bin/sh\n# Generate commit message using llmc\nnpx llmc --message-only \u003e \"$1\"\n```\n\nMake it executable:\n\n```bash\nchmod +x .git/hooks/prepare-commit-msg\n```\n\nNow when you run `git commit`, llmc will automatically generate the commit message for you.\n\n### commit-msg Hook Setup\n\nFor validation and generation combined:\n\n```bash\n#!/bin/sh\n# Generate commit message if none provided\nif [ -z \"$(cat $1 | grep -v '^#')\" ]; then\n    npx llmc --message-only \u003e \"$1\"\nfi\n```\n\n## Usage Examples\n\n### Basic Usage\n\n```bash\n# Stage your changes\ngit add .\n\n# Generate commit message and commit automatically\nnpx llmc\n\n# Generate message only (for git hooks)\nnpx llmc --message-only\n```\n\n### Custom Configuration\n\n```bash\n# Use different provider\necho 'provider = \"openai\"' \u003e llmc.toml\nnpx llmc\n\n# Use custom prompt\ncat \u003e llmc.toml \u003c\u003c EOF\nprovider = \"anthropic\"\nprompt = \"\"\"\nCreate a commit message for this diff: \\${diff}\nMake it concise and professional.\n\"\"\"\nEOF\nnpx llmc\n```\n\n### Example Output\n\nWhen you run `npx llmc`, you'll see a beautiful progress interface:\n\n```\n⠋ Checking for staged changes...\n⠋ Generating commit message...\nTime elapsed: 2s\n⠋ Committing changes...\n✓ Committed successfully!\nCommit message: feat(components): add new Button component with accessibility features\n```\n\n## Development\n\n### Building and Testing\n\n```bash\n# Install dependencies\nnpm install\n\n# Format code\nnpm run format\n\n# Build the project (includes formatting)\nnpm run build\n\n# Run tests (excludes API integration tests)\nnpm test\n\n# Run tests in watch mode\nnpm run test:watch\n\n# Run API integration tests (requires valid API key)\nnpm run test:integration\n\n# Run all tests (including API integration tests)\nnpm run test:all\n\n# Type checking\nnpm run lint\n\n# Releasing\nnpm run release\n```\n\n### Test Structure\n\nThe project uses a two-tier testing approach:\n\n- **Regular Tests** (`npm test`): Unit tests, React component tests, and basic integration tests that don't require API keys\n- **API Integration Tests** (`npm run test:integration`): Full end-to-end tests that require valid API keys and test actual AI provider integration\n\nThis separation allows for fast development cycles while ensuring comprehensive coverage when needed.\n\n## Troubleshooting\n\n### Common Issues\n\n1. **API Key Not Found**\n   ```bash\n   # Make sure your API key is set\n   echo $ANTHROPIC_API_KEY\n   ```\n\n2. **No Staged Changes**\n   ```bash\n   # Make sure you have staged changes first\n   git add .\n\n   # Verify you have staged changes\n   git diff --cached\n   ```\n\n3. **Generation Failures**\n   llmc automatically retries up to 3 times if generation fails. You'll see:\n   ```\n   ⠋ Retrying commit message generation (attempt 2/3)...\n   Previous attempt failed. Retrying... (1 failed attempts)\n   ```\n\n4. **Commit Failures**\n   If the commit fails, check that:\n   - You have write permissions to the repository\n   - You're in a git repository\n   - There are actually staged changes to commit\n\n### Error Handling\n\nllmc provides detailed error messages and visual feedback:\n\n- ✅ Green checkmark for success\n- ❌ Red X for errors\n- 🔄 Automatic retry with progress indicators\n- ⏱️ Real-time timer showing elapsed time\n\n## License\n\nBSD 3-Clause License - see LICENSE file for details.\n\n## Contributing\n\nContributions welcome! Please read CONTRIBUTING.md for guidelines.\n\n### Publishing to npm\n\nFor maintainers, here's how to publish new versions to npm:\n\n1. **Ensure all tests pass**:\n   ```bash\n   npm test\n   npm run test:integration  # Run API integration tests if needed\n   npm run lint\n   ```\n\n2. **Update version in package.json**:\n   ```bash\n   # Use Conventional Commits to drive release determination\n   npm run release\n\n   # For explicitly specifying patch releases (bug fixes)\n   npm version patch\n\n   # For explicitly specifying minor releases (new features)\n   npm version minor\n\n   # For explicitly specifying major releases (breaking changes)\n   npm version major\n   ```\n\n3. **Build and publish**:\n   ```bash\n   # The prepublishOnly script will automatically run 'npm run build'\n   npm publish\n   ```\n\n4. **Push the version tag**:\n   ```bash\n   git push origin main --tags\n   ```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarclove%2Fllmc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarclove%2Fllmc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarclove%2Fllmc/lists"}