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

📊 Datadog Integration (read-only)

Authenticate against the Datadog API. Subsequent slices add metrics, monitor, dashboard, and logs subcommands.

# Configure Datadog API credentials (prompts for API key, APP key, and site)
omni-dev datadog auth login

# Verify the credentials by calling /api/v1/validate
omni-dev datadog auth status

# Remove Datadog credentials from ~/.omni-dev/settings.json
omni-dev datadog auth logout

DATADOG_SITE defaults to datadoghq.com. Other regions (datadoghq.eu, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ddog-gov.com) are recognised without warning. Environment variables DATADOG_API_KEY, DATADOG_APP_KEY, DATADOG_SITE override the stored settings.

For on-prem or proxied Datadog installs, set DATADOG_API_URL to the full API base URL (e.g. https://datadog.corp.example) — it overrides the site-derived URL entirely.

✏️ Manual Amendment

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

🗒️ Claude Conversation History

Export your Claude Code chat history to a directory of .jsonl files for behavioural analysis, work-log generation, or downstream tooling. Re-running acts as an idempotent sync: new chats are added, modified chats are overwritten, unchanged chats are skipped.

# Mirror ~/.claude/projects to ./history/ (one .jsonl per chat, grouped by project slug)
omni-dev ai claude history sync --target ./history

# Limit to one project (encoded slug or decoded cwd path)
omni-dev ai claude history sync --target ./history --project /Users/me/work/repo

# Only sessions touched in the last week
omni-dev ai claude history sync --target ./history --since 7d

# Preview without writing, then prune target files for sessions removed upstream
omni-dev ai claude history sync --target ./history --dry-run --prune

# Render LLM-friendly markdown alongside the raw jsonl (one .md per session)
omni-dev ai claude history sync --target ./history --output-format jsonl,markdown

# Markdown only — suitable for piping into a coaching LLM
omni-dev ai claude history sync --target ./history --output-format markdown

The export is a behavioural transcript, not a faithful archive. The top-level session jsonl captures all prompts, responses, thinking blocks, tool calls, and tool-result metadata — the signal needed for analysis. Sub-agent internal turns, large tool-output sidecars, PDF page rasters, and Claude's auto-memory are deliberately excluded; they would bloat any LLM-ingested corpus without adding interaction-pattern signal.

In-progress chats produce a valid jsonl prefix (the source size is captured once at the start of the copy), so you can sync safely while a chat is open. The target layout mirrors the source — <target>/<slug>/<uuid>.jsonl — and source mtime is preserved on each target file so downstream tooling can sort sessions chronologically without parsing every file.

--output-format markdown writes a derived <target>/<slug>/<uuid>.md alongside (or instead of) the jsonl. Each markdown file has YAML frontmatter with session metadata followed by ## User / ## Assistant turns; tool calls render as ### Tool call: <name> blocks, thinking blocks collapse into <details>, and sub-agent (Agent) calls render the prompt argument only.

Agent-to-user interactions are surfaced as first-class structured events so the analyst LLM sees what was actually asked and how the user responded:

• AskUserQuestion calls render as ### Agent question: <header> with the question text and a bulleted list of options (with descriptions); the paired user reply renders as ## User response.
• Tool denials show up as **Tool result (<tool>, denied by user):** — detected by the canonical "The user doesn't want to proceed with this tool use" sentinel Claude Code stuffs into the next tool_result.
• Tool interrupts (escape mid-execution) render as **Tool result (<tool>, interrupted by user):**.
• Errors (real tool failures, distinct from user denials) keep the error label; successes use ok.

System reminders, attachments, and permission-mode events are included by default — pass --exclude-system to drop them. Markdown idempotency keys off source mtime alone (the rendered length differs from the source length), and --prune only deletes artifacts whose extension matches one of the formats listed in --output-format.

🔌 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
• Datadog Credentials (for Datadog features): API key, application key, and site
  • Configure with: omni-dev datadog auth login
• Git: Any modern version

AI backend selection

By default, omni-dev calls the Anthropic API (or Bedrock/OpenAI/Ollama via the USE_*/CLAUDE_CODE_USE_BEDROCK env vars). As an alternative, you can route AI calls through an already-authenticated Claude Code CLI session, avoiding the need for a separate API key:

# Per-invocation flag:
omni-dev --ai-backend claude-cli git commit message twiddle <range>

# Or set persistently:
export OMNI_DEV_AI_BACKEND=claude-cli

The flag takes precedence over the environment variable.

Model selection follows the precedence chain --model → CLAUDE_MODEL → CLAUDE_CODE_MODEL → ANTHROPIC_MODEL → registry default. Short aliases (sonnet, opus, haiku) and full identifiers (claude-sonnet-4-6) are both accepted and forwarded verbatim to claude -p --model.

Sandboxing guarantees. The claude -p subprocess is locked down so it behaves as a pure prompt→completion service, not a nested agent with filesystem or shell access:

• Built-in tools disabled (--tools "").
• MCP servers blocked (--strict-mcp-config with no config).
• User/project/local settings ignored (--setting-sources "").
• Slash commands / skills disabled.
• Session persistence disabled.
• Subprocess runs in a fresh temp directory (not your repo root).
• Environment is scrubbed of CLAUDE_PROJECT_DIR, CLAUDE_CODE_*, and CLAUDE_PROJECT_* before spawn.

Cost baseline. Because the claude -p session still loads a small system prompt, each invocation has a floor cost (~$0.007 Haiku, ~$0.03 Sonnet, ~$0.15 Opus) before any user content. Back-to-back calls within one hour hit the prompt cache and are much cheaper. If you pay per token, compare against the default HTTP backend which has no such floor.

Overrides. Optional environment variables:

• OMNI_DEV_CLAUDE_CLI_BIN — path to the claude binary (default: resolved from PATH).
• OMNI_DEV_CLAUDE_CLI_TIMEOUT_SECS — subprocess timeout (default: 600).
• OMNI_DEV_CLAUDE_CLI_STDOUT_MAX_BYTES — stdout cap in bytes (default: 4 MiB).
• OMNI_DEV_CLAUDE_CLI_ALLOW_TOOLS — escape hatch (default: disabled). See below.
• OMNI_DEV_CLAUDE_CLI_ALLOW_MCP — escape hatch for MCP server pickup (default: disabled). See below.
• OMNI_DEV_CLAUDE_CLI_MAX_BUDGET_USD — per-invocation spending cap in USD (default: none). See below.

The --beta-header flag is ignored with this backend (the CLI's --betas flag is API-key-user-only and has different semantics).

Escape hatch: --claude-cli-allow-tools

By default the nested claude -p session is run with --tools "" and cannot read, edit, or execute anything on your system. For deliberately tool-capable use cases, you can weaken the sandbox:

omni-dev --ai-backend claude-cli --claude-cli-allow-tools git branch create pr
# or:
export OMNI_DEV_CLAUDE_CLI_ALLOW_TOOLS=true

When enabled, the nested session uses the CLI's default built-in tool set (Read / Edit / Write / Bash / Glob / Grep). This means the session can access your repository and run commands. Only enable it when you want that behaviour. When active, omni-dev logs a warning on every invocation.

--strict-mcp-config and --setting-sources "" still apply unless you also enable --claude-cli-allow-mcp (see below). The two escape hatches are independent so you can grant tool access without exposing MCP server credentials, and vice-versa.

Escape hatch: --claude-cli-allow-mcp

By default the nested claude -p session is run with --strict-mcp-config and no --mcp-config, blocking every MCP server you have configured in ~/.claude/settings.json. To re-enable MCP server pickup:

omni-dev --ai-backend claude-cli --claude-cli-allow-mcp git branch create pr
# or:
export OMNI_DEV_CLAUDE_CLI_ALLOW_MCP=true

When enabled, the nested session can connect to any MCP server in your user settings. Be aware that MCP servers commonly hold OAuth tokens (Gmail, Drive, Slack) or expose internal network services; enabling this exposes them to the nested session. Only enable it when you want that behaviour. When active, omni-dev logs a warning on every invocation.

This flag is independent of --claude-cli-allow-tools. Built-in tools remain disabled unless you enable that flag separately.

Spending cap: --claude-cli-max-budget-usd

Pass a per-invocation spending cap in USD:

omni-dev --ai-backend claude-cli --claude-cli-max-budget-usd 0.50 \
  git commit message twiddle HEAD~3..HEAD
# or:
export OMNI_DEV_CLAUDE_CLI_MAX_BUDGET_USD=0.50

The value is forwarded to claude -p --max-budget-usd. If the nested session exceeds the cap, it aborts with an error rather than running away with cost. Regardless of whether a cap is set, each invocation's total_cost_usd is logged at INFO level for observability — run with RUST_LOG=omni_dev=info to see it.

The cap is ignored when --ai-backend is not claude-cli. Non-positive, non-finite, or non-numeric values are silently treated as no cap.

🐛 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