omni-dev

An intelligent Git commit message toolkit with AI-powered contextual intelligence. Transform messy commit histories into professional, conventional commit formats with project-aware suggestions.

✨ Key Features

🤖 AI-Powered Intelligence: Claude AI analyzes your code changes to suggest meaningful commit messages
🧠 Contextual Awareness: Understands your project structure, conventions, and work patterns
🔍 Comprehensive Analysis: Deep analysis of commits, branches, and file changes
✏️ Smart Amendments: Safely improve single or multiple commit messages
📦 Automatic Batching: Handles large commit ranges intelligently
🎯 Conventional Commits: Automatic detection and formatting
🛡️ Safety First: Working directory validation and error recovery
⚡ Fast & Reliable: Built with Rust for memory safety and performance

🚀 Quick Start

Installation

# Install from crates.io
cargo install omni-dev

# Set up Claude API key (required for AI features)
export CLAUDE_API_KEY="your-api-key-here"

30-Second Demo

Transform your commit messages with AI intelligence:

# Analyze and improve commit messages in your current branch
omni-dev git commit message twiddle 'origin/main..HEAD' --use-context

# Before: "fix stuff", "wip", "update files"
# After:  "feat(auth): implement OAuth2 authentication system"
#         "docs(api): add comprehensive endpoint documentation"
#         "fix(ui): resolve mobile responsive layout issues"

📋 Core Commands

🤖 AI-Powered Commit Improvement (`twiddle`)

The star feature - intelligently improve your commit messages with real-time model information display:

# Improve commits with contextual intelligence
omni-dev git commit message twiddle 'origin/main..HEAD' --use-context

# Process large commit ranges with automatic batching
omni-dev git commit message twiddle 'HEAD~20..HEAD' --batch-size 5

# Save suggestions to file for review
omni-dev git commit message twiddle 'HEAD~5..HEAD' \
  --save-only suggestions.yaml

# Auto-apply improvements without confirmation
omni-dev git commit message twiddle 'HEAD~3..HEAD' --auto-apply

🔍 Analysis Commands

# Analyze commits in detail (YAML output)
omni-dev git commit message view 'HEAD~3..HEAD'

# Analyze current branch vs main
omni-dev git branch info main

# Get comprehensive help
omni-dev help-all

✏️ Manual Amendment

# Apply specific amendments from YAML file
omni-dev git commit message amend amendments.yaml

⚙️ Configuration Commands

# Show supported AI models and their specifications
omni-dev config models show

# View model information with token limits and capabilities
omni-dev config models show | grep -A5 "claude-sonnet-4"

🧠 Contextual Intelligence

omni-dev understands your project context to provide better suggestions:

Project Configuration

Create .omni-dev/ directory in your repo root:

mkdir .omni-dev

Scope Definitions (`.omni-dev/scopes.yaml`)

scopes:
  - name: "auth"
    description: "Authentication and authorization systems"
    examples: ["auth: add OAuth2 support", "auth: fix token validation"]
    file_patterns: ["src/auth/**", "auth.rs"]
  
  - name: "api"
    description: "REST API endpoints and handlers"  
    examples: ["api: add user endpoints", "api: improve error responses"]
    file_patterns: ["src/api/**", "handlers/**"]

Commit Guidelines (`.omni-dev/commit-guidelines.md`)

# Project Commit Guidelines

## Format
- Use conventional commits: `type(scope): description`
- Keep subject line under 50 characters
- Use imperative mood: "Add feature" not "Added feature"

## Our Scopes
- `auth` - Authentication systems
- `api` - REST API changes
- `ui` - Frontend/UI components

🎯 Advanced Features

Intelligent Context Detection

omni-dev automatically detects:

Project Conventions: From .omni-dev/, CONTRIBUTING.md
Work Patterns: Feature development, bug fixes, documentation, refactoring
Branch Context: Extracts work type from branch names (feature/auth-system)
File Architecture: Understands UI, API, core logic, configuration changes
Change Significance: Adjusts detail level based on impact

Automatic Batching

Large commit ranges are automatically split into manageable batches:

# Processes 50 commits in batches of 4 (default)
omni-dev git commit message twiddle 'HEAD~50..HEAD' --use-context

# Custom batch size for very large ranges
omni-dev git commit message twiddle 'main..HEAD' --batch-size 2

Command Options

Option	Description	Example
`--use-context`	Enable contextual intelligence	`--use-context`
`--batch-size N`	Set batch size for large ranges	`--batch-size 3`
`--context-dir PATH`	Custom context directory	`--context-dir ./config`
`--auto-apply`	Apply without confirmation	`--auto-apply`
`--save-only FILE`	Save to file without applying	`--save-only fixes.yaml`
`--edit`	Edit amendments in external editor	`--edit`

📖 Real-World Examples

Before & After

Before: Messy commit history

e4b2c1a fix stuff
a8d9f3e wip
c7e1b4f update files
9f2a6d8 more changes

After: Professional commit messages

e4b2c1a feat(auth): implement JWT token validation system
a8d9f3e docs(api): add comprehensive OpenAPI documentation
c7e1b4f fix(ui): resolve mobile responsive layout issues
9f2a6d8 refactor(core): optimize database query performance

Workflow Integration

# 1. Work on your feature branch
git checkout -b feature/user-dashboard

# 2. Make commits (don't worry about perfect messages)
git commit -m "wip"
git commit -m "fix stuff"
git commit -m "add more features"

# 3. Before merging, improve all commit messages
omni-dev git commit message twiddle 'main..HEAD' --use-context

# 4. Review and apply the suggestions
# ✅ Creates professional, contextual commit messages automatically

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

Clone the repository:

git clone https://github.com/rust-works/omni-dev.git
cd omni-dev

Install Rust (if you haven't already):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Build the project:
```
cargo build
```

Run the build script (includes tests, linting, and formatting):

./scripts/build.sh

Or run individual steps:

cargo test         # Run tests
cargo clippy       # Run linting
cargo fmt          # Format code

📚 Documentation

User Guide - Comprehensive usage guide with examples
Configuration Guide - Set up contextual intelligence
API Documentation - Rust API reference
Troubleshooting - Common issues and solutions
Examples - Real-world usage examples
Release Process - For contributors

🔧 Requirements

Rust: 1.70+ (for installation from source)
Claude API Key: Required for AI-powered features
- Get your key from Anthropic Console
- Set: export CLAUDE_API_KEY="your-key"
AI Model Selection: Optional configuration for specific Claude models
- View available models: omni-dev config models show
- Configure via ~/.omni-dev/settings.json or ANTHROPIC_MODEL environment variable
- Supports standard identifiers and Bedrock-style formats
Git: Any modern version

🐛 Debugging

For troubleshooting and detailed logging, use the RUST_LOG environment variable:

# Enable debug logging for omni-dev components
RUST_LOG=omni_dev=debug omni-dev git commit message twiddle ...

# Debug specific modules (e.g., context discovery)  
RUST_LOG=omni_dev::claude::context::discovery=debug omni-dev git commit message twiddle ...

# Show only errors and warnings
RUST_LOG=warn omni-dev git commit message twiddle ...

See Troubleshooting Guide for detailed debugging information.

Changelog

See CHANGELOG.md for a list of changes in each version.

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Support

📋 Issues
💬 Discussions

Acknowledgments

Thanks to all contributors who help make this project better!
Built with ❤️ using Rust

omni-dev 0.8.0