<div align="center">
# 🦀 Rusty Commit (`rco`)
### **AI-powered commit message generator written in Rust**
**Generate conventional commits, GitMoji messages, and PR descriptions using 18+ AI providers**
[](https://github.com/hongkongkiwi/rusty-commit/actions/workflows/ci.yml)
[](https://crates.io/crates/rusty-commit)
[](https://docs.rs/rusty-commit)
[](https://opensource.org/licenses/MIT)
**🚀 Fast · 🔒 Secure · 🏠 Local-first · 🔌 Editor integrations via MCP**
[Installation](#installation) · [Quick Start](#quick-start) · [Features](#features) · [Providers](#providers) · [Configuration](#configuration) · [Git Hooks](#git-hooks)
</div>
---
## ✨ Why Rusty Commit?
<table>
<tr>
<td width="50%">
**⚡ Blazing Fast**
Native Rust binary with instant startup time. No Node.js bloat, no waiting.
**🤖 18+ AI Providers**
Works with OpenAI, Claude, OpenRouter, Groq, DeepSeek, GitHub Copilot, Ollama, and more.
**🔐 Secure by Default**
Optional keychain storage keeps your API keys safe. OAuth support for major providers.
</td>
<td width="50%">
**🎨 Flexible Formats**
Conventional commits, GitMoji, or custom templates. Multi-language support.
**🔄 Multi-Account Support**
Seamlessly switch between work and personal accounts, different providers, or models.
**🔌 Editor Integration**
MCP server for Cursor, VS Code, Claude Code, and other AI-powered editors.
</td>
</tr>
</table>
---
## 📦 Installation
### One-liner (recommended)
```bash
<details>
<summary>🔐 Security-conscious? Verify the install script first</summary>
```bash
# Download and inspect
curl -fsSL https://raw.githubusercontent.com/hongkongkiwi/rusty-commit/main/install.sh -o install.sh
# Verify with SHA256 checksums, Cosign, GPG, or GitHub attestations
# See: docs/INSTALL-SCRIPT-VERIFICATION.md
```
</details>
### Package Managers
| **Homebrew** | `brew tap hongkongkiwi/tap && brew install rusty-commit` |
| **Cargo** | `cargo install rusty-commit --features secure-storage` |
| **Debian/Ubuntu** | `wget .../rusty-commit_amd64.deb && sudo dpkg -i rusty-commit_amd64.deb` |
| **Fedora/RHEL** | `sudo dnf install https://.../rusty-commit.x86_64.rpm` |
| **Alpine** | `wget .../rusty-commit-x86_64.apk && sudo apk add --allow-untrusted rusty-commit-x86_64.apk` |
| **Windows (Scoop)** | `scoop install rusty-commit` |
| **Windows (Binary)** | [Download from releases](https://github.com/hongkongkiwi/rusty-commit/releases) |
---
## 🚀 Quick Start
### Interactive Setup Wizard
The easiest way to get started with Rusty Commit:
```bash
rco setup # Interactive wizard (recommended)
rco setup --advanced # Full configuration with all options
rco setup --defaults # Non-interactive with sensible defaults
```
**Quick Setup** will ask you:
1. **AI Provider** - Choose from 15+ providers (OpenAI, Anthropic, Gemini, Ollama, etc.)
2. **API Key** - Securely stored in your system's keychain
3. **Commit Format** - Conventional commits, GitMoji, or simple
**Advanced Setup** additionally includes:
- Custom model selection and API endpoints
- Commit message style (capitalization, max length, language)
- Behavior settings (auto-push, commit body, variations)
- Token limits and hook configuration
### Generate Your First Commit
```bash
# 1. Stage your changes
git add .
# 2. Generate commit message
rco
# 3. Review, edit, or regenerate interactively
```
### Multi-Account Workflow (Recommended)
```bash
# Add multiple provider accounts
rco config add-provider # Add work-openai
rco config add-provider # Add personal-anthropic
# Switch between them
rco config use-account work-openai
git add . && rco
rco config use-account personal-anthropic
git add . && rco
```
---
## 🎯 Features
### 📝 Commit Message Generation
```bash
rco # Interactive mode with review
rco -y # Auto-commit without confirmation
rco -g 3 # Generate 3 variations to choose from
rco -c "Fix OAuth flow" # Add extra context
```
### 😄 GitMoji Support
```bash
rco --fgm # Full GitMoji specification
rco -fgm -y # GitMoji + auto-commit
```
**Output:**
```
✨ feat(auth): implement OAuth2 PKCE flow
🔐 Add secure authentication with automatic token refresh.
Supports GitHub, GitLab, and generic OAuth2 providers.
```
### 📋 Clipboard Mode
```bash
rco -C # Copy to clipboard instead of committing
```
### 🔍 Debug Tools
```bash
rco --show-prompt # See the exact prompt sent to AI
rco --timing # Show detailed timing information
RUST_LOG=debug rco # Enable debug logging
```
---
## 🤖 Providers
Rusty Commit works with **18+ AI providers** out of the box. Configure them interactively with `rco setup` or manually as shown below:
> 💡 **Tip**: Use `rco setup` for interactive provider configuration with step-by-step guidance.
### 🔑 OAuth-Enabled (No API Key Required)
| **Claude (Anthropic)** | `rco auth login` |
| **Claude Code** | `rco auth login` |
| **GitHub Copilot** | `rco auth login --provider github-copilot` |
### 🔐 API Key Providers
| **OpenAI** | `rco config set RCO_AI_PROVIDER=openai RCO_API_KEY=sk-... RCO_MODEL=gpt-4o-mini` |
| **Anthropic** | `rco config set RCO_AI_PROVIDER=anthropic RCO_API_KEY=sk-ant-... RCO_MODEL=claude-3-5-haiku-20241022` |
| **OpenRouter** | `rco config set RCO_AI_PROVIDER=openrouter RCO_API_KEY=sk-or-...` |
| **Groq** | `rco config set RCO_AI_PROVIDER=groq RCO_API_KEY=gsk_... RCO_MODEL=llama-3.1-70b-versatile` |
| **DeepSeek** | `rco config set RCO_AI_PROVIDER=deepseek RCO_API_KEY=sk-... RCO_MODEL=deepseek-chat` |
| **xAI/Grok** | `rco config set RCO_AI_PROVIDER=xai RCO_API_KEY=... RCO_MODEL=grok-beta` |
| **Mistral** | `rco config set RCO_AI_PROVIDER=mistral RCO_API_KEY=... RCO_MODEL=mistral-small-latest` |
| **Google Gemini** | `rco config set RCO_AI_PROVIDER=gemini RCO_API_KEY=... RCO_MODEL=gemini-pro` |
| **Azure OpenAI** | `rco config set RCO_AI_PROVIDER=azure RCO_API_KEY=... RCO_API_URL=https://<resource>.openai.azure.com` |
| **Perplexity** | `rco config set RCO_AI_PROVIDER=perplexity RCO_API_KEY=...` |
| **Ollama (Local)** | `rco config set RCO_AI_PROVIDER=ollama RCO_MODEL=mistral RCO_API_URL=http://localhost:11434` |
| **Fireworks** | `rco config set RCO_AI_PROVIDER=fireworks RCO_API_KEY=...` |
| **Moonshot/Kimi** | `rco config set RCO_AI_PROVIDER=moonshot RCO_API_KEY=... RCO_API_URL=https://api.moonshot.cn/v1 RCO_MODEL=kimi-k2` |
| **Alibaba Qwen** | `rco config set RCO_AI_PROVIDER=dashscope RCO_API_KEY=... RCO_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 RCO_MODEL=qwen3-coder-32b-instruct` |
| **Together AI** | `rco config set RCO_AI_PROVIDER=together RCO_API_KEY=...` |
| **DeepInfra** | `rco config set RCO_AI_PROVIDER=deepinfra RCO_API_KEY=...` |
<details>
<summary>🔒 Secure Storage</summary>
When built with `--features secure-storage`:
- **macOS**: Keychain
- **Linux**: Secret Service (GNOME Keyring, KWallet, KeePassXC)
- **Windows**: Credential Manager
Falls back to config file if keychain is unavailable.
</details>
---
## ⚙️ Configuration
### Interactive Configuration
The easiest way to configure Rusty Commit is through the setup wizard:
```bash
rco setup # Quick setup (essential settings only)
rco setup --advanced # Advanced setup (all settings)
```
### Configuration Priority
```
Per-repo config > Global config > Environment variables > Defaults
```
### Manual Config Commands
```bash
rco config status # Check secure storage status
rco config set RCO_AI_PROVIDER=anthropic # Set provider
rco config set RCO_MODEL=claude-3-5-haiku # Set model
rco config set RCO_COMMIT_TYPE=conventional # conventional or gitmoji
rco config set RCO_EMOJI=true # Include emojis
rco config set RCO_LANGUAGE=en # Output language
rco config get RCO_AI_PROVIDER # Get current value
rco config describe # Show all options
rco config reset --all # Reset to defaults
```
### Common Options
| `RCO_AI_PROVIDER` | AI backend | `anthropic` |
| `RCO_MODEL` | Model name | Provider-specific |
| `RCO_API_KEY` | API key | - |
| `RCO_API_URL` | Custom endpoint | - |
| `RCO_COMMIT_TYPE` | Commit format | `conventional` |
| `RCO_EMOJI` | Include emojis | `false` |
| `RCO_LANGUAGE` | Output language | `en` |
| `RCO_MAX_TOKENS` | Max response tokens | `1024` |
| `RCO_TEMPERATURE` | Response creativity | `0.7` |
| `RCO_ENABLE_COMMIT_BODY` | Add commit body with context | `false` |
| `RCO_LEARN_FROM_HISTORY` | Learn style from git history | `false` |
| `RCO_HISTORY_COMMITS_COUNT` | Commits to analyze for style | `50` |
---
## 🎣 Git Hooks
### Install/Uninstall
```bash
rco hook set # Install prepare-commit-msg hook
rco hook unset # Remove hook
```
Once installed, `git commit` (without `-m`) automatically generates commit messages!
### Advanced Hooks
```bash
# Pre-generation hook
rco config set RCO_PRE_GEN_HOOK="just lint; just test -q"
# Pre-commit hook
rco config set RCO_PRE_COMMIT_HOOK="./scripts/tweak_commit.sh"
# Post-commit hook
rco config set RCO_POST_COMMIT_HOOK="git push"
# Hook behavior
rco config set RCO_HOOK_STRICT=false # Allow hook failures
rco config set RCO_HOOK_TIMEOUT_MS=60000 # Timeout in ms
```
### Skip Hooks (Per-Run)
```bash
rco --no-pre-hooks # Skip pre-gen + pre-commit hooks
rco --no-post-hooks # Skip post-commit hooks
```
---
## 🧠 Advanced Features
### Repository Context Awareness
Rusty Commit automatically detects and includes project context for better commit messages:
```bash
# Create custom context file
echo "Payment processing microservice using Stripe API" > .rco/context.txt
```
**Auto-detected context sources:**
- `.rco/context.txt` - Custom project description
- `README.md` - First paragraph
- `Cargo.toml` - Rust project description
- `package.json` - Node.js project description
### Commit Body Generation
Enable detailed commit messages with body explaining the "why":
```bash
rco config set RCO_ENABLE_COMMIT_BODY=true
```
**Output:**
```
feat(auth): implement OAuth2 PKCE flow
- Add secure token storage with automatic refresh
- Support GitHub, GitLab, and generic OAuth2 providers
- Handle token expiration gracefully
```
### Style Learning from History
Automatically learn and match your team's commit style:
```bash
rco config set RCO_LEARN_FROM_HISTORY=true
```
Analyzes last 50 commits to detect:
- Common commit types and scopes
- Average description length
- Capitalization preferences
- Gitmoji usage patterns
### Enhanced GitMoji Support
25+ emojis from [gitmoji.dev](https://gitmoji.dev) specification:
| ✨ | `:sparkles:` | New feature |
| 🐛 | `:bug:` | Bug fix |
| 📝 | `:memo:` | Documentation |
| 🎨 | `:art:` | Code structure/format |
| ♻️ | `:recycle:` | Refactoring |
| ⚡ | `:zap:` | Performance |
| ✅ | `:white_check_mark:` | Tests |
| 🔒 | `:lock:` | Security fix |
| ⬆️ | `:arrow_up:` | Upgrade dependencies |
| 🔥 | `:fire:` | Remove code/files |
| 🚀 | `:rocket:` | Deployment |
| 💥 | `:boom:` | Breaking changes |
---
## 🎨 Custom Skills
Create reusable commit message templates and prompt customizations:
```bash
# List available skills
rco skills list
# Create a new skill
rco skills create conventional-with-scope --category template
# Create project-specific skill
rco skills create my-team-style --project
# Show skill details
rco skills show my-team-style
# Remove a skill
rco skills remove my-team-style
```
### Skill Structure
Skills are stored in `~/.config/rustycommit/skills/` (or `.rco/skills/` for project-specific):
```
my-skill/
├── skill.toml # Skill manifest
├── prompt.md # Custom prompt template
└── hooks/ # Optional hooks
├── pre_gen.sh
└── post_gen.sh
```
### Custom Prompt Template
Create `prompt.md` with placeholders:
```markdown
# Custom Commit Prompt
Analyze this {language} code change:
{diff}
Context: {context}
Format: {commit_type}
Max length: {max_length}
Generate a commit message following our team conventions:
- Use present tense
- Include ticket number if obvious from branch name
- Reference related components
```
---
## 🔌 MCP Server
Rusty Commit includes an **MCP (Model Context Protocol)** server for editor integrations.
### Start the Server
```bash
# TCP Mode (Cursor, VS Code)
rco mcp server --port 3000
# STDIO Mode (Direct integration)
rco mcp stdio
```
### Editor Setup
**Cursor:**
```
Settings > Features > MCP > Add Server
Type: HTTP
URL: http://localhost:3000
```
**Claude Code:**
```bash
### Available MCP Tools
- `generate_commit` - Generate commit from staged changes
- `get_config` / `set_config` - Manage configuration
- `list_accounts` / `use_account` - Switch accounts
---
## 🔄 Multi-Account Support
Perfect for switching between work and personal projects!
```bash
# Add accounts
rco config add-provider # Interactive wizard
rco config add-provider --provider openai --alias work-openai
# Manage accounts
rco config list-accounts # Show all accounts
rco config show-account work-openai # Show account details
rco config use-account work-openai # Switch to account
rco config remove-account work-openai # Remove account
```
### Account Configuration
Accounts stored in `~/.config/rustycommit/accounts.toml`:
```toml
[accounts.work-openai]
provider = "openai"
model = "gpt-4o-mini"
[accounts.personal-anthropic]
provider = "anthropic"
model = "claude-3-5-haiku-20241022"
[active_account]
alias = "work-openai"
```
---
## 📋 PR Description Generation
```bash
rco pr generate # Generate PR description for current branch
rco pr generate --base main # Compare against main branch
rco pr browse # Generate and open PR creation page
```
Features:
- Analyzes all commits since base branch
- Groups changes by type (features, fixes, docs, etc.)
- Follows PR template conventions
- Includes breaking changes and deprecation notices
---
## 🚫 File Exclusion
Exclude files from AI analysis via `.rcoignore`:
```gitignore
# Dependencies
node_modules/
vendor/
Cargo.lock
# Build artifacts
*.min.js
*.map
dist/
build/
# IDE
.idea/
.vscode/
# OS
.DS_Store
Thumbs.db
```
Or via command line:
```bash
rco -x "package-lock.json" -x "*.lock" -x "*.min.js"
```
---
## 🔄 Updates
```bash
rco update --check # Check for updates
rco update # Update to latest
rco update --force # Force update
rco update --version 1.0.2 # Install specific version
```
---
## 🏃 GitHub Action
Use in CI/CD workflows:
```yaml
name: AI Commits
on: [push]
jobs:
ai-commit:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: hongkongkiwi/action-rusty-commit@v1
with:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
RCO_API_KEY: ${{ secrets.RCO_API_KEY }}
RCO_AI_PROVIDER: 'anthropic'
RCO_MODEL: 'claude-3-5-haiku-20241022'
```
See [action-rusty-commit](https://github.com/hongkongkiwi/action-rusty-commit) for details.
---
## 🛠️ Troubleshooting
| **401 / Invalid API key** | Re-authenticate: `rco auth login` or set `RCO_API_KEY` |
| **429 Rate-limited** | Wait briefly; try lighter model or switch accounts |
| **Secure storage unavailable** | Falls back to file; check `rco config status` |
| **Hooks not running** | Ensure `.git/hooks/prepare-commit-msg` is executable |
| **OAuth browser not opening** | Use `rco auth login --no-browser` |
| **Large diff truncated** | Increase `RCO_DIFF_TOKENS` or use `.rcoignore` |
| **Reasoning model thinking tags** | Use `--strip-thinking` flag |
### Debug Mode
```bash
RUST_LOG=debug rco -y # Enable debug logging
rco --show-prompt # See exact prompt sent to AI
rco --timing # Show timing breakdown
```
---
## 🧪 Development
```bash
# Build
cargo build
cargo build --release
cargo build --features secure-storage
# Test
cargo test
cargo test --all-features
# Lint
cargo clippy --all-features -- -D warnings
cargo fmt
# Just commands
just build
just test
just all # fmt + clippy + test
```
---
## 🔒 Security & Verification
All releases are cryptographically signed with multiple methods:
### Automatic Verification
The install script automatically verifies downloads using the strongest available method.
### Manual Verification
```bash
# Cosign/Sigstore (modern)
cosign verify-blob \
--bundle rustycommit-linux-x86_64.tar.gz.cosign.bundle \
--certificate-identity-regexp "https://github.com/hongkongkiwi/rusty-commit/.github/workflows/release.yml@.*" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
rustycommit-linux-x86_64.tar.gz
# GPG (traditional)
gpg --keyserver hkps://keys.openpgp.org --recv-keys 0EC2DFF577818B86BA38DA3F164E3F90E425B2AD
gpg --verify rustycommit-linux-x86_64.tar.gz.asc rustycommit-linux-x86_64.tar.gz
# GitHub attestations
gh attestation verify rustycommit-linux-x86_64.tar.gz --repo hongkongkiwi/rusty-commit
```
See [docs/VERIFICATION.md](docs/VERIFICATION.md) for details.
---
## 💖 Support the Project
If Rusty Commit saves you time, consider supporting ongoing development:
[](https://github.com/sponsors/hongkongkiwi)
[](https://buymeacoffee.com/hongkongkiwi)
---
## 📄 License
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
---
<div align="center">
**Inspired by [OpenCommit](https://github.com/di-sukharev/opencommit)** · Built with 🦀 Rust
**Build faster. Commit smarter.**
</div>