sensez

Coding agents produce tech debt. Bring them to their senses.

Coding agents forget the maintainability rules you give them. They hide logic in nested functions, reach for dict[str, Any] instead of a typed model, and pass around boolean flags whose meaning only exists in the agent’s current context.

Instructions help, but they’re soft constraints. Static analysis tools in your CI pipeline catch the problem too late and it starts rotting in a Jira ticket.

sensez adds fast, deterministic static feedback that agents can act on while they’re still working. It runs inside the coding-agent loop, giving agents fast, structured feedback on duplication, dead code, cycles, architecture violations, and design smells—so they fix problems before technical debt compounds.

In controlled evaluations, agents using Sensez produced 86% fewer code smells, 90% less duplicated code, and 67% fewer lines.

Website · Documentation · MCP and agent guide · Configuration reference

Quick start

Python

uv add --dev sensez      # or install globally: uv tool install sensez
uv run sensez init       # writes a starter config and registers the MCP server
uv run sensez noze .     # scan once — no install needed with: uvx sensez noze .

JavaScript and TypeScript

npm install --save-dev sensez
npx sensez init
npx sensez noze .

sensez init writes a commented starter sensez.toml and registers Sensez as an MCP server with your coding agent — Claude Code, Cursor, Cline, Codex, OpenCode, and Pi are supported. Restart the agent afterwards so the server is picked up. sensez . and sensez noze . both run the default scan.

A report is one screen, focused on what to fix first:

$ sensez noze .
sensez — structural maintainability report

Circular imports (1)
    [warning] ↻ shop.promo → shop.cart
        ./shop/promo.py:1  shop.promo → shop.cart
        ./shop/cart.py:1  shop.cart → shop.promo

Duplication (1)
    [advisory] structural clone (53):
      ./shop/clone_a.py:1-12
      ./shop/clone_b.py:1-12

Dead code candidates (2)
    [advisory] ./shop/legacy.py:1  shop.legacy::orphan_helper (function) [high]
    [advisory] ./shop/promo.py:10  shop.promo::recap (function) [high]

Code smells (0)

Boundary violations (not configured)

Why Sensez?

Coding agents are excellent at producing code—and, occasionally, at producing the same helper three times, gently ignoring architecture notes, and replacing type-safe models with dict[str, Any]. The vibes are immaculate; the result can still be a slopocalypse that takes hours to untangle.

Sensez closes that feedback loop while an edit is still fresh. It gives agents short, structured feedback on the repository's shape, so problems can be fixed before they become load-bearing.

The gap is especially visible in agent-driven work:

• Context rots. Architecture guidance fades across long, summarized turns.
• CI is too late. Small, non-blocking structural warnings are easy to defer.
• Slow checks do not fit the turn. If a check takes minutes, it cannot run in every feedback loop—and debt has time to accumulate.

[Agent proposes turn finish] ──> [Sensez MCP sniff] ──> [Finds cycle / clone / smell]
                                      │
                                      └──> Immediate, actionable feedback

Sensez complements—not replaces—Ruff, ty, mypy, ESLint, TypeScript, rustc, and Clippy. Use those tools for local correctness; use Sensez for the structural relationships across the codebase.

What it finds

Some examples of the included smells:

The default report is intentionally fixable in one screen: each pillar shows its top five offenders, each smell kind shows its total plus its top three examples, and dead-code output includes high-confidence findings only. Use --all for every finding, or --max N to set another cap.

# Focus a CI check on the pillars you care about
sensez noze . --duplicates
sensez noze . --duplicates --dead-code --json

Performance

Sensez evaluates all structural pillars in one pass.

Python: pylint benchmark

JavaScript / TypeScript: zod benchmark

Agent impact

The same coding agent completed 70 real-world Python tasks from SWE-PolyBench and SWE-bench Verified, plus 21 synthetic tasks designed to trigger specific maintainability traps. Both variants received SOLID/DRY principles. The Sensez variant additionally had to call noze_sniff in a feedback loop before it could declare a task complete.

Sensez agents produced structurally cleaner code with 67% fewer lines. Benchmarks used SWE-PolyBench_500, SWE-bench Verified, and synthetic pillar tests. See the evaluation suite for the methodology and per-benchmark results.

MCP for agents

MCP is the recommended integration when Sensez should run repeatedly during a coding session rather than as a one-off shell command. sensez init registers the server with your coding agent, which then launches it automatically at startup — there is nothing to run by hand.

Sensez can also run standalone in GitHub Actions. See the GitHub Action guide.

Configuration

Sensez reads sensez.toml from the project root, or [tool.sensez] from pyproject.toml when sensez.toml is absent.

sensez init

The main configuration areas are:

• [duplication] for clone thresholds
• [dead_code] for dynamic entry points
• [cycles] for cycle-only path excludes
• [smells] for smell toggles and thresholds
• [[boundaries.forbidden]] for architecture contracts
• [action] for how strongly agents and gates treat each pillar
• [accept] for shared accepted findings
• [self_improvement] for local metrics
• [cache] enables MCP/LSP process-memory reuse; CLI scans always stay stateless

[duplication]
threshold = 50

[dead_code]
entrypoint_names = ["register", "main", "setup"]

[smells.rules.long_function]
max_lines = 80
action = "warning"

# The beta performance heuristics are disabled by default.
[smells.rules.nested_loop]
enabled = true

[smells.rules.n_plus_one_call]
enabled = true

Smell rules can also be overridden per language, and every finding carries an action level (info → must_fix) that drives gates and CI. See the Configuration reference for action levels, per-language overrides, boundary patterns, and accepting findings.

Local-only metrics and privacy

brainz records scans, gate blocks, triage decisions, resolved findings, regressions, detector precision, and usage reports locally.

sensez brainz report .
sensez brainz report . --json

Everything remains under .sensez/local-metrics/. Sensez sends no telemetry and uploads no source code. Disable local metrics for a repository with:

[self_improvement]
enabled = false

Project anatomy

• spine: file discovery, parsing, shared IR, and dependency graph.
• profiles: language adapters for Python, JS/TS, TSX, and Rust.
• noze: duplication, dead code, cycles, and design smells.
• bonez: architecture-boundary auditing.
• brainz: local-only metrics and feedback memory.
• eyez: optional doc/comment search; not yet enabled.
• mcp: JSON-RPC/MCP surface for agent integration.
• reporter: terminal and JSON output.
• setup: starter configuration, MCP registration, and hook setup.

Disclaimer

Please review DISCLAIMER.md for the project disclaimer.