Omni dev agent

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.

🎬 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

✨ 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
• 🌐 Browser Bridge: Drive HTTP requests through an authenticated browser tab without exfiltrating cookies or tokens
• 🗂️ Worktrees View: One live view of every repo and git worktree open across all your VS Code windows
• 🛡️ Safety First: Working directory validation, protection against amending commits already in remote main branches, 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

Pre-built binaries are attached to each release. The Linux ones (omni-dev-linux.tar.gz, omni-dev-linux-arm64.tar.gz) are dynamically linked and need glibc 2.35 or newer (Ubuntu 22.04 and Debian 12 qualify). On an older host, such as RHEL 9 or Amazon Linux 2023 (glibc 2.34), they fail in the loader with version `GLIBC_2.xx' not found; build from source with cargo install omni-dev instead. The release workflow fails if a binary needs more than that floor (docs/RELEASE.md).

Next step: see Getting Started — a 10-minute walkthrough from authentication to your first AI-improved commit. (For just the API-key reference, see Authentication.)

Shell Completion

omni-dev completions <shell> prints a completion script to stdout for bash, zsh, fish, powershell, or elvish. The quickest path is bash per-user:

# Add to ~/.bashrc:
eval "$(omni-dev completions bash)"

See docs/shell-completion.md for per-shell install recipes, the $fpath/compinit setup zsh requires, and troubleshooting.

🆚 How omni-dev Compares

omni-dev sits in two adjacent spaces — AI commit-message tooling and Atlassian/dev-workflow MCP servers. The tables below contrast the incumbents on the dimensions a first-time reader is most likely to weigh. In every cell, ✅ means full / native support, ⚠ means partial or available only with caveats, and ❌ means not supported — and omni-dev's own limitations are flagged just as honestly (the ⚠ marks in its own columns).

Beyond these two niches, omni-dev also ships a supervised daemon that hosts a browser bridge (an authenticated proxy that runs requests through a logged-in browser tab for SSO-gated dashboards such as Grafana and Loki), a Snowflake SQL service (one external-browser SSO session reused for concurrent queries), and a worktrees registry (one live view of the repos open across every VS Code window), plus a local append-only request log (omni-dev log). These have no direct incumbent in either table below, so they are called out here rather than scored against tools that don't aim for them.

vs AI commit tools

	omni-dev	opencommit	aicommits
Rewrite existing commits in a range	✅ twiddle	❌ pre-commit only	❌ pre-commit only
Parallel batched processing (long ranges)	✅ --concurrency N	❌	❌
AI-written PR descriptions	✅ git branch create pr	⚠ GitHub Action only	❌
Project-context awareness	✅ --use-context	❌	❌
Sandboxed claude-cli backend	✅ ADR-0028	❌	❌
Multi-backend (Anthropic / Bedrock / OpenAI / Ollama)	✅	✅	✅
Conventional Commits	✅	✅	⚠ config
Language / runtime	Rust (static binary)	Node.js	Node.js

vs Atlassian-workflow MCP servers

omni-dev's MCP server also exposes Git tools (commit analysis, twiddling, PR creation), Datadog tools, and an ai_chat proxy — surfaces the Atlassian-focused servers don't aim for. The table below compares only Atlassian capability depth.

	omni-dev MCP	sooperset/mcp-atlassian	Atlassian official (Rovo)
Jira REST surface	✅ 36 tools (agile, fields, dev panel, links, watchers, worklogs, versions, changelog)	✅ 49 tools (above + JSM, proforma forms, SLA, batch ops)	⚠ 14 tools (basic CRUD, search, transitions, worklogs only)
Confluence REST surface	✅ 25 tools (history, diff, attachments, labels, spaces, inline + footer comments)	✅ 24 tools (history, diff, attachments, labels; no inline comments / spaces)	⚠ 12 tools (inline + footer comments, spaces; no delete / move / history / diff / attachments / labels)
Lossless JFM ↔ ADF round-trip	✅ full ADF node set (schema v56.1.18) + unsupported-node escape	❌	⚠ raw ADF, model-dependent
Anchored review-comment preservation	✅ annotation marks survive round-trip	❌ anchor stripped, comments orphaned	⚠ ADF carries anchors; model-dependent
Pre-flight ADF schema validation	✅ nesting + arity, before write	❌	❌
Offline JFM ↔ ADF conversion (no creds)	✅ atlassian_convert	❌	❌
Cloud + Server + Data Center	⚠ Cloud verified	✅ Cloud + Server (v6+) + DC (Jira v8.14+)	❌ Cloud only
Auth	⚠ API token only	✅ API token / PAT / OAuth 2.0	✅ OAuth 2.1 / API token

Last verified: 2026-06-23. omni-dev and sooperset rows are live-tested — a tools/list enumeration (omni-dev branch build vs ghcr.io/sooperset/mcp-atlassian:latest) plus a live read→write→read fidelity cycle on a complex page. Atlassian Rovo's server accepts the API token but gates tool execution behind an org-admin grant, so its rows combine Atlassian's Supported tools docs with the ADF-passthrough reasoning (raw ADF can round-trip, but only if the model echoes it faithfully — no deterministic guarantee), not a live run. Refresh quarterly or whenever a release-note search for the comparators flags a relevant change.

📋 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

Self-hosted PATs use atlassian auth login --auth-mode bearer without email. See PAT authentication and compatibility limits; most service operations still target Cloud APIs.

📊 Datadog Integration (read-only)

Authenticate against the Datadog API and query metrics, monitors, dashboards, logs, events, SLOs, hosts, and downtimes. See the Datadog integration guide for the full subcommand reference, authentication setup, rate-limit behaviour, and troubleshooting.

# 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

# Query metrics, monitors, dashboards, logs, and SLOs
omni-dev datadog metrics query --query 'avg:system.cpu.user{*}' --from 15m
omni-dev datadog monitor list --tags env:prod
omni-dev datadog dashboard list
omni-dev datadog logs search --filter 'service:api status:error' --from 1h
omni-dev datadog slo list --tags team:platform

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 installs, set DATADOG_API_URL to override the site-derived URL.

All Datadog subcommands are also exposed as MCP tools (datadog_*) — see docs/mcp.md. For the full guide covering every family with worked examples, see docs/datadog.md.

📧 Gmail Integration

Authenticate against your own Gmail account via OAuth2 (loopback authorization-code + PKCE), search/read/label messages and threads, and maintain a durable local archive with gmail sync. New to this integration? Start with the Gmail Quickstart for a zero-to-synced-archive walkthrough; see the Gmail integration guide for prerequisites (you bring your own Google Cloud OAuth2 client — Gmail read scopes require Google's CASA security assessment to distribute otherwise), authentication setup, rate-limit behaviour, and troubleshooting.

# One-time: create your own Google Cloud OAuth2 client (see docs/gmail.md),
# then authenticate (opens a browser)
export GMAIL_CLIENT_ID=...
export GMAIL_CLIENT_SECRET=...
omni-dev gmail auth login

# Verify the credentials by calling users.getProfile
omni-dev gmail auth status

# Search, read messages/threads, and manage labels
omni-dev gmail search --query 'label:finance after:2026/01/01' --limit 50
omni-dev gmail read <message-id>
omni-dev gmail thread <thread-id>
omni-dev gmail label list

# Maintain a durable local archive (.eml files + a JSONL manifest)
omni-dev gmail sync --output-dir ~/mail-archive --query 'label:finance'

An OAuth2 client left in Google's "Testing" publishing status issues refresh tokens that expire after 7 days — see docs/gmail.md for how to avoid re-running auth login weekly.

Every read-only Gmail subcommand except sync is also exposed as an MCP tool (gmail_*) — see docs/mcp.md; sync is CLI-only (a long-running bulk filesystem operation, a poor fit for a synchronous MCP call). For the full guide, see docs/gmail.md.

📁 Drive Integration

Authenticate against your own Google Drive account via OAuth2 (loopback authorization-code + PKCE, the same flow as Gmail), then search files, read their metadata or content, find duplicates, rename/move files, and create, upload, or replace file content. Every write is opt-in twice over. First by OAuth scope: the default drive.readonly covers search/read/dedupe; rename/move need drive.metadata (drive auth login --write), the narrowest write scope Google offers; create/upload need drive.file (--write-file); and editing a file omni-dev did not itself create needs the unrestricted drive scope (--write-full). Second by a local, folder-scoped gate: create/upload/edit resolve the target's ancestor folder chain against per-account rules in settings.json — closest ancestor wins, deny beats allow, and a write with no matching rule is denied — so an OAuth grant alone never authorizes a mutation (see ADR-0071). Inspect that gate with drive permissions show/lookup-folder/check before granting anything. There is still no trash/share/permission-mutation capability anywhere in this surface. drive move is separately security-gated: it refuses any move that would change a file's visibility by default (see ADR-0070). New to this integration? Start with the Drive Quickstart for a zero-to-first-search walkthrough; see the Drive integration guide for prerequisites (you bring your own Google Cloud OAuth2 client, independent of Gmail's), authentication setup, rate-limit behaviour, and troubleshooting.

# One-time: create your own Google Cloud OAuth2 client (see docs/drive.md),
# then authenticate (opens a browser)
export DRIVE_CLIENT_ID=...
export DRIVE_CLIENT_SECRET=...
omni-dev drive auth login

# Verify the credentials by calling about.get
omni-dev drive auth status

# Search and read file metadata/content
omni-dev drive search "name contains 'report'"
omni-dev drive read <file-id>
omni-dev drive read <file-id> --content --out-file report.pdf

# Rename/move need the opt-in drive.metadata scope
omni-dev drive auth login --write
omni-dev drive rename <file-id> "New Name.pdf"
omni-dev drive move <file-id> --to <folder-id>

# Creating/uploading/editing content needs a content scope *and* a
# folder rule in settings.json permitting the destination
omni-dev drive auth login --write-file          # or --write-full to edit
omni-dev drive permissions show                 # what is configured
omni-dev drive permissions check <folder-id> --operation create  # what it decides
omni-dev drive create --name notes.txt --parent <folder-id>
omni-dev drive upload ./report.pdf --parent <folder-id>
omni-dev drive edit <file-id> --content ./report.pdf   # or --content - for stdin

An OAuth2 client left in Google's "Testing" publishing status issues refresh tokens that expire after 7 days — see docs/drive.md for how to avoid re-running auth login weekly.

Five read-only MCP tools (drive_*) mirror the CLI's auth status, search, dedupe, read, and account list — see docs/mcp.md. The mutating verbs — rename/move/create/upload/edit — have no MCP equivalent. For the full guide, see docs/drive.md.

🎙️ Transcript Fetching

Pull captions and transcripts from external media platforms. YouTube is the first supported source; the CLI namespace and library are designed so additional sources (Vimeo, podcast RSS, generic VTT/SRT URLs) can be added without restructuring. See docs/transcript.md for the full reference and the recipe for adding a new source.

# Fetch captions for a YouTube video as SubRip (default).
omni-dev transcript youtube fetch https://www.youtube.com/watch?v=jNQXAC9IVRw

# WebVTT to a file, falling through to auto-generated captions if needed.
omni-dev transcript youtube fetch jNQXAC9IVRw \
  --format vtt --auto --output me-at-the-zoo.vtt

# Synthesise a translated track when no native French track exists.
omni-dev transcript youtube fetch <url> --lang fr --translate fr

# List available caption tracks (manual + auto-generated).
omni-dev transcript youtube list-langs <url>

# Show video metadata (title, channel, duration, languages).
omni-dev transcript youtube info <url> --output json

--format accepts srt, vtt, txt, or json. Locators may be a watch?v= URL, a youtu.be/ short URL, a /shorts/ or /embed/ URL, or a bare 11-character video ID. Age-gated and login-required videos surface as a typed PlayabilityRefused error carrying YouTube's status code rather than a generic HTTP failure.

🌐 Browser Bridge

Drive HTTP requests through an authenticated browser tab. When you are investigating internal services (Grafana/Loki, internal dashboards, SSO-gated admin panels), the browser already holds sessions — SSO, OAuth, cookies — that are hard to replicate programmatically. The bridge issues requests inside the browser's authenticated context without exfiltrating cookies or tokens (a confused deputy by design). Both planes are authenticated and default-closed; see docs/browser-bridge.md for the full guide and ADR-0036 for the security rationale.

# Start the bridge; it prints the bound ports, a session token, and a JS
# snippet to paste into the DevTools console of the authenticated tab.
omni-dev browser bridge serve

# Drive requests through the tab (token from the bridge's stdout).
export OMNI_BRIDGE_TOKEN=<token printed by the bridge>
omni-dev browser bridge request --url /loki/api/v1/labels

# POST a JSON payload from a file, with a custom header.
omni-dev browser bridge request --url /api/foo --method POST \
  --body @payload.json --header "Accept: application/json"

# Stream a long-lived endpoint (SSE / chunked) instead of buffering.
omni-dev browser bridge request --url /api/events --stream

# Route to a specific tab when several are connected (by id or origin).
omni-dev browser bridge request --url /api/foo --target https://grafana.internal

Supports binary and streaming response bodies, multi-tab routing via X-Omni-Bridge-Target, per-request --credentials and --allow-origin overrides, and a transparent proxy for tools that speak plain HTTP.

🛰️ Daemon

Host long-lived services in one supervised process behind a private per-user Unix-domain control socket. The browser bridge is the first service migrated onto it (Snowflake and the worktrees registry followed), and on macOS an optional menu-bar app gives live control. daemon start installs a launchd LaunchAgent for auto-start at login, and status reports every hosted service. See Running under the daemon and ADR-0039 for the architecture.

# Start the background daemon (installs a launchd LaunchAgent on macOS)
omni-dev daemon start

# Per-service status (add --json for machines)
omni-dev daemon status

# Restart or stop it
omni-dev daemon restart
omni-dev daemon stop

The daemon is Unix-only — its control plane is a Unix-domain socket — while the rest of omni-dev runs everywhere.

❄️ Snowflake

Authenticate a Snowflake session once via external-browser SSO, then run concurrent arbitrary SQL across any account without an SSO popup on every query. The daemon holds the session in memory and multiplexes a bounded pool, so each query can still set its own warehouse/role/database/schema. See docs/snowflake-service.md.

# Run SQL (from an argument or stdin); the first query opens the SSO browser
omni-dev snowflake query "select current_version()"

# Per-query context overrides and JSON output
omni-dev snowflake query "select * from t limit 10" \
  --warehouse WH --role ANALYST --database DB --schema PUBLIC --format json

# Inspect or evict live sessions
omni-dev snowflake sessions
omni-dev snowflake disconnect --account <ACCOUNT> --user <USER>

Account/user/context default from SNOWFLAKE_* env vars then ~/.omni-dev/settings.json — no accounts are hardcoded. Runs on the daemon, so it is Unix-only.

📓 Request Log

Every invocation and the HTTP requests it issues are recorded to a local, append-only log you can search and tail. Best-effort and default-on; no secret is ever written (auth headers are redacted, bodies opt-in). See docs/log.md.

# Recent activity (one line each)
omni-dev log

# Filter by service and status class, or a query expression; follow live
omni-dev log --service jira --status 5xx
omni-dev log --query 'method:POST AND status:4xx' --follow

# Full records as JSON (byte-identical to the on-disk lines)
omni-dev log --format json -n 20

Set OMNI_DEV_LOG_DISABLE=1 to turn it off, or OMNI_DEV_LOG_BODIES=1 / OMNI_DEV_LOG_HEADERS=1 to opt into capturing bodies/headers.

🗂️ Worktrees

See every repo and git worktree open across all your VS Code windows in one live view. A VS Code extension host is sandboxed per window — no extension alone can see a sibling window's folders — so a small first-party companion extension registers each window with the daemon, which aggregates them into a single registry served back to the CLI, tray, and extension UI. The registry is in-memory only; windows that crash without unregistering age out automatically. See docs/worktrees-service.md and ADR-0040.

# One line per open window and its folders (add --json for machines)
omni-dev worktrees list

Runs on the daemon, so it is Unix-only.

🤖 Agent Sessions

Track the Claude Code, Codex and pi.dev sessions running across every terminal and VS Code window, each with a coarse live state (working, idle, or waiting on you). Opt-in hooks, the claude-wrap/codex-wrap wrappers, a pi.dev extension and transcript watchers feed the daemon, which keeps the sessions in memory and serves them to the CLI, the tray, worktrees ui and the VS Code worktrees view. See docs/sessions-service.md.

# Install the Claude Code (and, when present, Codex and pi.dev) hooks
omni-dev sessions install-hooks

# One line per live session
omni-dev sessions list

Runs on the daemon, so it is Unix-only.

⚖️ Jev Judgments

omni-dev ai jev is a client for TypeSafe AI's Jev API, which returns typed probabilistic judgments rather than generated text. Beyond the raw choice/score/noul/ask primitives, route asks which model tier each GitHub issue needs to design, implement and review, and verify-decision checks each claim in a decision comment against the sources it cites. See docs/jev.md.

# Which model tier should handle these issues?
omni-dev ai jev route '#1779' '#1820' -o text

✏️ Manual Amendment

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

🧩 Claude Code Slash-Commands

Generate ready-to-use Claude Code slash-command templates into the project's .claude/commands/ directory. Each template is a self-contained workflow that drives a multi-step omni-dev operation from inside a Claude Code session.

# Generate all templates: commit-twiddle, pr-create, pr-update
omni-dev commands generate all

# Or individually
omni-dev commands generate commit-twiddle
omni-dev commands generate pr-create
omni-dev commands generate pr-update

Each subcommand writes .claude/commands/<name>.md. Commit the files to share the workflows with collaborators — Claude Code picks them up automatically, so anyone in the repo can invoke /commit-twiddle, /pr-create, or /pr-update inside a Claude Code session. See the user guide for the full reference.

🗒️ 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.

See docs/user-guide.md#ai-claude-history-sync--export-conversation-history for the in-depth reference, and the broader Claude Code Integration section for related commands (ai chat, ai claude skills).

🔌 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. The server is delivered as a second binary, omni-dev-mcp, gated behind the mcp Cargo feature (see ADR-0021).

Tools cover seven domains:

Domain	Examples
Git (5)	git_view_commits, git_branch_info, git_check_commits, git_twiddle_commits, git_create_pr
JIRA (28)	core read/write/search/transition/comment/link/dev/delete; sprints, boards, watchers, worklogs, fields, attachments, projects, changelog
Confluence (13)	read/write/search/create/delete/download/children, comments, labels, user search
Atlassian shared (2)	atlassian_auth_status, atlassian_convert (offline JFM ↔ ADF)
Datadog (14)	metrics, monitors, dashboards, logs, events, SLOs, hosts, downtimes, metrics catalog
Gmail (8)	gmail_auth_status, gmail_account_list, gmail_search, gmail_message_read, gmail_thread_read, gmail_label_list, gmail_draft_list, gmail_draft_show
AI / Config (5)	ai_chat (one-shot chat), claude_skills_* (sync / clean / status for .claude/skills/ distribution), config_models_show

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
omni-dev://specs/{name}	Embedded reference specs (e.g. jfm)

See docs/mcp.md for the full tool catalog, resource reference, cross-cutting parameters (output_file, confirm), and troubleshooting.

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 any tool interactively, and fetch resources against the current working directory.

Configuration (settings.json)

Three server defaults can be set once in the mcp section of ~/.omni-dev/settings.json instead of per-invocation env vars or flags. All three fields are optional; an absent mcp block leaves the built-in behaviour unchanged.

{
  "mcp": {
    "default_model": "claude-sonnet-4-6",
    "log_level": "info",
    "max_response_bytes": 102400
  }
}

Field	Effect	Fallback
default_model	Model for ai_chat when its model param is omitted	model registry default
log_level	Tracing filter directive for the server	warn (env RUST_LOG overrides)
max_response_bytes	Cap on a tool response before truncation (0 disables)	100 KB

For troubleshooting (stderr logs, RUST_LOG=debug, "failed to open git repository"), see docs/mcp.md#troubleshooting.

⚙️ 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
--fresh	Generate fresh messages from the diffs alone (the default; conflicts with --refine)	--fresh
--refine	Refine the existing messages instead of starting fresh (conflicts with --fresh)	--refine
--use-context	Enable contextual intelligence	--use-context
--work-context TEXT	Describe the work being done to steer suggestions	--work-context "feature: user auth"
--branch-context TEXT	Override the context detected from the branch name	--branch-context "bugfix: login flow"
--context-dir PATH	Custom context directory	--context-dir ./config
--model MODEL	Claude API model to use (defaults from settings)	--model claude-sonnet-4-5
--beta-header KEY:VALUE	Beta header for API requests (model-gated)	--beta-header key:value
--concurrency N	Number of parallel commit processors (default: 4)	--concurrency 3
--no-coherence	Skip cross-commit coherence refinement pass	--no-coherence
--no-ai	Skip AI; amend to a deterministic type/scope suggestion, leaving conforming commits untouched	--no-ai
--auto-apply	Apply without confirmation	--auto-apply
--allow-pushed	Allow amending commits already in remote main branches	--allow-pushed
--check	Validate the messages after applying	--check
--save-only FILE	Save to file without applying	--save-only fixes.yaml
--quiet	Only show errors/warnings	--quiet

See the User Guide's Key Options table for the full reference; omni-dev git commit message twiddle --help is the source of truth.

📖 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

• Getting Started - 10-minute walkthrough from install to first AI-improved commit (start here)
• User Guide - Comprehensive usage guide with examples
• Configuration Guide - Set up contextual intelligence
• Why JFM? - Why omni-dev edits Atlassian content as Markdown instead of raw ADF
• API Documentation - Rust API reference
• Troubleshooting - Common issues and solutions
• Examples - Real-world usage examples
• Release Process - For contributors

🔧 Requirements

• Rust: 1.88+ (for installation from source)
• Claude API Key: Required for AI-powered features
  • See Authentication for setup (env var, .env, or CI/CD secrets)
• AI Model Selection: Optional configuration for specific models
  • View available models: omni-dev config models show
  • Pick per-invocation with --model on an AI command, or configure via OMNI_DEV_MODEL / the per-backend env chain (CLAUDE_MODEL, CLAUDE_CODE_MODEL, ANTHROPIC_MODEL for Claude-family backends; OPENAI_MODEL; OLLAMA_MODEL) or ~/.omni-dev/settings.json
  • 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

omni-dev supports five AI backends. The --ai-backend flag — accepted after the AI commands (git commit message twiddle, git commit message check, git commit message staged, git branch create pr, ai chat), or set via OMNI_DEV_AI_BACKEND — selects one decisively — default, claude-cli, openai, ollama, or bedrock:

• --ai-backend claude-cli — sandboxed claude -p subprocess that reuses your Claude Code session.
• --ai-backend ollama — local Ollama or LM Studio server.
• --ai-backend openai — OpenAI Chat Completions API.
• --ai-backend bedrock — AWS Bedrock.
• --ai-backend default (or no flag) — direct Anthropic API.

When OMNI_DEV_AI_BACKEND is unset, the legacy USE_OLLAMA=true / USE_OPENAI=true / CLAUDE_CODE_USE_BEDROCK=true variables still select their backends, in that order.

See the AI Backends Guide for required env vars, model selection, the Claude CLI sandbox and its escape hatches (--claude-cli-allow-tools, --claude-cli-allow-mcp), the --claude-cli-max-budget-usd spending cap, and per-backend troubleshooting.

🐛 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