Created by Mohammed Nasher · Open source (MIT) · Free for anyone to use
Lens is a self-contained code-quality and code-review engine for AI coding assistants. You point it at a diff, a file, or a complexity hotspot and it sharpens the craft: readability, naming, function and complexity size, code smells, and real duplication — so the next person, including future-you, can read it, change it safely, and trust it. It's the review you run on every diff, every day.
A lens brings what's blurry into focus without changing what's there. Lens does that for code. It doesn't re-architect, re-test, re-secure, or redeploy — it sharpens the daily craft and routes everything else to the skill that owns it.
Who built this? Lens is designed and authored by Mohammed Nasher (@mhd-nasher). Released open source under MIT — use it, fork it, ship with it. If it helps you, a ⭐ and a mention go a long way.
Most code-quality tooling fails in one of two ways: it churns working code (a 400-line "cleanup" diff that risks bugs to satisfy a style preference, or a premature DRY that couples things that should diverge), or it steps out of its lane (calling a security bug a "style issue", or re-architecting the system in a review comment). Lens refuses both:
- The Leave-It-Alone Law. Lens won't churn working code for cosmetic preference, and won't "DRY" code that changes for different reasons. A change must improve readability or maintainability for a concrete reader or a concrete future change — not satisfy a personal style or a metric. If the only justification is taste, leave it alone. A diff must earn its risk.
- It routes, it doesn't adjudicate. Lens owns code quality only. A security smell → Bastion
(with the
B-id). A structural/boundary smell → Cairn (with theR-id). A missing test → Anvil (with theT-id). A deploy concern → Relay. It raises quality findings (Q-###) and names the owner for the rest. It never raises a security or architecture finding itself. - Clean ≠ correct ≠ secure. Beautiful code can be wrong, untested, insecure, or unshippable. Lens improves readability and maintainability — it does not verify behavior (that's Anvil), prove safety (that's Bastion), fix structure (that's Cairn), or deploy (Relay). It says so, plainly, and never claims a cleanup made code safe.
- It's stack-aware. It detects your real technology — idiomatic TS/JS/React/Next and Dart/Flutter, with
ESLint/Prettier and
dart format/dart analyzeas the baseline — and lets the formatter own mechanical style so the review is about substance, not whitespace. Signal, not dogma. - It's an advisor, not an autopilot. Money/auth/access/crypto code is proposed and explained, never silently applied — a "cleaner" rewrite of a payout or a Security Rule can introduce a worse defect. The human approves every change, and a refactor is "done" only when Anvil's tests are still green.
- It's verifiable. Lens ships with evals that prove it activates correctly, raises the real quality problems, and does not churn working code or stray out of its lane.
| Failure mode | What it looks like | How Lens avoids it |
|---|---|---|
| The false alarm | A big cosmetic rewrite of working code; a premature DRY of look-alikes; a security/structure finding raised in the quality lane. | The Leave-It-Alone Law + route-don't-adjudicate (Q-051, Q-062). |
| The miss | Letting an unreadable name, a five-job function, deep nesting, a boolean trap, or genuine drifting duplication through. | The Q-### catalogue + the complexity report, each tied to a concrete reader/future-change. |
| Mode | For | What it does |
|---|---|---|
| Mode 0 — Guided Clean-up (Beginner) | "I don't know what makes code good." | Plain-language walkthrough with progress gauges, teaching the why behind each fix. |
| Mode A — Review a Diff / PR | Reviewing changes before merge. | Quality findings, kind/specific/prioritized; must-fix vs nit:; routes non-quality findings to the owner. |
| Mode B — Refactor for Readability | Improving an existing file/module. | Behavior-preserving cleanups, gated on an Anvil test safety net. |
| Mode C — Reduce Complexity Hotspots | The complexity report flags the worst offenders. | Tames real hotspots; respects justified complexity (Q-043) — never fake-simplifies. |
Every run starts at Step 0: detect the stack and lint/format baseline, read the complexity budget from Cairn (don't impose full-team rigor on a solo MVP), scope the review, and gauge the user's level.
- Version: 1.0.0
- Name:
lens - Author: Mohammed Nasher (@mhd-nasher)
- Tagline: the daily craft — code a human can read, change, and trust
- Modes: Guided (beginner) · Review a Diff/PR · Refactor for Readability · Reduce Complexity Hotspots
- Owns: code quality & review — readability, naming, complexity, code smells, real DRY
- Routes: correctness → Anvil · security → Bastion · structure → Cairn · deploy → Relay
- Stack-aware: idiomatic TS/JS/React/Next · Dart/Flutter · ESLint/Prettier &
dart format/dart analyze - Citable: every check maps to a stable
Q-###id - Category: Code quality, code review & refactoring
- Risk: Low (advisory — reviews and proposes; the human approves every change; refactors gated on green tests)
- License: MIT
lens/
├── SKILL.md # Entry point: identity, Honesty Contract, Step 0, modes, core checks, Leave-It-Alone Law
├── README.md # This file
├── FORGE_DNA.md # The shared suite contract + boundary table (read first)
├── LICENSE # MIT
├── CHANGELOG.md # Version history
├── CITATION.cff # Citation metadata
├── CONTRIBUTING.md # How to add profiles / guardrails / evals (skill-TDD)
├── reference/
│ ├── checks.md # ALL checks: Q-### + Means/Why/Applies-Leave-it-alone/Routes-to (the backbone)
│ ├── readability.md # Names, function size, nesting, comments, idiom
│ ├── code-smells.md # Each smell with the fix AND the false-alarm note
│ ├── complexity.md # Cyclomatic + cognitive + justified complexity
│ ├── dry-and-coupling.md # Real vs accidental duplication; don't-DRY-what-diverges
│ ├── stack-style-profiles.md # Idiomatic TS/JS/React/Next + Dart/Flutter baselines (load in Step 0)
│ ├── review-etiquette.md # Kind, specific, prioritized; must-fix vs nit
│ └── glossary.md # Quality vocabulary, defined plainly
├── workflows/
│ ├── guided-cleanup-for-beginners.md # Mode 0 — plain-language, progress gauges
│ ├── review-a-pr.md # Mode A — review a diff/PR + route the rest
│ ├── refactor-for-readability.md # Mode B — behavior-preserving, test-gated
│ └── reduce-complexity.md # Mode C — tame hotspots, respect justified complexity
├── checklists/
│ ├── code-review-quality.md # The quality lane (separate from Cairn's structural + Bastion's security review)
│ └── pre-merge-quality-gate.md # Must-fixes block, nits don't
├── templates/
│ └── review-comment-template.md # A kind, specific, prioritized, routed review comment
├── examples/
│ ├── messy-then-clean-ts-function.md # Before/after TS with Q-### tags
│ └── dart-widget-readability-fix.md # Before/after Flutter widget
├── scripts/
│ └── complexity_report.py # Cyclomatic complexity per function (JS/TS/Dart-like); flags hotspots; self-tested
└── evals/
├── trigger-eval.json # Activation tests (should / shouldn't trigger, incl. sibling boundary cases)
├── evals.json # Behavior: quality problems it MUST raise + churn/out-of-lane cases it must NOT
└── README.md # Skill-TDD (RED · GREEN · REFACTOR) for quality evals
Personal skill (recommended):
# Claude Code
cp -R lens ~/.claude/skills/Then start a new session. Lens auto-activates when you discuss reviewing a PR, cleaning up code, readability, naming, complexity, code smells, or duplication.
Project skill:
mkdir -p .claude/skills && cp -R lens .claude/skills/Beginner — "I don't know what's wrong with my code":
"I wrote this function and it works, but it feels messy. Can you clean it up and tell me why?"
Lens runs Step 0 (detects the stack + lint baseline), then Mode 0: a plain-language walkthrough with progress gauges, explaining each fix in human terms and only changing what earns its risk.
Review a PR / diff:
"Review this PR before I merge — what's a must-fix vs a nit?"
Lens runs Mode A: raises quality findings (with Q-### ids), separates must-fix from nit:, and routes
anything outside its lane — a security smell to Bastion, a boundary problem to Cairn, a missing test to Anvil.
Refactor for readability:
"This function is too complex — refactor it for clarity without changing behavior."
Lens checks there are Anvil tests covering the behavior (asks Anvil to add them if not), then proposes a behavior-preserving refactor — respecting justified complexity and never fake-simplifying.
# Activation + behavior tests live in evals/. See evals/README.md for the skill-TDD workflow.
python3 -c "import json; json.load(open('lens/evals/trigger-eval.json')); json.load(open('lens/evals/evals.json')); print('evals OK')"
# The complexity scorer is self-tested (proves it scores known cases correctly and flags hotspots):
python3 lens/scripts/complexity_report.py --self-test
# Run the complexity report over a real tree (flags hotspots; quiet on generated code):
python3 lens/scripts/complexity_report.py <path>Lens produces a code-quality assessment — readability, naming, complexity, smells, and real-DRY findings, each tied to a concrete reader or a concrete future change. It does not, by itself, make code correct, tested, secure, structurally sound, or shippable. Clean is not the same as correct or secure. Lens is stack-aware (a style rule that doesn't fit your stack is suppressed, and the formatter owns mechanical style), it honors the Leave-It-Alone Law (no churn for taste, no DRY of look-alikes that diverge), and it routes every non-quality finding to its owner — security to Bastion, structure to Cairn, tests to Anvil, deploy to Relay. Every change to money, auth, access, or crypto code is proposed and explained, never silently applied — the human approves, and a refactor is "done" only when Anvil's tests are still green.
Lens is one of eight composable skills in the Forge suite, each the world's best at one job, all sharing
one philosophy and one boundary contract so they reinforce instead of collide. The full contract — the
shared genome, the stack family, the five laws, and the ownership table — is in FORGE_DNA.md.
| Skill | Owns | Lens's relationship |
|---|---|---|
| Helm | The product loop | Quality smells Helm meets mid-reading park to Lens by name + Q- id; Lens never renders outcome verdicts. |
| Loom | Feature definition & completeness | Loom parks quality smells it meets mid-weave to Lens by name + Q- id; Lens never re-decides the feature's scope. |
| Facet | The interface | Lens owns the code's readability; Facet owns the interface's coherence — broken spacing is a Facet finding, a 400-line build method is Lens's. |
| Cairn | Architecture & structure | Lens flags structural symptoms (God object, divergent change) and defers the boundary call to Cairn. |
| Anvil | Testing | Lens gates every refactor on Anvil's green tests; routes missing-test findings to Anvil. |
| Lens (this) | Code quality & review | Readability, naming, complexity, smells, real DRY — the daily craft. |
| Bastion | Security & resilience | Lens routes any security smell to Bastion by name + B- id; it never raises a security finding itself. |
| Relay | Ship & operate | Relay's pipeline runs Lens as a quality gate stage — must-fixes block, nits don't. |
The natural flow: Helm sets the course → Loom defines → Facet gives it a face → Cairn designs → Anvil tests → Lens cleans → Bastion guards → Relay ships → Helm reads the results. Each also stands alone, and you can enter at any skill. Lens never re-decides another skill's concern — it sharpens the craft and routes the rest.
Lens is open source and contributions are welcome. Open an issue or a pull request on the
GitHub repo. Good contributions: new stack-style profiles, sharper
Leave-It-Alone guardrails, more evals (especially must_not route / over-DRY / churn cases), and new worked
examples. See CONTRIBUTING.md and evals/README.md for the skill-TDD workflow that keeps Lens trustworthy.
Lens is created and maintained by Mohammed Nasher.
- 👤 Author: Mohammed Nasher
- 🐙 GitHub: @mhd-nasher
- 📦 Repository: github.com/mhd-nasher/lens
- 🧬 Suite: part of Forge — see
FORGE_DNA.md; siblings Cairn, Anvil, Bastion, Relay. - 💬 Contact / questions / collaboration: open an issue or start a discussion on the repo.
If you use Lens in a project, a credit back to @mhd-nasher is appreciated.
See CITATION.cff for citation details.
MIT © Mohammed Nasher (@mhd-nasher). Free to use, modify, and distribute — keep the copyright and license notice.
Built with intent by Mohammed Nasher 🔍
Lens sharpens the craft and routes the rest. If Lens helped you ship something cleaner, drop a ⭐.