Sentrux: The Architecture Sensor for AI-Generated Code

The experience follows a recognizable pattern. Day one of using an AI coding agent is genuinely impressive. The agent writes clean code, understands the intent of the task, ships features quickly, and seems to have a coherent understanding of the project. Features that would have taken hours arrive in minutes.

Then something changes. Around session three or four, the agent starts hallucinating functions that do not exist. It puts new code in locations that make no structural sense. It introduces bugs in files it wrote correctly two sessions ago. A request for a simple feature breaks three other things. The debugging time starts to exceed the code generation time.

The intuition most developers reach for is that the AI got worse somehow. It did not. The codebase did.

This is the structural problem that underlies AI-assisted development at scale, and it is almost never discussed explicitly. When developers used an IDE, they maintained constant spatial awareness of their codebase. The file tree was always visible. Opening a file meant seeing where it sat in the directory hierarchy and understanding its relationship to adjacent files. Every edit passed through a human mental model of the architecture: which module does what, how the components connect, where new code belongs, what the dependency relationships look like.

AI agents operating through a terminal interface break that spatial awareness. The agent modifies dozens of files per session. The developer sees a stream of modification messages scrolling past. The file tree is not visible. The dependency graph is not visible. The architectural relationships that make a codebase navigable are not visible. Many developers allow AI agents to build entire applications without ever opening a file browser.

What accumulates silently across sessions is architectural decay. The same function names appear with different purposes scattered across files. Unrelated code accumulates in the same folders because the agent placed it there without understanding the organizational intent. Dependencies tangle. Circular references appear. When the agent searches the project in a subsequent session, it finds twenty conflicting matches and selects the wrong one. Each session makes the architectural mess worse. Each increment of mess makes the next session harder and less reliable.

The dirty secret of AI-assisted development is this: the better the AI generates code, the faster a codebase without architectural monitoring becomes ungovernable.

Why Planning Alone Does Not Solve the Problem

The conventional response to this problem is to plan more carefully. Generate detailed architectural specifications before writing any code. Define the module structure, the dependency relationships, the naming conventions, and the boundaries before the agent touches a file. Tools built on this philosophy, including specification generation systems, attempt to front-load architectural decision-making to prevent drift during implementation.

The problem with this approach is that it has no feedback loop. A specification describes the intended architecture. The agent writes code. Nobody checks whether the code that was produced matches the specification in any structural sense. The spec goes in, the implementation comes out, and the gap between them is invisible.

More fundamentally, this approach misunderstands how productive work with AI agents actually happens. Developers prototype rapidly. They iterate through conversation. They follow unexpected directions when the agent produces something interesting. The creative, exploratory, iterative workflow is exactly what makes AI coding agents valuable for discovery and experimentation. Forcing that workflow into a rigid waterfall of specification followed by implementation loses the primary benefit.

What is needed is not a better plan. What is needed is a sensor that observes the actual structure of the code being produced in real time and provides immediate feedback when that structure degrades.

What Sentrux Is and How It Closes the Loop

Sentrux is an open-source code architecture sensor built in Rust that closes the feedback loop between AI-generated code and structural quality. It reached 2,300 GitHub stars within two months of release, which reflects how widely the problem it addresses is recognized among developers using AI coding tools.

The conceptual model behind Sentrux draws on a principle from control systems engineering. Every system that functions reliably at scale has three components: a sensor that observes the current state of the system, a spec that defines what the desired state looks like, and an actuator that corrects deviation from the spec. Compilers close a feedback loop on syntax. Test suites close a loop on behavior. Linters close a loop on style.

Architecture, the structural dimension of whether code is organized in a way that will remain maintainable and comprehensible as it grows, has historically had no sensor and no actuator. Only humans could evaluate architectural quality, and humans cannot keep pace with the rate at which AI agents generate code.

Sentrux provides the sensor for architecture. It scans the entire codebase, computes five root-cause structural metrics, produces a continuous quality score from 0 to 10,000, visualizes the dependency graph as a live interactive treemap, and exposes all of this to AI agents through an MCP server so that agents can read their own structural impact mid-session and self-correct before degradation compounds.

The developer provides the spec through the rules engine, encoding architectural constraints as a configuration file that defines what the structure must satisfy. The AI agent is the actuator, correcting its own output when the sensor reports that the score has degraded or a constraint has been violated.

The loop closes.

The Five Root Cause Metrics

