Sensez

PyPI npm CI Website Documentation License: MIT

Structural maintainability checks for coding agents and teams.

Sensez is a suite of Rust CLIs and an MCP server that runs alongside your linter and type-checker. It finds cross-file problems that those tools do not usually own: duplication, dead code, import cycles, architecture-boundary violations, and design smells.

It gives coding agents the noze to detect code smells, the bonez to respect architectural boundaries, and the spine to do it fast. Python, JavaScript, TypeScript/TSX, and Rust profiles are supported (Rust primarily for dogfooding).

Website · Documentation · MCP and agent guide · Configuration reference · Report a security issue

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.

Quick start

Python

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

# Or install a global CLI
uv tool install sensez
sensez init

# Or run a one-off scan
uvx sensez noze .

JavaScript and TypeScript

# Add as a development dependency
npm install --save-dev sensez

# Generate a starter config and scan
npx sensez init .
npx sensez noze .

sensez . and sensez noze . both run the default scan. The explicit form sensez noze sniff . remains available for agent-oriented workflows.

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.
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. The init command would set this up automatically on agent start.

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

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; 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: 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.2-py3-none-win_amd64.whl (2.9 MB view details)

Uploaded Python 3Windows x86-64

sensez-0.2.2-py3-none-manylinux_2_39_x86_64.whl (3.3 MB view details)

Uploaded Python 3manylinux: glibc 2.39+ x86-64

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

Uploaded Python 3manylinux: glibc 2.39+ ARM64

sensez-0.2.2-py3-none-macosx_11_0_arm64.whl (3.0 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

sensez-0.2.2-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.2-py3-none-win_amd64.whl.

File metadata

  • Download URL: sensez-0.2.2-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/6.1.0 CPython/3.13.12

File hashes

Hashes for sensez-0.2.2-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 1d036318d7507e709bf8d0dcf99e7b76176183465ae9d97f046c882dc453a099
MD5 a89bb17dd5feb5d65b7e5b837f7bd35f
BLAKE2b-256 6797cfa33a1b6f2a71640d18211d1f0a21afa8e412ded3b24805522116db854d

See more details on using hashes here.

Provenance

The following attestation bundles were made for sensez-0.2.2-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.2-py3-none-manylinux_2_39_x86_64.whl.

File metadata

File hashes

Hashes for sensez-0.2.2-py3-none-manylinux_2_39_x86_64.whl
Algorithm Hash digest
SHA256 9a53dec549c547110f193d328166c8c4cdf3db6d52e632aeaa4001d568414780
MD5 3c2ad84fa43016272135221603e32b44
BLAKE2b-256 3b6cb8d66b06ca672439ea65faaf79e1984882b8eddb4562f46a5ea7941ea6c5

See more details on using hashes here.

Provenance

The following attestation bundles were made for sensez-0.2.2-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.2-py3-none-manylinux_2_39_aarch64.whl.

File metadata

File hashes

Hashes for sensez-0.2.2-py3-none-manylinux_2_39_aarch64.whl
Algorithm Hash digest
SHA256 062ab1d95cb707231b956e25f66cea3ae098df0a1632121f46244bda97cf1b50
MD5 b709849fd8a8211928dc2906e2914c19
BLAKE2b-256 2c674a252b1978d9d807a3c9d0d09a1a8ebecd6868c005cc92adcfb087634f68

See more details on using hashes here.

Provenance

The following attestation bundles were made for sensez-0.2.2-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.2-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for sensez-0.2.2-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c43414a372747f37ddc8c52e8d5a4c6c60702d35967fd1c61cf56a92129c10fd
MD5 084511895b50cf5e0716eec7fe08379e
BLAKE2b-256 ffe00a7189bb49ffd2f153c32d08715fb2e674b30ec53cc0f1ae641ae3081a3c

See more details on using hashes here.

Provenance

The following attestation bundles were made for sensez-0.2.2-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.2-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for sensez-0.2.2-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 7a60819e5fa03ce28631e1ed8b2053351fbe8c22dd16a6a503347e72cffa80f5
MD5 eb0d9b1c48cf60eb373485f79045c2f6
BLAKE2b-256 31acb580fa974a757019b8265134fa6751dc3403b9114127ab89a9776e5af5cf

See more details on using hashes here.

Provenance

The following attestation bundles were made for sensez-0.2.2-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

0.2.5

5 files

0.2.4

5 files

0.2.3

5 files

This release

0.2.2 This release

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