Omen

Your AI writes code without knowing where the landmines are.

Omen gives AI assistants the context they need: complexity hotspots, hidden dependencies, defect-prone files, and self-admitted debt. One command surfaces what's invisible.

Why "Omen"? An omen is a sign of things to come - good or bad. Your codebase is full of omens: low complexity and clean architecture signal smooth sailing ahead, while high churn, technical debt, and code clones warn of trouble brewing. Omen surfaces these signals so you can act before that "temporary fix" celebrates its third anniversary in production.

---

Features

Complexity Analysis - How hard your code is to understand and test

There are two types of complexity:

• Cyclomatic Complexity counts the number of different paths through your code. Every if, for, while, or switch creates a new path. A function with cyclomatic complexity of 10 means there are 10 different ways to run through it. The higher the number, the more test cases you need to cover all scenarios.

• Cognitive Complexity measures how hard code is for a human to read. It penalizes deeply nested code (like an if inside a for inside another if) more than flat code. Two functions can have the same cyclomatic complexity, but the one with deeper nesting will have higher cognitive complexity because it's harder to keep track of.

Why it matters: Research shows that complex code has more bugs and takes longer to fix. McCabe's original 1976 paper found that functions with complexity over 10 are significantly harder to maintain. SonarSource's cognitive complexity builds on this by measuring what actually confuses developers.

[!TIP] Keep cyclomatic complexity under 10 and cognitive complexity under 15 per function.

Self-Admitted Technical Debt (SATD) - Comments where developers admit they took shortcuts

When developers write TODO: fix this later or HACK: this is terrible but works, they're creating technical debt and admitting it. Omen finds these comments and groups them by type:

Category	Markers	What it means
Design	HACK, KLUDGE, SMELL	Architecture shortcuts that need rethinking
Defect	BUG, FIXME, BROKEN	Known bugs that haven't been fixed
Requirement	TODO, FEAT	Missing features or incomplete implementations
Test	FAILING, SKIP, DISABLED	Tests that are broken or turned off
Performance	SLOW, OPTIMIZE, PERF	Code that works but needs to be faster
Security	SECURITY, VULN, UNSAFE	Known security issues

Why it matters: Potdar and Shihab's 2014 study found that SATD comments often stay in codebases for years. The longer they stay, the harder they are to fix because people forget the context. Maldonado and Shihab (2015) showed that design debt is the most common and most dangerous type.

[!TIP] Review SATD weekly. If a TODO is older than 6 months, either fix it or delete it.

Stubs Detection - Incomplete or placeholder implementations left unfinished

SATD is debt a developer chose to keep; a stub is work that was never finished - the kind of thing an agent or human leaves behind mid-task. Omen finds stubs via tree-sitter AST analysis (never plain string matching, so string literals containing trigger words are never false positives) and groups them by pattern type:

Category	Severity	What it means
not_implemented	High	Explicit not-implemented idioms: todo!(), raise NotImplementedError, throw new Error('not implemented')
elision	Medium	Comments admitting skipped work: // ... rest of the implementation, // placeholder, // your code here
empty_body	Medium	A function/method with an empty body that can't legitimately be empty (non-void return type, or an elision comment inside)

omen stubs

# Fail CI if any stub is found
omen stubs --gate error

# Only fail on high-severity stubs (todo!()-style idioms), warn on the rest
omen stubs --gate error --gate-severity high
omen stubs --gate warn

