sensez

PyPI npm CI Website Documentation License: MIT

Bring your coding agent to its senses.

Coding agents drift. CI catches the result too late, and non-blocking reports become Jira tickets nobody picks up.

sensez 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 quality issues, 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

Area Output key What it catches
Duplication duplication Structural clones, including local-rename copies.
Dead code dead_code Unreferenced symbols with confidence tiers.
Cycles cycles Import loops and load-order tangles.
Boundaries boundaries Imports that cross configured architecture rules.
Smells smells Design pressure inside functions, classes, modules, and the graph.

Some examples of the included smells:

Smell Why Sensez flags it
tuple_packing Positional tuples hide meaning; tuple[int, str, int] is not a data model.
loose_typing Any, schema-erasing maps, and primitive containers erase caller contracts.
boolean_blindness do_thing(True, False) makes argument meaning a guessing game.
implicit_schema Repeated string-key access often means a real shape is hiding in a dict.
mutated_parameter A function returns a parameter after chewing it up.
feature_envy A method that mostly uses another object's data may belong elsewhere.
message_chain Long a.b.c.d chains couple callers to deep object plumbing.
god_module One module has become the place everything depends on.
magic_string_default || "" or or "" hides a string that should be required.
split_variable Multiple reassignments of a variable in one scope add hidden state.
nested_loop Beta, opt-in: nested iteration may have unintended complexity.
nested_ternary Nested conditional expressions make agent-generated decisions hard to follow.
n_plus_one_call Beta, opt-in: one-by-one external calls may need batching.

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

Python benchmark: Sensez 0.27 s, Vulture 1.29 s, Repowise 17.26 s, Symilar 234.12 s

Tool Time Scope
sensez 0.27 s All structural pillars in one pass
vulture 1.29 s Python dead code
repowise 17.26 s Repository intelligence, including dead code
symilar 234.12 s Line-based duplication

JavaScript / TypeScript: zod benchmark

JavaScript and TypeScript benchmark: Sensez 0.16 s, Fallow 0.48 s, Repowise 5.75 s

Tool Time Scope
sensez 0.16 s All structural pillars in one pass
fallow 0.48 s JS/TS structural dead-code and dependency findings
repowise 5.75 s Repository intelligence, including dead code

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.

New quality issues Clone tokens New clones Lines written Tokens used
Without Sensez 14 1,251 129 2,080 1.23M
With Sensez 2 126 0 682 1.34M
Reduction 86% 90% 100% 67% +8.7% overhead

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.

Tool Use
noze_sniff Scan the repository for smells and structural issues.
noze_gate Experimental end-of-turn diff gate; may be noisy for short or Q&A turns.
noze_explain Explain a finding category.
get_configuration_summary Summarize the effective configuration and noisiest rules when tuning.
brainz_report Summarize local usage and resolution metrics.
brainz_triage Record user-approved debt or false-positive verdicts.
eyez_search_docs Disabled unless eyez is enabled; searches docstrings and comments.

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
  • [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
[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.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for popov95s from gravatar.com popov95s

Requires

Python >=3.11

Tags

architecture dead-code duplication code-quality

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

sensez-0.2.5-py3-none-win_amd64.whl (2.9 MB view details)

Uploaded Python 3Windows x86-64

sensez-0.2.5-py3-none-manylinux_2_39_x86_64.whl (3.2 MB view details)

Uploaded Python 3manylinux: glibc 2.39+ x86-64

sensez-0.2.5-py3-none-manylinux_2_39_aarch64.whl (3.2 MB view details)

Uploaded Python 3manylinux: glibc 2.39+ ARM64

sensez-0.2.5-py3-none-macosx_11_0_arm64.whl (2.9 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

sensez-0.2.5-py3-none-macosx_10_12_x86_64.whl (3.1 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file sensez-0.2.5-py3-none-win_amd64.whl.

File metadata

  • Download URL: sensez-0.2.5-py3-none-win_amd64.whl
  • Upload date:
  • Size: 2.9 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for sensez-0.2.5-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 1e4432819448b15cc3f74069d244d35193c89f97b7fffba693322e331c11d25e
MD5 128064315c32c62eb6b4315294556762
BLAKE2b-256 7ee3de009f2371b1227ababc21985fa99c38e47c298409b00a27c8bc9fd4ed14

See more details on using hashes here.

Provenance

The following attestation bundles were made for sensez-0.2.5-py3-none-win_amd64.whl:

Publisher: release.yml on popov95s/sensez

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sensez-0.2.5-py3-none-manylinux_2_39_x86_64.whl.

File metadata

File hashes

Hashes for sensez-0.2.5-py3-none-manylinux_2_39_x86_64.whl
Algorithm Hash digest
SHA256 c0779c980925fc65019d2620debaae3eb1aa61e276c4d735451649e5ba76a664
MD5 cb75d00acb094d152f623dc44ae0fca2
BLAKE2b-256 087f0cb068e8fe6881a95d5d5a2dbb423161c7fde0adc53993eea64bb473a2a3

See more details on using hashes here.

Provenance

The following attestation bundles were made for sensez-0.2.5-py3-none-manylinux_2_39_x86_64.whl:

Publisher: release.yml on popov95s/sensez

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sensez-0.2.5-py3-none-manylinux_2_39_aarch64.whl.

File metadata

File hashes

Hashes for sensez-0.2.5-py3-none-manylinux_2_39_aarch64.whl
Algorithm Hash digest
SHA256 92139176a01ca757aefe2503b3ecc67af05e9537422606c2163f0b4f028bcb64
MD5 53e7269aaba5fb21442cc3be57943a26
BLAKE2b-256 dd9e354971442102809305a00ea6f4e003fbef4013a22326b48a4f3ff1836558

See more details on using hashes here.

Provenance

The following attestation bundles were made for sensez-0.2.5-py3-none-manylinux_2_39_aarch64.whl:

Publisher: release.yml on popov95s/sensez

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sensez-0.2.5-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for sensez-0.2.5-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 035a671aa971017c1aaf3cde4a5a21bb34eea515e645573fa3e800ab5006ce69
MD5 a528475713c462b02fba777c7d6e88d5
BLAKE2b-256 121b2550d815882359d81d9aa72988180c755258abdff8a08b82aa3bcf7a64c0

See more details on using hashes here.

Provenance

The following attestation bundles were made for sensez-0.2.5-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yml on popov95s/sensez

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file sensez-0.2.5-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for sensez-0.2.5-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 3fcc8ea30bbd2d84deb745c7513dede963784799dad6c7c34eab2d0e17e0b70d
MD5 7bdf0a37bfa9430fee69bc21471bf7ff
BLAKE2b-256 4e4b22951a1c44cee0ea255a73e21a078f0e96d7e6250827124826b65da03e7f

See more details on using hashes here.

Provenance

The following attestation bundles were made for sensez-0.2.5-py3-none-macosx_10_12_x86_64.whl:

Publisher: release.yml on popov95s/sensez

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.3.1

5 files

0.3.0

5 files

This release

0.2.5 This release

5 files

0.2.4

5 files

0.2.3

5 files

0.2.2

5 files

0.2.1

5 files

0.2.0

5 files

0.1.12

5 files

0.1.11

5 files

0.1.10

5 files

0.1.9

5 files

0.1.8

5 files

0.1.7

5 files

0.1.6

5 files

0.1.5

5 files

0.1.4

5 files

0.1.3

5 files

0.1.1

5 files

0.1.0

5 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page