Omen

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.

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:

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.

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:

omen stubs
# Fail CI if any stub is foundomen stubs --gate error
# Only fail on high-severity stubs (todo!()-style idioms), warn on the restomen stubs --gate error --gate-severity highomen 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 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.

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.

There are three types of clones:

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%.

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.

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):

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

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:

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.

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 mainomen diff --target main
# Compare against a specific commitomen diff --target abc123
# Output as markdown for PR commentsomen -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:

Risk Score Interpretation:

Example Output:

Branch Diff Risk Analysis==========================
Source:   feature/new-apiTarget:   mainBase:     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.

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

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.

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.

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

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.

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:

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.

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)

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.

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

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 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 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:

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.

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:

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 scoreomen score
# JSON output for CI integrationomen -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.

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:

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 operatorsomen mutation --mode thorough
# Fast mode (excludes operators that produce more equivalent mutants)omen mutation --mode fast
# Run with coverage data to skip untested codeomen mutation --coverage coverage.json
# Incremental mode for CI - only test changed filesomen mutation --incremental
# Control parallelismomen mutation --jobs 8
# Output surviving mutants for investigationomen mutation --output-survivors survivors.json
# Filter to specific filesomen 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 trainingomen mutation --record
# Train the model from accumulated historyomen mutation train
# Use trained model to skip high-confidence kills (saves time)omen mutation --skip-predicted 0.95
# Use a custom model pathomen 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 recordingomen mutation --record --mode thorough
# After accumulating history: train modelomen mutation train
# Daily CI: fast run using predictionsomen 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)

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.

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."