panbanda/omen

---

Features

Semantic Search

Natural language code discovery

Search your codebase by meaning, not just keywords. Omen uses a TF-IDF engine with sublinear TF, smooth IDF, and bigram tokenization to find semantically similar code from natural language queries. No external models, no API keys, no GPU required.

# Build the search index
omen search index

# Discard cached entries and rebuild the complete index
omen search index --force

# Search for code
omen search query "database connection pooling"
omen search query "error handling middleware" --top-k 20
omen search query "validation" --min-score 0.5
omen search query "authentication" --files src/auth/,src/middleware/

# Cross-repo search
omen search query "retry logic" --include-project /path/to/other-repo

# Filter by complexity
# (via MCP: semantic_search with max_complexity parameter)

How it works:

1. Symbol extraction - Extracts functions from your codebase using tree-sitter
2. AST-aware chunking - Splits long functions at statement boundaries so each chunk is focused and self-contained. Parent type context (class, struct, impl) is preserved.
3. TF-IDF indexing - Builds a sparse vector index with L2-normalized cosine similarity. Indexes in ~1-2 seconds for typical codebases.
4. Incremental updates - Only re-indexes files that changed since last run
5. Deduplication - Each symbol appears once in results (best-scoring chunk wins)

Queries return at most 10 results by default and discard matches below a similarity score of 0.3. The index is stored in .omen/search.db; subsequent indexing runs update only files whose content hashes changed.

Features:

• HyDE search - Write a hypothetical code snippet as your query for better matches (available via MCP semantic_search_hyde tool)
• Complexity filtering - Exclude high-complexity functions from results (max_complexity parameter on MCP tools)
• Multi-repo search - Query across multiple project indexes with unified IDF scoring (--include-project)
• Per-function metrics - Results include cyclomatic and cognitive complexity when available

Performance:

Why it matters: Traditional grep/ripgrep finds exact matches. Semantic search finds code that means the same thing even with different naming. Ask “how do we validate user input” and find functions named sanitize_params, check_request, or validate_form.

[!TIP] Run omen search index after major refactors or when onboarding to a new codebase. The index updates incrementally on subsequent runs.

Supported Languages

Go, Rust, Python, TypeScript, JavaScript, TSX/JSX, Java, C, C++, C#, Ruby, PHP, Bash (and other languages supported by tree-sitter)

Installation

Homebrew (macOS/Linux)

brew install panbanda/brews/omen

Cargo Install

cargo install omen-cli

Docker

# Pull the latest image
docker pull ghcr.io/panbanda/omen:latest

# Run analysis on current directory
docker run --rm -v "$(pwd):/repo" ghcr.io/panbanda/omen:latest -p /repo all

# Run specific analyzer
docker run --rm -v "$(pwd):/repo" ghcr.io/panbanda/omen:latest -p /repo complexity

# Get repository score
docker run --rm -v "$(pwd):/repo" ghcr.io/panbanda/omen:latest -p /repo score

Multi-arch images are available for linux/amd64 and linux/arm64.

Download Binary

Download pre-built binaries from the releases page.

Build from Source

git clone https://github.com/panbanda/omen.git
cd omen
cargo build --release
# Binary at target/release/omen

Quick Start

# Run all analyzers
omen all

# Check out the analyzers
omen --help

# Minify JSON onto one line (the flag is global and may follow a subcommand)
omen -f json score --compact

# Include rustc dead-code diagnostics; cargo check executes build scripts,
# so use this only on trusted repositories
omen deadcode --cargo-check

The top-level commands are complexity, satd, stubs, deadcode, churn, clones, defect, changes, diff, tdg, graph, hotspot, temporal, ownership, cohesion, repomap, smells, flags, score, mcp, all, context, report, search, mutation, outline, impact, and symbol. Run omen --help for that command’s current options.

Remote Repository Scanning

Analyze any public GitHub repository without cloning it manually:

# GitHub shorthand
omen -p facebook/react complexity
omen -p kubernetes/kubernetes satd

# With specific ref (branch, tag, or commit SHA)
omen -p agentgateway/agentgateway --ref v0.1.0 all
omen -p owner/repo --ref feature-branch all

# Full URLs
omen -p github.com/golang/go all
omen -p https://github.com/vercel/next.js all

# Shallow clone for faster analysis (static analyzers only)
omen -p facebook/react --shallow all

Omen clones to a temp directory, runs analysis, and cleans up automatically. The --shallow flag uses git clone --depth 1 for faster clones but disables git-history-based analyzers (churn, ownership, hotspot, temporal coupling, changes).

Configuration

Automatic configuration discovery loads TOML from omen.toml and then .omen/omen.toml under the analyzed repository. An explicit --config accepts TOML (the default for unrecognized extensions), YAML (.yaml or .yml), or JSON (.json). OMEN_ environment variables override file values; use a double underscore for nested keys, such as OMEN_COMPLEXITY__CYCLOMATIC_ERROR=25.

The accepted top-level keys are exclude, exclude_built_assets, complexity, satd, churn, duplicates, hotspot, score, feature_flags, temporal, and changes. Copy omen.example.toml to omen.toml or .omen/omen.toml and customize it. Configuration structs reject unknown keys, including unknown nested keys, so misspellings produce an error instead of being silently ignored.

