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 and PR descriptions
• 🧠 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
• 🚀 PR Creation: Generate professional pull requests with AI-powered descriptions
• 📦 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

# Install with Nix
nix profile install github:rust-works/omni-dev

# Install with Nix flakes (development)
nix run github:rust-works/omni-dev

# Enable binary cache for faster builds (optional)
cachix use omni-dev

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

Nix Binary Cache (Optional)

For faster Nix builds, you can use the binary cache:

# Install cachix if you don't have it
nix profile install nixpkgs#cachix

# Enable the omni-dev binary cache
cachix use omni-dev

# Now Nix installations will use pre-built binaries instead of compiling from source
nix profile install github:rust-works/omni-dev

🎬 See It In Action

Watch omni-dev transform messy commits into professional ones with AI-powered analysis

30-Second Demo

Transform your commit messages and create professional PRs 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"

# Create a professional PR with AI-generated description
omni-dev git branch create pr
# 🎉 Generates comprehensive PR with detailed description, testing info, and more

📋 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 parallel processing
omni-dev git commit message twiddle 'HEAD~20..HEAD' --concurrency 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

🚀 AI-Powered PR Creation

Create professional pull requests with AI-generated descriptions:

# Generate and create PR with AI-powered description
omni-dev git branch create pr

# Create PR with specific base branch
omni-dev git branch create pr main

# Save PR details to file without creating
omni-dev git branch create pr --save-only pr-description.yaml

# Auto-create without confirmation
omni-dev git branch create pr --auto-apply

📝 Atlassian Integration

Read, write, and manage JIRA issues and Confluence pages from the command line:

# Authenticate with Atlassian Cloud
omni-dev atlassian auth login

# Check authentication status
omni-dev atlassian auth status

# Fetch a JIRA issue as markdown
omni-dev atlassian jira read PROJ-123

# Fetch as raw ADF JSON
omni-dev atlassian jira read PROJ-123 --format adf

# Push markdown changes back to JIRA
omni-dev atlassian jira write PROJ-123 issue.md

# Interactive edit: fetch, edit in $EDITOR, push
omni-dev atlassian jira edit PROJ-123

# Search issues with JQL
omni-dev atlassian jira search --project PROJ --status Open

# Create an issue
omni-dev atlassian jira create issue.md --project PROJ --summary "Fix bug"

# Transition an issue
omni-dev atlassian jira transition PROJ-123 "In Progress"

# Confluence: read, search, create pages
omni-dev atlassian confluence read 12345
omni-dev atlassian confluence search --space ENG --title auth
omni-dev atlassian confluence create page.md --space ENG --title "New Page"

# Convert markdown to ADF JSON (offline)
omni-dev atlassian convert to-adf input.md

✏️ Manual Amendment

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

🔌 MCP Server

omni-dev ships an optional Model Context Protocol server so AI assistants (Claude Desktop, Claude Code, the MCP Inspector, custom agents) can call omni-dev over stdio instead of shelling out to the CLI.

Tools currently exposed:

• git_view_commits — YAML commit analysis (mirrors omni-dev git commit message view)

Resources exposed via URI templates:

URI template	Returns
git://repo/commits/{range}	YAML commit analysis
jira://issue/{key}	JIRA issue as JFM
jira://issue/{key}.adf	JIRA issue body as ADF
confluence://page/{id}	Confluence page as JFM
confluence://page/{id}.adf	Confluence page body as ADF

Install

cargo install omni-dev --features mcp

This adds a second binary, omni-dev-mcp, alongside the regular omni-dev CLI. The default cargo install omni-dev build is unchanged — no MCP dependencies are pulled in unless the mcp feature is enabled.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "omni-dev": {
      "command": "omni-dev-mcp"
    }
  }
}

Claude Code

Per-project — create .mcp.json at the repo root:

{
  "mcpServers": {
    "omni-dev": {
      "command": "omni-dev-mcp"
    }
  }
}

Or register globally with the Claude Code CLI:

claude mcp add omni-dev omni-dev-mcp

Smoke-test with the MCP Inspector

npx @modelcontextprotocol/inspector omni-dev-mcp

The Inspector opens a browser UI where you can list tools and resources, call git_view_commits, and fetch git://repo/commits/HEAD against the current working directory.

Troubleshooting

• Logs go to stderr. MCP uses stdin/stdout for protocol framing, so tracing output is routed to stderr — tail your client's MCP log pane or run the binary in a terminal to see it.
• Verbose tracing: RUST_LOG=debug omni-dev-mcp turns on debug-level logs. Module-scoped filters work too, e.g. RUST_LOG=omni_dev::mcp=trace.
• Permission errors: the assistant runs omni-dev-mcp with its own working directory. Tools that open a git repository use that directory unless an explicit repo_path parameter (or a resource URI placing you elsewhere) overrides it. If tool calls fail with "failed to open git repository", confirm the assistant launched the server from inside the repo you expected.

⚙️ 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-opus-4.1"

🧠 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 concurrency for very large ranges
omni-dev git commit message twiddle 'main..HEAD' --concurrency 2

Command Options

Option	Description	Example
--use-context	Enable contextual intelligence	--use-context
--concurrency N	Number of parallel commit processors (default: 4)	--concurrency 3
--no-coherence	Skip cross-commit coherence refinement pass	--no-coherence
--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. Create professional PR with AI-generated description
omni-dev git branch create pr

# ✅ Professional commit history + comprehensive PR description ready for review

Contributing

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

Development Setup

1. Clone the repository:

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

2. Install Rust (if you haven't already):

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

3. Build the project:

   cargo build
   

4. 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
• Atlassian Credentials (for JIRA/Confluence features): Instance URL, email, and API token
  • Configure with: omni-dev atlassian auth login
• 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