omen

Name: omen
Author: panbanda

bypanbanda· 1 MCP server

Stars

Forks

How to install omen?

panbanda/omen

$git clone https://github.com/panbanda/omen

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Install & use

Install omen by running `git clone https://github.com/panbanda/omen`, then use it for the current task and follow its documentation at https://github.com/panbanda/omen.

Files · 1

View on GitHub

README.md

1	<div align="center">
2
3	# Omen
4
5	<img src="assets/omen-logo.jpg" alt="Omen - Code Analysis CLI" width="100%">
6
7	[![Rust Version](https://img.shields.io/badge/rust-1.92%2B-orange)](https://www.rust-lang.org/)
8	[![License](https://img.shields.io/github/license/panbanda/omen)](https://github.com/panbanda/omen/blob/main/LICENSE)
9	[![CI](https://github.com/panbanda/omen/actions/workflows/ci.yml/badge.svg)](https://github.com/panbanda/omen/actions/workflows/ci.yml)
10	[![Release](https://img.shields.io/github/v/release/panbanda/omen)](https://github.com/panbanda/omen/releases)
11	[![Crates.io](https://img.shields.io/crates/v/omen-cli)](https://crates.io/crates/omen-cli)
12
13	Your AI writes code without knowing where the landmines are.
14
15	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.
16
17	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.
18
19	</div>
20
21	---
22
23	## Features
24
25	<details>
26	<summary><strong>Complexity Analysis</strong> - How hard your code is to understand and test</summary>
27
28	There are two types of complexity:
29
30	- 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.
31
32	- 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.
33
34	Why it matters: Research shows that complex code has more bugs and takes longer to fix. [McCabe's original 1976 paper](https://ieeexplore.ieee.org/document/1702388) found that functions with complexity over 10 are significantly harder to maintain. [SonarSource's cognitive complexity](https://www.sonarsource.com/docs/CognitiveComplexity.pdf) builds on this by measuring what actually confuses developers.
35
36	> [!TIP]
37	> Keep cyclomatic complexity under 10 and cognitive complexity under 15 per function.
38
39	</details>
40
41	<details>
42	<summary><strong>Self-Admitted Technical Debt (SATD)</strong> - Comments where developers admit they took shortcuts</summary>
43
44	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:
45
46	\| Category \| Markers \| What it means \|
47	\| ----------- \| ----------------------- \| ---------------------------------------------- \|
48	\| Design \| HACK, KLUDGE, SMELL \| Architecture shortcuts that need rethinking \|
49	\| Defect \| BUG, FIXME, BROKEN \| Known bugs that haven't been fixed \|
50	\| Requirement \| TODO, FEAT \| Missing features or incomplete implementations \|
51	\| Test \| FAILING, SKIP, DISABLED \| Tests that are broken or turned off \|
52	\| Performance \| SLOW, OPTIMIZE, PERF \| Code that works but needs to be faster \|
53	\| Security \| SECURITY, VULN, UNSAFE \| Known security issues \|
54
55	Why it matters: [Potdar and Shihab's 2014 study](https://ieeexplore.ieee.org/document/6976075) 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)](https://ieeexplore.ieee.org/document/7332619) showed that design debt is the most common and most dangerous type.
56
57	> [!TIP]
58	> Review SATD weekly. If a TODO is older than 6 months, either fix it or delete it.
59
60	</details>
61
62	<details>
63	<summary><strong>Dead Code Detection</strong> - Code that exists but never runs</summary>
64
65	Dead code includes:
66
67	- Functions that are never called
68	- Variables that are assigned but never used
69	- Classes that are never instantiated
70	- Code after a `return` statement that can never execute
71
72	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)](https://ieeexplore.ieee.org/document/8370748) found that dead code is a strong predictor of other code quality problems.
73
74	> [!TIP]
75	> Delete dead code. Version control means you can always get it back if needed.
76
77	</details>
78
79	<details>
80	<summary><strong>Git Churn Ana

6 picks

Type

omen

bypanbanda· 1 MCP server

Stars

Forks

How to install omen?

panbanda/omen

$git clone https://github.com/panbanda/omen

Installs into the current project.

›Prefer a prompt? Paste this to your agent

Install & use

Install omen by running `git clone https://github.com/panbanda/omen`, then use it for the current task and follow its documentation at https://github.com/panbanda/omen.

Files · 1

View on GitHub

README.md

1	<div align="center">
2
3	# Omen
4
5	<img src="assets/omen-logo.jpg" alt="Omen - Code Analysis CLI" width="100%">
6
7	[![Rust Version](https://img.shields.io/badge/rust-1.92%2B-orange)](https://www.rust-lang.org/)
8	[![License](https://img.shields.io/github/license/panbanda/omen)](https://github.com/panbanda/omen/blob/main/LICENSE)
9	[![CI](https://github.com/panbanda/omen/actions/workflows/ci.yml/badge.svg)](https://github.com/panbanda/omen/actions/workflows/ci.yml)
10	[![Release](https://img.shields.io/github/v/release/panbanda/omen)](https://github.com/panbanda/omen/releases)
11	[![Crates.io](https://img.shields.io/crates/v/omen-cli)](https://crates.io/crates/omen-cli)
12
13	Your AI writes code without knowing where the landmines are.
14
15	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.
16
17	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.
18
19	</div>
20
21	---
22
23	## Features
24
25	<details>
26	<summary><strong>Complexity Analysis</strong> - How hard your code is to understand and test</summary>
27
28	There are two types of complexity:
29
30	- 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.
31
32	- 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.
33
34	Why it matters: Research shows that complex code has more bugs and takes longer to fix. [McCabe's original 1976 paper](https://ieeexplore.ieee.org/document/1702388) found that functions with complexity over 10 are significantly harder to maintain. [SonarSource's cognitive complexity](https://www.sonarsource.com/docs/CognitiveComplexity.pdf) builds on this by measuring what actually confuses developers.
35
36	> [!TIP]
37	> Keep cyclomatic complexity under 10 and cognitive complexity under 15 per function.
38
39	</details>
40
41	<details>
42	<summary><strong>Self-Admitted Technical Debt (SATD)</strong> - Comments where developers admit they took shortcuts</summary>
43
44	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:
45
46	\| Category \| Markers \| What it means \|
47	\| ----------- \| ----------------------- \| ---------------------------------------------- \|
48	\| Design \| HACK, KLUDGE, SMELL \| Architecture shortcuts that need rethinking \|
49	\| Defect \| BUG, FIXME, BROKEN \| Known bugs that haven't been fixed \|
50	\| Requirement \| TODO, FEAT \| Missing features or incomplete implementations \|
51	\| Test \| FAILING, SKIP, DISABLED \| Tests that are broken or turned off \|
52	\| Performance \| SLOW, OPTIMIZE, PERF \| Code that works but needs to be faster \|
53	\| Security \| SECURITY, VULN, UNSAFE \| Known security issues \|
54
55	Why it matters: [Potdar and Shihab's 2014 study](https://ieeexplore.ieee.org/document/6976075) 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)](https://ieeexplore.ieee.org/document/7332619) showed that design debt is the most common and most dangerous type.
56
57	> [!TIP]
58	> Review SATD weekly. If a TODO is older than 6 months, either fix it or delete it.
59
60	</details>
61
62	<details>
63	<summary><strong>Dead Code Detection</strong> - Code that exists but never runs</summary>
64
65	Dead code includes:
66
67	- Functions that are never called
68	- Variables that are assigned but never used
69	- Classes that are never instantiated
70	- Code after a `return` statement that can never execute
71
72	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)](https://ieeexplore.ieee.org/document/8370748) found that dead code is a strong predictor of other code quality problems.
73
74	> [!TIP]
75	> Delete dead code. Version control means you can always get it back if needed.
76
77	</details>
78
79	<details>
80	<summary><strong>Git Churn Ana

6 picks

Type

omen

How to install omen?

Related

omen

How to install omen?

Related