adit-code

adit-code

Finds the files in your codebase that are structurally expensive to work with — for humans and AI agents alike — and tells you exactly what to fix.

wc -l tells you a file is big. adit tells you it has 51 parameters on one function, nesting 16 levels deep, and 8 ambiguous names that pollute every grep. Each finding maps to a specific refactoring action.

An adit is a horizontal tunnel driven into a hillside to provide access to a mine. adit-code tunnels into your codebase to find the structural hot spots.

What It Reports

$ adit score --pretty .

adit v0.1.0

  File              Lines  Size   Nest  Reads  Unneeded  Noise  Blast
  ────────────────────────────────────────────────────────────────────
  engine.py          3200    D       8     12        4      8      8
  handlers.py         890    B       5      7        3      2      3
  utils.py            420    A       3      2        0      0     15

  Co-locate (single-consumer imports):
    TRUST_HINTS (const)   constants.py:15 -> handlers.py

  Ambiguous names:
    _validate   3 defs: engine.py:42 handlers.py:88 auth.py:15

  Uncommented (large files, 0 comments — AI agents benefit from comments):
    engine.py (3200 lines)

  Import cycles: none

Every finding is actionable:

Validated Against Real Agent Behavior

Correlated against SWE-bench agent trajectories — 1,840 files across 49 repos, 10,000 agent runs. File size is the strongest predictor of agent tool call cost (median Spearman +0.474, positive on all 49 repos). The structural metrics tell you what specifically to fix:

File size does most of the predictive work. The structural metrics don't predict better — they tell you why a file is expensive and what to change. wc -l says "this file is 3,200 lines." adit says "split it, and while you're at it, that function with 15 parameters needs a config object and those 8 levels of nesting need extracting."

Install

go install github.com/justinstimatze/adit-code/cmd/adit@latest

Or build from source:

git clone https://github.com/justinstimatze/adit-code.git
cd adit-code
go build ./cmd/adit

Single binary. Analyzes Python, TypeScript, and Go with one tool — no need for separate linters per language. Uses tree-sitter for parsing. No runtime dependencies.

Some of what adit checks (nesting depth, parameter count) overlaps with language-specific linters like pylint or eslint. adit's value is the cross-language consistency, the co-location and grep noise metrics that no linter checks, and the --diff mode for CI regression gates.

Quick Start

adit score .                          # JSON (default — for CI and AI tools)
adit score --pretty .                 # Human-readable table
adit score --diff HEAD~1 --pretty .   # What changed and what got worse
adit enforce .                        # CI gate — exit 1 if thresholds exceeded
adit enforce --diff HEAD~1 .          # Only enforce on changed files
adit mcp                              # MCP server for Claude Code / Codex

What It Measures

Five metrics. No composite score — each answers a different question.

Context Reads — How many files must the AI read to understand this file? Flags single-consumer imports (names imported by only one file) that should be co-located. Each unnecessary import is a wasted Read tool call.

Grep Noise — How much search noise surrounds this file? Counts ambiguous names this file defines or imports that are also defined elsewhere. _validate in 5 files = 4 extra grep results to wade through.

File Size — How many reads and re-reads does this file cost? AI tools read files in chunks, not all at once. Larger files require more reads and the AI loses coherence across distant methods. Grades A (<500 lines) through F (5000+) based on empirically validated thresholds.

Blast Radius — How many files reference this one? High-blast files are central definitions that get read often for context.

Import Cycles — Circular dependencies that waste AI context (A reads B, B reads A, loop).

Configuration

Create adit.toml in your project root:

[thresholds]
max_file_lines = 3000
max_context_reads = 10
max_unnecessary_reads = 3
max_ambiguity_defs = 3
max_blast_radius = 20
max_cycle_length = 0           # 0 = no cycles allowed

[scan]
languages = ["python", "typescript"]
exclude = ["test_*.py", "*.test.ts", "**/__pycache__/**", "**/node_modules/**"]

# Looser thresholds for specific paths
[per-path."test_*.py"]
max_file_lines = 5000

Also reads [tool.adit] from pyproject.toml. Config is auto-discovered by walking up from the target path.

AI Agent Integration

MCP Server (Claude Code, Codex, any MCP-compatible agent)

{
  "mcpServers": {
    "adit": { "command": "adit", "args": ["mcp"] }
  }
}

7 tools: adit_score_repo, adit_score_file, adit_relocatable, adit_ambiguous, adit_blast_radius, adit_cycles, adit_diff.

CLI + JSON (any agent that shells out)

JSON-default output. Any agent that can run commands and parse JSON works:

adit score .              # full analysis
adit enforce --diff $REF  # PR gate

CLAUDE.md / AGENTS.md

Add to your project's AI instruction file:

## Structural Health
This project uses adit for code structure analysis.
- Before committing: run `adit enforce .` — fix violations, don't skip.
- When adit reports relocatable imports: move the definition to the consumer file.
- When adit reports ambiguous names: rename to be more distinctive.

Pre-commit Hook

repos:
  - repo: local
    hooks:
      - id: adit
        name: adit enforce
        entry: adit enforce
        language: system
        types_or: [python, ts, tsx, go]

CLI Reference

adit score [PATHS...]                  # JSON (default)
adit score --pretty [PATHS...]         # Human table
adit score --diff REF [PATHS...]       # Compare against git ref
adit score --min-grade C .             # Only files at grade C or worse
adit score --sort blast .              # Sort: blast|reads|noise|size|name
adit score --quiet .                   # Metrics only, no recommendations
adit score --silent .                  # No output, exit code only

adit enforce [PATHS...]                # Exit 1 if thresholds exceeded
adit enforce --diff REF .              # Only enforce on changed files
adit enforce --silent .                # Exit code only

adit mcp                               # MCP server (stdio)

Exit codes: 0 = pass, 1 = issues found, 2 = tool error.

Performance

Fast on most repos: ~150 files/sec. Cross-file analysis (co-location, blast radius, grep noise) is O(n²) and dominates on large repos:

Deeper Validation

Beyond the headline correlations, session-level analysis reveals:

File size effect — AI tool calls by file size grade:

Re-reads per session — The AI re-reads large files repeatedly within a single session. Avg reads-per-session by grade: A=5.8, B=13.2, C=29.6, F=54.0.

Edit success rate — Files with more imports have higher re-edit rates (r=+0.437). Re-edit rates by grade: A=59%, B=77%, D=87%, F=89%. More coupled files are harder to get right on the first try.

Across open source projects

adit scored against 33 open source projects across Python, TypeScript, and Go. Generated files (migrations, protobuf, etc.) are auto-detected and excluded.

Python

TypeScript

Go

Key findings:

• Salt has the worst parameter complexity (51 params) and deepest nesting (16 levels). PyTorch follows with 53 max params. Nova has 47.
• TypeScript compiler and TypeORM have the deepest nesting in TS (18-19). Deno std reaches 21 despite tiny file sizes.
• Go projects have lower max params (5-40) and moderate nesting (8-13). CockroachDB is the exception with 12 Grade F files.

Reproduce on your own repos:

adit score --pretty /path/to/project

License

MIT. All dependencies MIT or BSD-2. See INFLUENCES.md for full citation record, prior art search, and license audit.