Sentrux computes five architectural metrics that together explain the structural health of a codebase comprehensively enough to diagnose the root cause of degradation rather than just reporting that something is wrong.

Modularity measures how effectively the codebase is organized into cohesive, well-bounded modules. A codebase with high modularity has components that do one thing well, depend on few other components, and expose clean interfaces. Low modularity means code is scattered across files in ways that make it impossible to understand any component in isolation.

Acyclicity measures whether the dependency graph contains cycles. Circular dependencies are the most structurally damaging pattern an AI agent can introduce, because they make it impossible to understand any component without understanding all the components it depends on. A codebase with zero cycles can be reasoned about bottom-up. A codebase with many cycles cannot be reasoned about systematically at all.

Depth measures the nesting and hierarchy depth of the structural organization. Excessive depth means that understanding any given piece of code requires holding many layers of context simultaneously, which degrades both human comprehension and AI agent reasoning.

Equality measures how evenly complexity and responsibility are distributed across the codebase. Low equality means some files have become god objects or god modules, concentrating so much logic that they become the single point of coupling for everything else in the system.

Redundancy measures duplication of logic, naming conflicts, and repeated patterns that the agent and future readers will struggle to disambiguate. High redundancy is precisely the condition that causes agents to find twenty conflicting matches and select the wrong one.

The Live Treemap: Making Structural Rot Impossible to Ignore

The visual interface of Sentrux presents the codebase as a live interactive treemap where the size of each cell reflects the relative weight of the corresponding file or module and the color reflects its structural health contribution. Dependency edges are drawn over the treemap, making circular dependencies and high-coupling relationships immediately visible as crossing lines.

When the AI agent modifies a file, that file glows in the treemap. The developer can see exactly which parts of the codebase the agent is touching, how those files relate to the broader structure, and whether the modifications are creating new dependency edges that should not exist.

This visual feedback restores something close to the spatial awareness that developers had when working with a file tree in an IDE, but at a higher level of abstraction. Instead of seeing which files exist, the developer sees how the files relate to each other structurally and whether those relationships are healthy.

The Quality Gate: Catching Degradation Before It Compounds

The quality gate workflow provides a simple, CI-compatible mechanism for detecting whether an AI coding session degraded the architecture compared to its starting state.

Before beginning an agent session, saving a baseline:

sentrux gate --save .

After the session completes, comparing against the baseline:

sentrux gate .

If the architecture score degraded during the session, the gate fails with a non-zero exit code. If the score held or improved, the gate passes. The comparison output shows the score before and after, which bottleneck metric drove any degradation, and whether the change falls within acceptable thresholds.

In CI environments, the gate integrates naturally into pipeline checks:

sentrux check .

This exits with code 0 if all configured rules pass and code 1 if any rule is violated, which makes it directly usable as a pipeline step that blocks deployment of architecturally degraded code.

The MCP Server: Giving Agents Real-Time Structural Awareness

The most architecturally significant capability in Sentrux for developers using AI coding agents is the MCP server, which exposes the structural health information to agents in real time during active coding sessions.

Adding Sentrux to Claude Code:

/plugin marketplace add sentrux/sentrux
/plugin install sentrux

For Cursor, Windsurf, OpenCode, OpenClaw, and any other MCP-compatible client, the server configuration is added to the MCP config:

{
  "mcpServers": {
    "sentrux": {
      "command": "sentrux",
      "args": ["--mcp"]
    }
  }
}

With the MCP server active, the agent has access to nine structural tools during the session. The scan tool returns the current quality score and identifies the primary bottleneck metric. The session-start tool saves a baseline at the beginning of the session. The session-end tool compares the final state against the baseline and reports whether the session improved or degraded the architecture. The rescan tool allows the agent to check the structural impact of recent changes without ending the session. The check-rules tool verifies that the current state satisfies all configured architectural constraints. The evolution tool shows how the quality score has changed over time. The dsm tool generates a dependency structure matrix. The test-gaps tool identifies areas of the codebase with insufficient test coverage.

An agent equipped with these tools can observe the effect of its own code generation on the architecture, identify when it is creating problematic coupling or dependency cycles, and correct its approach mid-session rather than waiting for the developer to discover the degradation in a later review.