[!TIP] Using Claude Code? Run the setup-config skill to analyze your repository and generate an omen.toml with intelligent defaults for your tech stack, including detected feature flag providers and language-specific exclude patterns.

GitHub Action

Omen provides a GitHub Action for automated PR analysis. It runs diff risk analysis and health scoring on every pull request.

Complete workflow

name: Omen Analysis

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  omen:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: panbanda/[email protected]
        id: omen
        with:
          version: latest
          path: .
          comment: true
          label: true
          label-template: 'risk: {{level}}'
          label-color-low: '0e8a16'
          label-color-medium: 'fbca04'
          label-color-high: 'd93f0b'
          check: true
          check-threshold: high
          summary: true
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Print results
        run: |
          echo "Risk: ${{ steps.omen.outputs.risk-level }} (${{ steps.omen.outputs.risk-score }})"
          echo "Health: ${{ steps.omen.outputs.health-grade }} (${{ steps.omen.outputs.health-score }})"

[!IMPORTANT] fetch-depth: 0 is required because history-based analysis needs complete git history. pull-requests: write is required when comment is enabled, and issues: write is required when label is enabled. Workflows that disable those features can omit the corresponding write permissions.

[!NOTE] Pin the action to a release tag (the latest is omen-v4.26.1) and bump it as new releases ship. The version: latest input above controls which omen binary the action downloads and is independent of the action tag.

Inputs

Outputs

All outputs are available for chaining into downstream steps:

If a JSON output exceeds the GitHub Actions output-size guard, the action returns a temporary file path instead of inline JSON. Consumers should accept either form.

MCP Server

Omen includes a Model Context Protocol (MCP) server that exposes all analyzers as tools for LLMs like Claude. This enables AI assistants to analyze codebases directly.

The server uses stdio transport only: omen mcp and omen mcp --transport stdio are equivalent. Tool paths are confined to the configured repository root by default; omen mcp --allow-external-paths opts out of that boundary for clients that intentionally need broader filesystem access. There are no host or port options for the MCP server.

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "omen": {
      "command": "omen",
      "args": ["mcp"]
    }
  }
}

Claude Code

claude mcp add omen -- omen mcp

Example Usage

Once configured, you can ask Claude:

• “Analyze the complexity of this codebase”
• “Find technical debt in the src directory”
• “What are the hotspot files that need refactoring?”
• “Show me the bus factor risk for this project”
• “Find stale feature flags that should be removed”

Claude Code Plugin

Omen is available as a Claude Code plugin, providing analysis-driven skills that guide Claude through code analysis workflows.

Installation

/plugin install panbanda/omen

Verify installation with /skills to see available Omen skills.

Prerequisites

Skills invoke the omen CLI directly, so they require the omen binary on your PATH (see Installation). Installing the plugin also registers the Omen MCP server automatically (command: omen, args: ["mcp"]) via each plugin’s mcpServers declaration, so no manual command entry is needed; you can still configure it by hand (see the MCP Server section above) if you prefer.

Real-World Repository Analysis Examples

The examples/repos/ directory contains comprehensive health reports for popular open-source projects, demonstrating Omen’s capabilities across different languages and project types.

Analyzed Repositories

What the Reports Demonstrate

1. Health Score Breakdown Each report shows how the composite score is calculated from individual components (complexity, duplication, SATD, coupling, etc.) and explains why certain scores are what they are.

2. Hotspot Analysis Reports identify files with high churn AND high complexity - the most impactful refactoring targets. For example, gin’s tree.go has a hotspot score of 0.54 due to its radix tree routing complexity.

3. Technical Debt Gradient (TDG) Files are graded A-F based on accumulated technical debt. The reports explain what drives low grades and prioritize cleanup efforts.

4. PR Risk Analysis Each report includes a real PR analysis demonstrating omen diff:

omen -f markdown diff --target main

Example from gin-gonic/gin (#4420 - add escaped path option):

Risk Score: 0.31 (MEDIUM)
Lines Added:    63
Lines Deleted:  2
Files Modified: 2

Risk Factors:
  entropy:        0.084
  lines_added:    0.118
  num_files:      0.050

Understanding Risk Factors:

• Risk Score - LOW ( 0.5)
• Entropy - How scattered changes are (0 = concentrated, 1 = everywhere)
• Lines Added/Deleted Ratio - Net code reduction is often a good sign
• Files Modified - More files = more potential for cascading issues

5. CI/CD Integration Reports include GitHub Actions workflow examples for quality gates and PR risk assessment.

Generating Your Own Reports

Run a comprehensive analysis on any repository:

# Local repository
omen score
omen hotspot
omen tdg

# Remote repository
omen -p facebook/react score
omen -p kubernetes/kubernetes hotspot

# PR risk before merging
omen diff --target main

# Track score trends over time
omen score trend --period monthly --since 6m

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -am 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a Pull Request

Acknowledgments

Omen draws heavy inspiration from paiml-mcp-agent-toolkit - a fantastic CLI and comprehensive suite of code analysis tools for LLM workflows. If you’re doing serious AI-assisted development, it’s worth checking out. Omen exists as a streamlined alternative for teams who want a focused subset of analyzers without the additional dependencies. If you’re looking for a Rust-focused MCP/agent generator as an alternative to Python, it’s definitely worth checking out.

License

Apache License 2.0 - see LICENSE for details.