Why it matters: Unfinished work that looks complete (it compiles, it's committed) is more dangerous than code that's obviously missing - nothing signals it needs attention until it's called in production. Stubs feed into the composite health score's debt component alongside SATD, so unresolved stubs lower your repo's score just like unresolved TODOs do.

[!TIP] Add omen stubs --gate error to CI to block merges that leave todo!() or NotImplementedError behind.

Dead Code Detection - Code that exists but never runs

Dead code includes:

• Functions that are never called
• Variables that are assigned but never used
• Classes that are never instantiated
• Code after a return statement that can never execute

Why it matters: Dead code isn't just clutter. It confuses new developers who think it must be important. It increases build times and binary sizes. Worst of all, it can hide bugs - if someone "fixes" dead code thinking it runs, they've wasted time. Romano et al. (2020) found that dead code is a strong predictor of other code quality problems.

[!TIP] Delete dead code. Version control means you can always get it back if needed.

Git Churn Analysis - How often files change over time

Churn looks at your git history and counts:

• How many times each file was modified
• How many lines were added and deleted
• Which files change together

Files with high churn are "hotspots" - they're constantly being touched, which could mean they're:

• Central to the system (everyone needs to modify them)
• Poorly designed (constant bug fixes)
• Missing good abstractions (features keep getting bolted on)

Why it matters: Nagappan and Ball's 2005 research at Microsoft found that code churn is one of the best predictors of bugs. Files that change a lot tend to have more defects. Combined with complexity data, churn helps you find the files that are both complicated AND frequently modified - your highest-risk code.

[!TIP] If a file has high churn AND high complexity, prioritize refactoring it.

Code Clone Detection - Duplicated code that appears in multiple places

There are three types of clones:

Type	Description	Example
Type-1	Exact copies (maybe different whitespace/comments)	Copy-pasted code
Type-2	Same structure, different names	Same function with renamed variables
Type-3	Similar code with some modifications	Functions that do almost the same thing

Why it matters: When you fix a bug in one copy, you have to remember to fix all the other copies too. Juergens et al. (2009) found that cloned code has significantly more bugs because fixes don't get applied consistently. The more clones you have, the more likely you'll miss one during updates.

[!TIP] Anything copied more than twice should probably be a shared function. Aim for duplication ratio under 5%.

Defect Prediction - The likelihood that a file contains bugs

Omen combines multiple signals to predict defect probability using PMAT-weighted metrics:

• Process metrics (churn frequency, ownership diffusion)
• Metrics (cyclomatic/cognitive complexity)
• Age (code age and stability)
• Total size (lines of code)

Each file gets a risk score from 0% to 100%.

Why it matters: You can't review everything equally. Menzies et al. (2007) showed that defect prediction helps teams focus testing and code review on the files most likely to have problems. Rahman et al. (2014) found that even simple models outperform random file selection for finding bugs.

[!TIP] Prioritize code review for files with >70% defect probability.

Change Risk Analysis (JIT) - Predict which commits are likely to introduce bugs

Just-in-Time (JIT) defect prediction analyzes recent commits to identify risky changes before they cause problems. Unlike file-level prediction, JIT operates at the commit level using change-scope factors from Kamei et al. (2013), augmented with file-level risk signals from the software engineering research literature.

Change-scope factors (75% of score):

Weighted using Kamei's median logistic regression coefficients (relative ordering across projects):

Factor	Name	Weight	What it measures
LA	Lines Added	0.16	More additions = more risk (strongest predictor)
ENTROPY	Change Entropy	0.14	Scattered changes = harder to review
FIX	Bug Fix	0.12	Bug fix commits indicate problematic areas
LD	Lines Deleted	0.08	Deletions are generally safer
NF	Number of Files	0.08	More files = more coordination risk
NUC	Unique Changes	0.07	More unique prior commits on files
NDEV	Number of Developers	0.05	More developers on files = more risk
EXP	Developer Experience	0.05	Less experience = more risk

File-level risk signals (25% of score):

Signal	Weight	Source
File Churn	0.10	Nagappan & Ball (2005) - historical change frequency predicts defects
File Complexity	0.08	Zimmermann & Nagappan (2008) - cyclomatic complexity is predictive but weaker than change metrics
Ownership Diffusion	0.07	Bird et al. (2011) - files with many minor contributors (no clear owner) have more defects

Ownership diffusion is 1 - max_author_percentage: files where no single author dominates score higher risk. This follows Bird et al.'s finding that concentrated ownership (a clear primary author) correlates with fewer defects, while diffuse ownership correlates with more.

Percentile-based risk classification:

Risk levels use percentile-based thresholds following JIT defect prediction best practices. Rather than fixed thresholds, commits are ranked relative to the repository's own distribution:

Level	Percentile	Meaning
High	Top 5%	P95+ - Deserve extra scrutiny
Medium	Top 20%	P80-P95 - Worth additional attention
Low	Bottom 80%	Below P80 - Standard review process

This approach aligns with the 80/20 rule from defect prediction research: ~20% of code changes contain ~80% of defects. It ensures actionable results regardless of repository characteristics - well-disciplined repos will have lower thresholds, while high-churn repos will have higher ones.

Why it matters: Kamei et al. (2013) demonstrated that JIT prediction catches risky changes at commit time, before bugs propagate. Their effort-aware approach uses ranking rather than fixed thresholds, focusing limited review resources on the riskiest ~20% of commits. Zeng et al. (2021) showed that simple JIT models match deep learning accuracy (~65%) with better interpretability.

[!TIP] Run omen changes before merging PRs to identify commits needing extra review.

PR/Branch Diff Risk Analysis - Assess overall risk of a branch before merging

While JIT analysis examines individual commits, diff analysis evaluates an entire branch's cumulative changes against a target branch. This gives reviewers a quick risk assessment before diving into code review.

Usage:

# Compare current branch against main
omen diff --target main

# Compare against a specific commit
omen diff --target abc123

# Output as markdown for PR comments
omen -f markdown diff --target main

Risk Factors:

The diff analyzer uses the same research-backed weight model as omen changes (see above), combining change-scope factors with file-level signals:

Factor	What it measures	Category
Lines Added	Total new code introduced	Change-scope
Lines Deleted	Code removed	Change-scope
Files Modified	Spread of changes	Change-scope
Commits	Number of commits in branch	Change-scope
Entropy	How scattered changes are	Change-scope
File Churn	Historical change frequency of touched files	File-level
File Complexity	Max cyclomatic complexity of touched files	File-level
Ownership Diffusion	How diffusely owned the touched files are	File-level

Risk Score Interpretation:

Score	Level	Recommended Action
< 0.2	LOW	Standard review process
0.2 - 0.5	MEDIUM	Careful review, consider extra testing
> 0.5	HIGH	Thorough review, ensure comprehensive test coverage

Example Output:

Branch Diff Risk Analysis
==========================

Source:   feature/new-api
Target:   main
Base:     abc123def

Risk Score: 0.31 (MEDIUM)

Changes:
  Lines Added:    530
  Lines Deleted:  39
  Files Modified: 3
  Commits:        1

Risk Factors:
  entropy:              0.023
  lines_added:          0.140
  lines_deleted:        0.008
  num_files:            0.014
  commits:              0.007
  file_churn:           0.080
  file_complexity:      0.045
  ownership_diffusion:  0.000

File Risk:
  max_complexity:       6.78
  max_churn:            1.00
  ownership_diffusion:  0.00

What to Look For:

• High lines added, low deleted - New feature, needs thorough review
• Balanced add/delete - Refactoring, verify behavior unchanged
• Net code reduction - Cleanup/simplification, generally positive
• High entropy - Scattered changes, check for unrelated modifications
• Many files - Wide impact, ensure integration testing
• High file_churn - Touching historically volatile files that change often
• High ownership_diffusion - No clear owner for the touched files; ensure someone takes responsibility for review

CI/CD Integration:

# Add to GitHub Actions workflow
- name: PR Risk Assessment
  run: |
    omen -f markdown diff --target ${{ github.base_ref }} >> $GITHUB_STEP_SUMMARY

Why it matters: Code review time is limited. Diff analysis helps reviewers prioritize their attention - a LOW risk PR with 10 lines changed needs less scrutiny than a MEDIUM risk PR touching 17 files. The entropy metric is particularly useful for catching PRs that bundle unrelated changes, which are harder to review and more likely to introduce bugs.

[!TIP] Run omen diff before creating a PR to understand how reviewers will perceive your changes. Consider splitting HIGH risk PRs into smaller, focused changes.

Technical Debt Gradient (TDG) - A composite "health score" for each file

TDG combines multiple metrics into a single score (0-100 scale, higher is better):

Component	Max Points	What it measures
Structural Complexity	20	Cyclomatic complexity and nesting depth
Semantic Complexity	15	Cognitive complexity
Duplication	15	Amount of cloned code
Coupling	15	Dependencies on other modules
Hotspot	10	Churn x complexity interaction
Temporal Coupling	10	Co-change patterns with other files
Consistency	10	Code style and pattern adherence
Entropy	10	Pattern entropy and code uniformity
Documentation	5	Comment coverage

Why it matters: Technical debt is like financial debt - a little is fine, too much kills you. Cunningham coined the term in 1992, and Kruchten et al. (2012) formalized how to measure and manage it. TDG gives you a single number to track over time and compare across files.

[!TIP] Fix files with scores below 70 before adding new features. Track average TDG over time - it should go up, not down.

Dependency Graph - How your modules connect to each other

Omen builds a graph showing which files import which other files, then calculates:

• PageRank: Which files are most "central" (many things depend on them)
• Betweenness: Which files are "bridges" between different parts of the codebase
• Coupling: How interconnected modules are

Why it matters: Highly coupled code is fragile - changing one file breaks many others. Parnas's 1972 paper on modularity established that good software design minimizes dependencies between modules. The dependency graph shows you where your architecture is clean and where it's tangled.

[!TIP] Files with high PageRank should be especially stable and well-tested. Consider breaking up files that appear as "bridges" everywhere.

Hotspot Analysis - High-risk files where complexity meets frequent changes

Hotspots are files that are both complex AND frequently modified. A simple file that changes often is probably fine - it's easy to work with. A complex file that rarely changes is also manageable - you can leave it alone. But a complex file that changes constantly? That's where bugs breed.

Omen calculates hotspot scores using the geometric mean of normalized churn and complexity:

hotspot = sqrt(churn_percentile * complexity_percentile)

Both factors are normalized against industry benchmarks using empirical CDFs, so scores are comparable across projects:

• Churn percentile - Where this file's commit count ranks against typical OSS projects
• Complexity percentile - Where the average cognitive complexity ranks against industry benchmarks

Hotspot Score	Severity	Action
>= 0.6	Critical	Prioritize immediately
>= 0.4	High	Schedule for review
>= 0.25	Moderate	Monitor
< 0.25	Low	Healthy

Why it matters: Adam Tornhill's "Your Code as a Crime Scene" introduced hotspot analysis as a way to find the most impactful refactoring targets. His research shows that a small percentage of files (typically 4-8%) contain most of the bugs. Graves et al. (2000) and Nagappan et al. (2005) demonstrated that relative code churn is a strong defect predictor.

[!TIP] Start refactoring with your top 3 hotspots. Reducing complexity in high-churn files has the highest ROI.

Temporal Coupling - Files that change together reveal hidden dependencies

When two files consistently change in the same commits, they're temporally coupled. This often reveals:

• Hidden dependencies not visible in import statements
• Logical coupling where a change in one file requires a change in another
• Accidental coupling from copy-paste or inconsistent abstractions

Omen analyzes your git history to find file pairs that change together:

Coupling Strength	Meaning
> 80%	Almost always change together - likely tight dependency
50-80%	Frequently coupled - investigate the relationship
20-50%	Moderately coupled - may be coincidental
< 20%	Weakly coupled - probably independent

Why it matters: Ball et al. (1997) first studied co-change patterns at AT&T and found they reveal architectural violations invisible to static analysis. Beyer and Noack (2005) showed that temporal coupling predicts future changes - if files changed together before, they'll likely change together again.

[!TIP] If two files have >50% temporal coupling but no import relationship, consider extracting a shared module or merging them.

Code Ownership/Bus Factor - Knowledge concentration and team risk

Bus factor asks: "How many people would need to be hit by a bus before this code becomes unmaintainable?" Low bus factor means knowledge is concentrated in too few people.

Omen uses git blame to calculate:

• Primary owner - Who wrote most of the code
• Ownership ratio - What percentage one person owns
• Contributor count - How many people have touched the file
• Bus factor - Number of major contributors (>5% of code)

Ownership Ratio	Risk Level	What it means
> 90%	High risk	Single point of failure
70-90%	Medium risk	Limited knowledge sharing
50-70%	Low risk	Healthy distribution
< 50%	Very low	Broad ownership

Why it matters: Bird et al. (2011) found that code with many minor contributors has more bugs than code with clear ownership, but code owned by a single person creates organizational risk. The sweet spot is 2-4 significant contributors per module. Nagappan et al. (2008) showed that organizational metrics (like ownership) predict defects better than code metrics alone.

[!TIP] Files with >80% single ownership should have documented knowledge transfer. Critical files should have at least 2 people who understand them.

CK Metrics - Object-oriented design quality measurements

The Chidamber-Kemerer (CK) metrics suite measures object-oriented design quality:

Metric	Name	What it measures	Threshold
WMC	Weighted Methods per Class	Sum of method complexities	< 20
CBO	Coupling Between Objects	Number of other classes used	< 10
RFC	Response for Class	Methods that can be invoked	< 50
LCOM	Lack of Cohesion in Methods	Methods not sharing fields	< 3
DIT	Depth of Inheritance Tree	Inheritance chain length	< 5
NOC	Number of Children	Direct subclasses	< 6

LCOM (Lack of Cohesion) is particularly important. Low LCOM means methods in a class use similar instance variables - the class is focused. High LCOM means the class is doing unrelated things and should probably be split.

Why it matters: Chidamber and Kemerer's 1994 paper established these metrics as the foundation of OO quality measurement. Basili et al. (1996) validated them empirically, finding that WMC and CBO strongly correlate with fault-proneness. These metrics have been cited thousands of times and remain the standard for OO design analysis.

[!TIP] Classes violating multiple CK thresholds are candidates for refactoring. High WMC + high LCOM often indicates a "god class" that should be split.

Repository Map - PageRank-ranked symbol index for LLM context

Repository maps provide a compact summary of your codebase's important symbols, ranked by structural importance using PageRank. This is designed for LLM context windows - you get the most important functions and types first.

For each symbol, the map includes:

• Name and kind (function, class, method, interface)
• File location and line number
• Signature for quick understanding
• PageRank score based on how many other symbols depend on it
• In/out degree showing dependency connections

Why it matters: LLMs have limited context windows. Stuffing them with entire files wastes tokens on less important code. PageRank, developed by Brin and Page (1998), identifies structurally important nodes in a graph. Applied to code, it surfaces the symbols that are most central to understanding the codebase.

Scalability: Omen uses a sparse power iteration algorithm for PageRank computation, scaling linearly with the number of edges O(E) rather than quadratically with nodes O(V^2). This enables fast analysis of large monorepos with 25,000+ symbols in under 30 seconds.

Example output:

# Repository Map (Top 20 symbols by PageRank)

## parser.ParseFile (function) - pkg/parser/parser.go:45
  PageRank: 0.0823 | In: 12 | Out: 5
  func ParseFile(path string) (*Result, error)

## models.TdgScore (struct) - pkg/models/tdg.go:28
  PageRank: 0.0651 | In: 8 | Out: 3
  type TdgScore struct

[!TIP] Use omen repomap --top 50 for the 50 highest-ranked symbols, or omen context --max-tokens 8000 for broader agent context.

Feature Flag Detection - Find and track feature flags across your codebase

Feature flags are powerful but dangerous. They let you ship code without enabling it, run A/B tests, and roll out features gradually. But they accumulate. That "temporary" flag from 2019 is still in production. The flag you added for a one-week experiment is now load-bearing infrastructure.

Omen detects feature flag usage across popular providers:

Provider	Languages	What it finds
LaunchDarkly	JS/TS	variation(), boolVariation() calls
Split	JS/TS	getTreatment() calls
Unleash	JS/TS, Python	isEnabled(), is_enabled() calls
Flipper	Ruby	Flipper[:flag], enabled?() calls
ENV-based	Ruby, JS/TS, Python	ENV["FEATURE_*"], process.env.FEATURE_*

Additional providers can be added via custom tree-sitter queries in your omen.toml configuration.

For each flag, Omen reports:

• Flag key - The identifier used in code
• Provider - Which SDK is being used
• References - All locations where the flag is checked
• Staleness - When the flag was first and last modified (with git history)

Custom providers: For in-house feature flag systems, define custom tree-sitter queries in your omen.toml:

[[feature_flags.custom_providers]]
name = "feature"
languages = ["ruby"]
query = '''
(call
  receiver: (constant) @receiver
  (#eq? @receiver "Feature")
  method: (identifier) @method
  (#match? @method "^(enabled\\?|get_feature_flag)$")
  arguments: (argument_list
    .
    (simple_symbol) @flag_key))
'''

Why it matters: Meinicke et al. (2020) studied feature flags across open-source projects and found that flag ownership (the developer who introduces a flag also removes it) correlates with shorter flag lifespans, helping keep technical debt in check. Rahman et al. (2018) studied Google Chrome's 12,000+ feature toggles and found that while they enable rapid releases and flexible deployment, they also introduce technical debt and additional maintenance burden. Regular flag audits prevent your codebase from becoming a maze of unused toggles.

[!TIP] Audit feature flags monthly. Remove flags older than 90 days for experiments, 14 days for release flags. Track flag staleness in your CI pipeline.

Repository Score - Composite health score (0-100)

Omen computes a composite repository health score (0-100) that combines multiple analysis dimensions. This provides a quick overview of codebase quality and enables quality gates in CI/CD.

Score Components:

Component	Weight	What it measures
Complexity	25%	% of functions exceeding complexity thresholds
Duplication	20%	Code clone ratio with non-linear penalty curve
SATD	10%	Severity-weighted TODO/FIXME density, plus unresolved stubs (todo!(), NotImplementedError, etc.)
TDG	15%	Technical Debt Gradient composite score
Coupling	10%	Cyclic deps, SDP violations, and instability
Smells	5%	Architectural smells relative to codebase size
Cohesion	15%	Class cohesion (LCOM) for OO codebases

Normalization Philosophy:

Each component metric is normalized to a 0-100 scale where higher is always better. The normalization functions are designed to be:

1. Fair - Different metrics with similar severity produce similar scores
2. Calibrated - Based on industry benchmarks from SonarQube, CodeClimate, and CISQ
3. Non-linear - Gentle penalties for minor issues, steep for severe ones
4. Severity-aware - Weight items by impact, not just count

For example, SATD (Self-Admitted Technical Debt) uses severity-weighted scoring:

• Critical (SECURITY, VULN): 4x weight
• High (FIXME, BUG): 2x weight
• Medium (HACK, REFACTOR): 1x weight
• Low (TODO, NOTE): 0.25x weight

This prevents low-severity items (like documentation TODOs) from unfairly dragging down scores.

TDG (Technical Debt Gradient) provides a complementary view by analyzing structural complexity, semantic complexity, duplication patterns, and coupling within each file.

Usage:

# Compute repository score
omen score

# JSON output for CI integration
omen -f json score

Adjusting thresholds:

Achieving a score of 100 is nearly impossible for real-world codebases. Set realistic thresholds in omen.toml based on your codebase:

[score]
fail_under = 70.0

Run omen score to see your current scores, then set thresholds slightly below those values. Gradually increase them over time.

Enforcing on commit with Lefthook:

Add to lefthook.yml:

pre-push:
  commands:
    omen-score:
      run: omen score

This prevents pushing code that fails your quality thresholds.

Why it matters: A single health score enables quality gates, tracks trends over time, and provides quick codebase assessment. The weighted composite ensures that critical issues (defects, complexity) have more impact than cosmetic ones.

[!TIP] Start with achievable thresholds and increase them as you improve your codebase. Duplication is often the hardest metric to improve in legacy code.

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:

Metric	Value
Index time	~1-2s (1,400 symbols)
Query time	~250ms
Storage	SQLite in .omen/search.db
Dependencies	Zero external (pure Rust TF-IDF)

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.

Mutation Testing - Test suite effectiveness through code mutation

Mutation testing measures how well your test suite catches bugs by introducing small changes (mutations) to your code and checking if tests fail. A "killed" mutant means tests caught the bug; a "surviving" mutant means a bug could slip through.

21 Mutation Operators:

Category	Operators	What they mutate
Core	CRR, ROR, AOR, COR, UOR	Literals, relational ops, arithmetic, conditionals, unary
Advanced	SDL, RVR, BVO, BOR, ASR	Statement deletion, return values, boundaries, bitwise, assignment
Rust	BorrowOperator, OptionOperator, ResultOperator	Borrow semantics, Option/Result handling
Go	GoErrorOperator, GoNilOperator	Error handling, nil checks
TypeScript	TSEqualityOperator, TSOptionalOperator	===/==, optional chaining
Python	PythonIdentityOperator, PythonComprehensionOperator	is/==, list comprehensions
Ruby	RubyNilOperator, RubySymbolOperator	nil handling, symbol/string conversion

Features:

• Parallel execution - Async worker pool with work-stealing for efficient mutation testing
• Equivalent mutant detection - ML-based scoring to identify semantically equivalent mutations
• Coverage integration - Parse LLVM-cov, Istanbul, coverage.py, and Go coverage to skip untested code
• Incremental mode - Only test mutations in changed files
• CI/CD integration - Quality gates and GitHub integration

Usage:

# Generate mutants (dry run) with default operators (CRR, ROR, AOR)
omen mutation --dry-run

# Run mutation testing with all operators
omen mutation --mode thorough

# Fast mode (excludes operators that produce more equivalent mutants)
omen mutation --mode fast

# Run with coverage data to skip untested code
omen mutation --coverage coverage.json

# Incremental mode for CI - only test changed files
omen mutation --incremental

# Control parallelism
omen mutation --jobs 8

# Output surviving mutants for investigation
omen mutation --output-survivors survivors.json

# Filter to specific files
omen mutation --glob "src/analyzers/*.rs"

# Analyze a dirty working tree (review the changes first)
omen mutation --allow-dirty

By default mutation testing refuses to run with uncommitted changes so it cannot overwrite work while applying mutants. Use --allow-dirty only when you have reviewed and protected the current changes.

ML-Based Prediction:

Omen includes an ML model that learns from your mutation testing history to predict which mutants will survive. This enables two optimizations:

1. Skip obvious kills - Don't waste time testing mutants the model is confident will be caught
2. Better equivalent detection - Learn which patterns in your codebase produce equivalent mutants

# Record results to history file for later training
omen mutation --record

# Train the model from accumulated history
omen mutation train

# Use trained model to skip high-confidence kills (saves time)
omen mutation --skip-predicted 0.95

# Use a custom model path
omen mutation --model path/to/model.json

Training Workflow:

1. Collect data: Run omen mutation --record on your codebase. Each mutant's outcome (killed/survived) is appended to .omen/mutation-history.jsonl along with:

   • Mutant details (operator, location, original/mutated code)
   • Source context (5 lines before/after the mutation)
   • Execution time

2. Train model: Run omen mutation train to train the predictor. The model learns:

   • Operator-specific kill rates for your codebase
   • Feature weights correlating code patterns with survival

3. Use predictions: Future runs automatically load .omen/mutation-model.json. Use --skip-predicted 0.9 to skip mutants with >90% predicted kill probability.

Example CI workflow:

# Weekly: full run with recording
omen mutation --record --mode thorough

# After accumulating history: train model
omen mutation train

# Daily CI: fast run using predictions
omen mutation --incremental --skip-predicted 0.95

[!NOTE] The .omen/ directory is gitignored by default. If you want to share the trained model across your team, remove .omen/mutation-model.json from your .gitignore.

Mutation Score:

The mutation score measures test suite effectiveness:

mutation_score = killed_mutants / (total_mutants - equivalent_mutants)

Score	Quality	Meaning
> 80%	Excellent	Strong test suite that catches most bugs
60-80%	Good	Reasonable coverage, some gaps to address
40-60%	Moderate	Significant testing gaps
< 40%	Poor	Tests miss many potential bugs

Why it matters: Code coverage tells you what code runs during tests, but not whether tests actually verify behavior. A function can have 100% coverage yet 0% mutation score if assertions are missing. Jia and Harman (2011) showed that mutation testing correlates strongly with fault detection. Papadakis et al. (2019) demonstrated it outperforms other test adequacy criteria.

[!TIP] Start with --mode fast on CI for quick feedback, and run --mode thorough periodically for comprehensive analysis. Use --coverage to avoid wasting time on untested code.

MCP Server - LLM tool integration via Model Context Protocol

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 through standardized tool calls.

Available tools:

• context - Agent-oriented repository overview and navigation hints
• outline - Token-cheap imports, classes, and function outline
• complexity - Cyclomatic and cognitive complexity
• satd - Self-admitted technical debt detection
• stubs - Incomplete/placeholder implementation detection (read-only; does not gate)
• deadcode - Unused functions and variables
• churn - Git file change frequency
• clones - Code clones detection
• defect - File-level defect probability (PMAT)
• changes - Commit-level change risk (JIT)
• diff - Branch diff risk analysis
• tdg - Technical Debt Gradient scores
• graph - Dependency graph generation
• hotspot - High churn + complexity files
• temporal - Files that change together
• ownership - Code ownership and bus factor
• cohesion - CK OO metrics
• repomap - PageRank-ranked symbol map
• smells - Architectural smell detection
• flags - Feature flag detection and staleness
• score - Composite health score (0-100)
• semantic_search - Natural language code search
• get_symbol - Source, signature, location, relationships, and complexity for one symbol
• impact - Transitive caller/callee blast-radius analysis
• semantic_search_hyde - HyDE-style search (query with a hypothetical code snippet)

Each tool honors the parameters advertised in its MCP input schema. Every tool also accepts limit (default 50) and offset (default 0). JSON responses are serialized compactly and wrapped in an envelope containing tool, total_items, returned, offset, and result (plus git_skipped_reason when applicable). Some tools can return agent-facing Markdown when their advertised format parameter allows it.

Why it matters: LLMs work best when they have access to structured tools rather than parsing unstructured output. MCP provides a standard interface for Claude Desktop and other compatible assistants, while pagination keeps large results within context budgets.

[!TIP] Configure omen as an MCP server in your AI assistant to enable natural language queries like "find the most complex functions" or "show me technical debt hotspots."

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 <command> --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 <PATH> 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/omen@omen-v4.26.1
        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

Input	Default	Description
version	latest	Omen version to install
path	.	Repository path to analyze
comment	false	Post/update a sticky PR comment
label	false	Add a risk-level label
label-template	risk: {{level}}	Label name template ({{level}} is replaced with low, medium, or high)
label-color-low	0e8a16	Hex color (without #) for the low-risk label
label-color-medium	fbca04	Hex color (without #) for the medium-risk label
label-color-high	d93f0b	Hex color (without #) for the high-risk label
check	false	Fail if risk meets threshold
check-threshold	high	Risk level to fail on (low, medium, high)
summary	true	Write risk, change-size, health, and component results to the job summary
github-token	${{ github.token }}	Token used to resolve releases and manage enabled PR comments/labels

Outputs

All outputs are available for chaining into downstream steps:

Output	Example	Description
risk-score	0.42	Diff risk score (0.0 - 1.0); empty outside pull requests
risk-level	medium	Risk level (low, medium, high); empty outside pull requests
health-score	76.9	Health score (0 - 100)
health-grade	C	Health grade (A - F)
diff-json	{...}	Full omen diff JSON; empty outside pull requests
score-json	{...}	Full omen score JSON

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

Repository	Language	Health Score	Key Insights
tiangolo/fastapi	Python	91/100 (A)	Top scorer: perfect cohesion, complexity, and coupling; duplication comes from versioned docs examples
gin-gonic/gin	Go	87/100 (B)	Clean, mature web framework; perfect coupling and smells, with cohesion the main headroom
discourse/discourse	Ruby	84/100 (B)	Largest codebase (14K+ files) yet strong debt, complexity, and defect management; coupling is the drag
excalidraw/excalidraw	TypeScript	77/100 (C)	Healthy complexity and low duplication; coupling and architectural smells pull the score down
BurntSushi/ripgrep	Rust	74/100 (C)	Excellent architecture and complexity; lower duplication/SATD scores reflect a mature, long-lived codebase

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.2), MEDIUM (0.2-0.5), HIGH (> 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.