sensez 0.2.1

Why can't coding agents detect code smells? Because they don't have a noze.

Coding agents are very good at producing code. They are also very good at producing the same helper three times, gently ignoring your architecture notes, and using dict[str, Any] when you ask for type safety. You ask it to complete a task like "a staff software engineer", you ask it to follow SOLID principles and use strong type safety. It happily agrees, and starts working on the task. The vibes are immaculate. You come back a few minutes later to a slopocalypse that looks nothing like what your AGENTS.md says and you spend hours trying to understand where to start.

Sensez is a suite of Rust CLIs with an MCP server for maintenance before tech debt accumulates. It runs beside your linter and type-checker and looks for cross-file problems they usually do not own: duplication, dead code, import cycles, boundary violations, and design smells. It is designed to give your coding agent the noze to detect code smells, the bonez to respect architectural boundaries, and the spine to do it fast.

Supported language profiles currently include Python, JavaScript, TypeScript, and Rust (for dogfooding primarily).

Docs: https://popov95s.github.io/sensez/latest/

Quick Start

Python

# Add as a project dev dependency; run it with `uv run sensez ...`
uv add --dev sensez
uv run sensez init

# Install as a global CLI so `sensez ...` works directly
uv tool install sensez
sensez init

# or run a one-off scan with uv
uvx sensez noze .

JS/TS

# Add as a dev dependency
npm install --save-dev sensez
# Generate a sensez.toml starter config
npx sensez init . 

# Run a one-off scan with npx
npx sensez noze .

sensez . and sensez noze . both run the default scan. The verbose form is still available as sensez noze sniff ..

Performance Snapshot

xychart-beta
  title "pylint benchmark seconds"
  x-axis ["sensez", "vulture", "repowise", "symilar"]
  y-axis "seconds" 0 --> 20
  bar [0.27, 1.29, 17.26, 20]

sensez scans all structural pillars in one pass (0.27s). vulture checks Python dead code (1.29s). repowise uses a custom ranking mechanism, including dead code (17.26s). symilar checks line-based duplication (234.12s; chart capped at 20s).

JS/TS

xychart-beta
  title "zod benchmark seconds"
  x-axis ["sensez", "fallow", "repowise"]
  y-axis "seconds" 0 --> 6
  bar [0.16, 0.48, 5.75]

sensez scans all structural pillars in one pass (0.16s). fallow checks JS/TS structural dead-code and dependency findings (0.48s). repowise checks repo intelligence signals, including dead code (5.75s).

sensez tries to lower dead code noise and allows for configuration of what gets reported. It also includes a few more Python and TS/JS opinionated smells, apart from overall structural consistency metrics.

Agent Impact

We gave the same coding agent 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 used the noze_sniff MCP tool in a mandatory feedback loop before declaring each task complete.

Sensez agents produced structurally cleaner code with 67% fewer lines.

Benchmarks used: SWE-PolyBench_500, SWE-bench Verified, and synthetic pillar tests. Full methodology and per-benchmark results in evals/.

The Problem

Coding agents drift. Not due to bad intentions, but because their loop is leaky.

1. Context rots. You told the agent to respect boundaries, follow SOLID, and think like a staff engineer. Six turns later, the context has been summarized twice and the agent is confidently rewriting the same csv file parser your colleague wrote two weeks ago.

2. CI is too late. CI is great at saying "absolutely not." It is much worse at saying "hm, this duplication is small but suspicious." Non-blocking warnings have a natural habitat: ignored forever.

3. Slow checks do not fit the turn. If a check takes minutes, it should not run every agent turn. If it does not run every turn, the slop has time to ferment.

[Agent Proposes Turn Finish] ──> [ 👃 Sensez MCP Sniff ] ──> [ Catches Import Cycle / Duplication ]
                                   │
                                   └──> (Immediate Agent Feedback: "Loose typing violation on line 40 of code.py. Replace loose collections with dataclass/model.")

Sensez provides short, structured feedback directly to the agent while the edit is still fresh. Less archaeology, more "fix it before it becomes load-bearing."

noze

noze takes care of the gorgonzola coding agents love so much:

Some smell examples:

noze is not a formatter, linter, or type-checker. Keep using Ruff, ty, mypy, ESLint, TypeScript, rustc, and Clippy. noze sits next to them and watches the repo-level shape.

The default report is intentionally fixable in one screen: each pillar shows only its top 5 offenders, each smell kind shows its own total plus top 3 examples, and dead-code output includes high-confidence findings only. Use --all to print every finding, or --max N to choose a different cap.

For CI, filter to the pillars you care about:

sensez noze . --duplicates
sensez noze . --duplicates --dead-code --json

MCP

MCP is the default integration path for agents. Use it when Sensez should run repeatedly during a coding session instead of shelling out for one-off scans.

sensez mcp serve

The MCP tools are themed but explicit:

You can also use the sensez noze CLI standalone in GitHub Actions.

brainz

brainz is local-only memory. It records scans, gate blocks, triage decisions, resolved findings, regressions, detector precision, and usage reports.

sensez brainz report .
sensez brainz report . --json

Everything stays under:

.sensez/local-metrics/

No telemetry. No source upload. Disable it per repo:

[self_improvement]
enabled = false

Configuration

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

sensez init . --yes

Main knobs:

• [duplication] for clone thresholds
• [dead_code] for dynamic entrypoints
• [smells] for smell toggles and thresholds
• [[boundaries.forbidden]] for architecture contracts
• [action] for how strongly agents/gates treat each pillar
• [accept] for shared accepted findings
• [self_improvement] for local metrics

Small example:

[duplication]
threshold = 50

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

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

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. Not yet enabled.
• 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: sensez init, starter config, MCP registration, and hook setup.

Privacy

Sensez does not send telemetry or source code anywhere. Local metrics stay under .sensez/local-metrics/.

Disclaimer: DISCLAIMER.md