tectonix

Headless code quality analysis for AI coding agents.

tectonix is a terminal and MCP server tool. It scans a codebase, builds a structural model, computes quality signals, checks architectural rules, and returns machine-readable JSON. There is no GUI, no windowing stack, no licensing tier, and no paywall.

Install

cargo install --git https://github.com/DevomB/Tectonix

Or build from source:

git clone https://github.com/DevomB/Tectonix.git
cd tectonix
cargo build --release

The first run downloads runtime tree-sitter grammar libraries for the current platform into ~/.tectonix/plugins. Plugin configs are embedded and synced automatically.

Terminal Usage

All terminal commands print JSON to stdout.

tectonix scan .
tectonix rescan .
tectonix health .
tectonix check-rules .
tectonix git-stats . --days 90
tectonix dsm . --format text
tectonix test-gaps .
tectonix session-start .
tectonix session-end .

session-start writes .tectonix/session-baseline.json in the scanned project. session-end rescans and compares current health against that baseline.

MCP Server

Run the MCP server over JSON-RPC on stdin/stdout:

tectonix --mcp

MCP client config:

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

Available MCP tools:

Tool	Purpose
scan	Scan a directory and cache structural analysis state
health	Return quality signal and root-cause diagnostics
check_rules	Validate .tectonix/rules.toml
git_stats	Report churn, hotspots, bus factor, and change coupling
dsm	Return dependency structure matrix data
test_gaps	Find high-risk source files without tests
rescan	Re-scan the current directory
session_start	Save the current state as an in-memory baseline
session_end	Re-scan and compare against the in-memory baseline

Example JSON-RPC request:

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

Rules

Create .tectonix/rules.toml in a project:

[constraints]
max_cycles = 0
max_cc = 25
max_fn_lines = 100
no_god_files = false

[[layers]]
name = "core"
paths = ["src/core/*"]
order = 0

[[layers]]
name = "app"
paths = ["src/app/*"]
order = 1

[[boundaries]]
from = "src/app/*"
to = "src/core/internal/*"
reason = "App must not depend on core internals"

Then run:

tectonix check-rules .

Output Model

The primary quality value is quality_signal, reported on a 0..10000 scale for terminal and MCP consumers. Diagnostics are grouped by root cause:

• modularity
• acyclicity
• depth
• equality
• redundancy

The intended loop is simple:

1. scan
2. inspect health
3. make targeted code changes
4. rescan
5. compare with session_end or rules

Language Support

Language support is data-driven through plugins/<language>/plugin.toml and queries/tags.scm. The binary loads tree-sitter grammar libraries at runtime and does not compile language-specific parsers into the Rust code.

The repository includes plugin definitions for 52 languages. Runtime grammar libraries are downloaded from the release asset matching the binary version and platform.

Set TECTONIX_SKIP_GRAMMAR_DOWNLOAD=1 to disable automatic grammar download in deterministic CI or offline tests.

Development

cargo check
cargo test
cargo build --release

Release smoke test:

printf '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}\n' | ./target/release/tectonix --mcp

License

MIT