The workflow the MCP integration enables looks like this: the agent scans the project at the start of the session, receives the current quality signal and the primary bottleneck, saves a baseline, writes code across multiple files, periodically rescans to check whether the score is holding, and calls session-end to produce a final comparison report. If the score degrades beyond a threshold, the agent knows immediately which metric drove the degradation and can address it before moving on.

The Rules Engine: Encoding Architectural Constraints

The rules engine allows architectural constraints to be defined as machine-readable specifications that Sentrux enforces automatically. This turns architectural decisions, which are usually informal agreements that exist only in team memory, into enforceable policies that the CI pipeline can verify and that the AI agent can read and respect.

A rules file for a typical layered architecture might look like this:

[constraints]
max_cycles = 0
max_coupling = "B"
max_cc = 25
no_god_files = true
[[layers]]
name = "core"
paths = ["src/core/*"]
order = 0
[[layers]]
name = "app"
paths = ["src/app/*"]
order = 2
[[boundaries]]
from = "src/app/*"
to = "src/core/internal/*"
reason = "App must not depend on core internals"

This configuration enforces zero dependency cycles, a maximum coupling grade, a maximum cyclomatic complexity per function, a prohibition on files that exceed a size threshold making them god objects, a layered dependency ordering that prevents higher layers from importing lower-layer internals, and a specific boundary that the application layer must not depend on core internal modules.

When Sentrux runs the check command against a codebase where the agent has violated any of these rules, it reports precisely which constraint was violated, in which file, and with what severity. The agent can read these reports through the MCP server and avoid creating violations before they occur, because the rules give it explicit knowledge of the boundaries it must stay within.

Installation and Getting Started

Sentrux is a pure Rust binary with no runtime dependencies. Installation on macOS:

brew install sentrux/tap/sentrux

Installation on Linux:

curl -fsSL https://raw.githubusercontent.com/sentrux/sentrux/main/install.sh | sh

After installation, opening the live treemap GUI for the current project:

sentrux

Opening the GUI for a specific project directory:

sentrux /path/to/project

Running a rules check in CI-compatible mode:

sentrux check .

Building from source for contributors or developers who prefer it:

git clone https://github.com/sentrux/sentrux.git
cd sentrux && cargo build --release

The single-binary architecture means there is nothing else to install, no language runtimes to manage, and no configuration required to start getting structural feedback. The 52 supported languages are available through tree-sitter plugins, and all language knowledge lives in the plugin configuration files rather than in the binary itself. Adding support for a new language requires no Rust code; it requires only a plugin configuration file and a tree-sitter grammar query file.

The Philosophy Behind the Tool

Sentrux is built on three explicit beliefs about the changing role of developers in an AI-assisted world.

The first belief is that human oversight of the architectural whole is non-negotiable. AI agents are capable of generating correct code at the local level while simultaneously destroying coherence at the global level. A human must be able to see, at any moment, what the aggregate effect of the agent’s work is on the overall structure. Sentrux makes that visibility possible.

The second belief is that verification is more valuable than generation. Generating a correct solution is harder than verifying one. Developers working with AI agents do not need to out-code the machine. They need to out-evaluate it: specify what correct architectural structure looks like, recognize when the output deviates from that specification, and judge whether the direction of change is sustainable. Sentrux turns that architectural judgment into machine-readable scores and constraints that can be evaluated automatically.

The third belief is that good systems make good outcomes inevitable. A quality gate that blocks architecturally degraded code before it is committed. A rules engine that encodes architectural decisions as enforceable constraints. A visual map that makes structural decay visible rather than hiding it in a file tree. These tools do not require developers to work harder. They change the environment so that the right thing is the natural path.

Conclusion

The challenge of maintaining architectural quality in codebases developed with AI agents is not a limitation of the models. It is a consequence of removing the feedback loop that developers previously maintained intuitively through constant spatial awareness of their codebase.

Sentrux restores that feedback loop at the structural level. The live treemap restores visibility. The five-metric quality score restores measurement. The quality gate restores the ability to detect and prevent regression. The rules engine restores the ability to enforce architectural decisions as policies. The MCP server closes the loop by giving the agent itself access to the structural feedback it needs to self-correct during the session.

For any team using AI coding agents seriously, the architectural decay problem is not hypothetical. It is already happening, session by session, in every project where structural health is not being actively monitored. Sentrux provides the sensor that makes monitoring possible, the spec language that makes constraints enforceable, and the visualization that makes structural rot impossible to ignore.

The repository is available at: https://github.com/sentrux/sentrux