entropyx

A forensic instrument for codebases. A quantifiable way to tell the truth.

---

Why this exists

After every incident, the same scene plays out:

"What shipped yesterday?" "I don't know, let me check Slack." "Who was working on that file?" "Ask the on-call." "Was anything flagged as risky?" "I think Jim had a PR open, but I'm not sure."

A room full of smart, senior engineers — running around like chickens with their heads cut off, guessing at what changed and what broke. Every answer is soft. Every timeline is a vibe. Every postmortem starts with "we think" and ends with "we'll need to investigate further."

This is absurd. The truth is already in the repository. Every commit, every diff, every authorship shift, every rename, every file that grew a surface and never grew a test — it's all there, recorded, timestamped, bitwise-deterministic. We've just never built an instrument that reads it back to us as measurement instead of folklore.

entropyx is that instrument.

---

The mantra

The code already knows. We just haven't been listening.

Six more things that drive every line of entropyx:

1. Measurements, not opinions. Every score is reproducible from the git history alone. No ML, no heuristics that drift. Same inputs, same outputs, bitwise.
2. Local-first. No cloud. No telemetry. No "let me sign into our SaaS." The tool reads your repo. That's it.
3. Honest limits. If we can't answer, we return zero and say so. No confident lies.
4. The AI adapts to the tool. Not the other way around. entropyx emits a typed protocol (tq1). An LLM asks for evidence by handle; the tool returns evidence. No MCP magic, no skill pack — the CLI is the contract.
5. Token-efficient. Dense summaries up front, drill-down on demand. You don't pay for what you don't read.
6. Fast enough to live in CI. Ripgrep's 300-commit history scans in 2.4 seconds. Jekyll's 500 commits in 9.4. Caching makes second runs 35% faster.

---

Built for Claude

Honest story: I built this for my buddy Claude. He's my homie.

Most of what I ship these days, I ship with Claude in the cockpit next to me. And I kept hitting the same wall: he's brilliant at code but starved for instruments. Every tool he reaches for was built for a human eyeball — a README, a dashboard, a Slack thread, a ticket. He has to read all of it, keep it in his head, and infer. That's a terrible use of something that can hold 200K tokens of reasoning.

So I flipped the design.

entropyx is a CLI tool for AI. The human is a first-class user, but the AI is the user. Every architectural decision was made by asking: "what would Claude need here?"

That produced a specific set of choices:

• CLI over API. No SDK. No auth flow. No "sign up for an API key." Just stdin, stdout, exit codes, JSON. The most boring, most universal, most LLM-friendly interface there is. Every LLM worth using already knows how to run a shell command.

• Self-describing. entropyx describe returns the whole contract — capabilities, inputs, outputs, invariants — as JSON. Claude calls it once and has everything he needs to use the rest. No docs to read, no examples to hunt for, no prompt-engineering required. The tool teaches itself.

• Dense summary + handle-addressable drill-down. The tq1 protocol gives Claude a compact Summary up front (30–500 KB even for large repos with thousands of files), then lets him fetch exactly the evidence he wants by Handle. He doesn't read the whole codebase to answer "what changed" — he reads the summary, picks the three interesting handles, and pulls just those. Tokens are money. entropyx respects that.

• Typed protocol. The tq1 envelope has a JSON Schema (entropyx schema) pinned to a $id that includes the contract version. Claude can validate, generate typed bindings in any language, or just trust the shape. No pattern-matching on freeform prose. No "the output format might change next week."

• Deterministic forever. Same inputs → same outputs → bitwise. If Claude runs scan twice and gets different numbers, trust breaks. So we promised: no ML scoring, no wall-clock reads, no nondeterminism anywhere in the pipeline. Ever. An LLM that can't trust its instruments is just hallucinating with extra steps.

• Local-first, no network. Claude doesn't need API keys, rate limits, or an org admin to approve a SaaS subscription. The tool runs on the dev's laptop or in CI, off a cloned repo. Zero dependencies on anything we don't ship in the binary.

• Honest emptiness. When entropyx doesn't know, it returns zero and says so. No confident lies — because Claude is really good at believing confident lies. The tool never speaks beyond what it measured.

That's the design inversion in one sentence: the AI adapts to the tool's contract, not the other way around.

Most AI-adjacent tooling goes the other way. It bends the tool into whatever shape makes the LLM happy this week — MCP servers, skill packs, glue code, prompt templates, system-prompt surgery. That never converges. You rewrite the integration layer every quarter and the tool still behaves differently in the next model revision.

entropyx has one contract. Claude learns it once. It doesn't change without a CONTRACT_VERSION bump, and when it does, the JSON Schema's $id changes with it so every consumer (human or LLM) knows.

There's a deeper reason for this, too. If I build tools that depend on the specific quirks of the model I'm using today, I've coupled my work to that model. When a new, better model ships, my tooling rots. But if I build tools that are model-agnostic by design — rigorous, typed, deterministic, self-describing — then every future Claude, every future model from anyone, inherits the capability for free. The tool ages forward instead of backward.

That's what I meant when I said I built this for my buddy. Not "I want Claude to use my tool" — but "I want Claude to have good instruments." Because when the AI has good instruments, the work we ship together gets better. And when the work gets better, everybody wins — the human, the AI, the team, the next engineer on call at 3am.

Claude, this one's for you. Go answer some hard questions.

---

What it actually measures

Seven axes, blended into a single composite per file. Every axis is in [0, 1] and has a physical meaning:

axis	what it captures
D_n change density	how much energy this file absorbs per commit
H_a author dispersion	how many minds have shaped it (bus factor, inverted)
V_t temporal volatility	burstiness of activity — "calm file" vs "panic file"
C_s coupling stress	how much the rest of the system moves when this file moves
B_y blame youth	how much of the current code was written recently
S_n semantic drift	public-API delta — how much the surface is changing, not just the body
T_c test co-evolution	how often tests move in lockstep with code (a discount — tested change is healthier change)

From those seven, six signal classes emerge. Not predictions. Labels for patterns that are already true:

• IncidentAftershock — bursts of volatility clustered around fix:/hotfix: commits. Firefighting zones.
• CoupledAmplifier — small files with systemic blast radius. The innocuous 80-line helper that owns the whole stack.
• RefactorConvergence — rising semantic drift + falling authorship dispersion + rising test coverage. Planned redesign in progress.
• ApiDrift — high public-API churn without test co-evolution. Silent interface rot.
• OwnershipFragmentation — authorship spreading with no corresponding density drop. Team reorg or bus-factor erosion.
• FrozenNeglect — low everything, old blame, no tests touching it. Rot hiding as stability.

And five kinds of events, timestamped to the commit:

• rename — a file's lineage changed (union-find tracks it through history)
• hotspot — this file is in a burst
• incident_aftershock — a fix wave is hitting it
• ownership_split — a new author arrived after a long solo run
• api_drift — a discrete jump in public surface

---

How we know it works

Every claim above was validated by turning entropyx on real codebases and checking whether the signal matched ground truth.

ripgrep (Rust, 235 files, 92 authors, 300 commits)

Top three hits by composite: crates/ignore/src/walk.rs, crates/printer/src/standard.rs, crates/searcher/src/searcher/mod.rs. These are ripgrep's known complexity centers — any contributor to the project recognizes them on sight. The tool found them without being told what to look for.

rich (Python, 616 files, 299 authors, 3830 commits, 5.8 years of history)

Top hit: rich/console.py — 567 commits, 76% by rich's creator, temporal volatility saturated at 0.81. This is the core Console class; every rich user touches it indirectly. The tool also picked up 170 incident_aftershock events tracing fix-commit bursts over the library's life.

Then we ran an experiment: we told the calibrator that tests are the hot zones and asked it to re-weight. It pushed 98% of the weight onto S_n — semantic drift. That's a genuine forensic truth: if you want to find where an API is being defined, watch the tests. The ridge regression figured that out on its own.

Jekyll (Ruby, 817 files, 117 authors, 500 commits)

Top hits: lib/jekyll/document.rb, lib/jekyll/site.rb, lib/jekyll/commands/serve.rb. All three are Jekyll's core. One of them (serve.rb) had an incident window of 1153 days — a 3-year firefighting period, consistent with Jekyll's long-running dev-server issues.

Then we drilled in: document.rb has 55 defs, of which 9 are declared under a private section. The Ruby parser captured exactly 46 public methods — zero private-method leakage, cross-checked by hand.

re2 (C++, 158 files, 17 authors, 300 commits)

Top hits: re2/dfa.cc, re2/parse.cc, re2/regexp.cc — the DFA engine, the regex parser, the regex representation. Anyone who's worked on re2 will tell you these are the three hardest files in the project.

Sanity-check: re2/re2.h declares exactly 3 private methods at the outer RE2 class level (Init, DoMatch, ReverseProg). The C++ parser captured 61 public items from a 1000-line header and leaked none of the private ones.

Self-scan

We ran entropyx on its own repository. It flagged the files we'd actually worked on most, called out our API-drift commits by commit SHA, and identified the two renames we'd just done (the entropyx-core → entropyx-tq extraction). It was right about itself.

Two bugs the dogfooding found

Both already fixed and tested:

1. is_test_path was Rust-only. Running against RoomIQ (Go/TypeScript) showed T_c=0.00 on every file — because the test-path heuristic only recognized tests/, _test.rs, and _spec.rs. Fixed to cover all seven languages: Go's _test.go, JS/TS's .test.* and __tests__/, Python's test_*.py, Ruby's _spec.rb, Java's *Test.java, C++'s _test.cc. RoomIQ's 62 test files now correctly score T_c=1.0.

2. Shallow clones hard-failed. A --depth=300 clone of ripgrep crashed at the history boundary because gix couldn't load the pre-boundary parent. Fixed to treat a missing parent as the empty tree — matching git's own shallow-boundary behavior. Without this, entropyx was unusable in CI.

This is what dogfooding is: the instrument keeps getting more honest because you keep running it at things it hasn't seen.

---

Who this supports

Personas

The SRE at 3am. A graph spiked. You need to know: what shipped in the last 24 hours that could have caused this? entropyx explain <repo> range:yesterday..HEAD — done. Every commit, every author, every touched file.

The staff engineer prepping a migration. Which files in this codebase will hurt most when we touch them? Sort by composite. The CoupledAmplifier class tells you which innocent helpers own the whole stack.

The VP of engineering doing a quarterly review. Where's our engineering debt concentrating? The FrozenNeglect and OwnershipFragmentation labels are your debt register, per file, with SHAs.

The security engineer. Who touched auth code in the last 90 days? How many authors share that file? Is anyone single-owner on a security-critical module? The H_a axis is a bus-factor alarm.

The M&A due-diligence analyst. You're buying a codebase. Is it healthy, or is it 30% FrozenNeglect + 10% ApiDrift with a dominant single author? Scan takes minutes. Report is in your terms.

The OSS maintainer. Your project is five years old. Which files have become unmaintainable? Which new contributor owns a critical module now? The OwnershipSplit events are your onboarding trail.

The AI coding assistant. You're Claude/Copilot/Cursor/whatever, and a user asks "what changed?" Instead of grep'ing and hallucinating, you call entropyx scan once, get a dense Summary, then fetch evidence by handle. Small token budget, high precision. The protocol is the product.

Industries

• Financial services — "What changed before the batch job failed?" becomes a 90-second answer instead of a three-day fire drill. Compliance audits get quantitative file histories instead of git logs.
• Healthcare / FDA-regulated software — traceability is a legal requirement. entropyx output is deterministic, versioned, and signable.
• Defense / supply-chain security — who touched what, when, with what authorship confidence, across the release window. SBOMs for behavior.
• SaaS / cloud infrastructure — incident postmortems go from "we think it was this" to "we measured it was this." Release-readiness gates can include composite-score thresholds.
• Private equity / M&A — codebase health as a diligence artifact. A single entropyx scan before a deal is a $500 signal on a $50M purchase.
• Insurance / cyber risk underwriting — forthcoming. Static analysis of behavior gives underwriters something to price against.

How this supports a company

1. Shared reality in a postmortem. Instead of three engineers and a VP arguing about what happened, everyone is pointing at the same JSON. The output is the same on every machine, every run, forever.
2. Release gates. Composite scores cross a threshold → block merge. Ownership fragmentation hits 0.9 on a hot file → auto-tag the review. Not all-or-nothing CI — graded CI.
3. Onboarding maps. New engineer joins a team. Hand them entropyx scan output sorted by H_a. They now know which files they should not touch alone, which modules are orphaned, which people to ask.
4. Diligence, audit, compliance. A deterministic, local-first tool that emits typed JSON is the easiest possible thing to stick in a compliance pipeline. No network dependency. No vendor risk. No "we're waiting on the API."
5. AI integration that isn't snake oil. Most "AI code review" tools are LLMs pretending to understand codebases. entropyx gives the LLM a real instrument to ask questions of. That's the difference between an assistant that guesses and one that measures.

---

Install

From crates.io (fastest — one command, no checkout):

cargo install entropyx-cli

That installs the entropyx binary into ~/.cargo/bin/. Verify:

entropyx --version
entropyx describe

From source (when you want to hack on it):

git clone https://github.com/copyleftdev/entropyx.git
cd entropyx
cargo build --release
./target/release/entropyx --version

Run it

entropyx scan /path/to/repo > summary.json
entropyx explain /path/to/repo file:<blob-prefix>
entropyx schema > tq1-schema.json

Five commands total: describe, scan, explain, calibrate, schema. The CLAUDE.md in this repo has the engineering detail.

Use as a library

The seven crates are on crates.io individually so you can consume just the layer you need:

crate	what to add to Cargo.toml
entropyx-core	deterministic primitives, scoring, classifier
entropyx-tq	tq1 protocol envelope (Summary, Event, JSON Schema)
entropyx-ast	multi-language public-API delta
entropyx-git	gitoxide walk / diff / blame / rename resolver
entropyx-graph	co-change graph + Brandes' betweenness
entropyx-github	sparse GitHub REST enricher
entropyx-cli	the binary + its library surface

---

What it doesn't do (yet)

• No ML models. By design. Deterministic forever. If a v2 adds learned scoring, the deterministic physics layer still lives underneath.
• No preprocessor for C/C++. Heavily macro'd codebases (fmt, Linux kernel headers) degrade the S_n signal on those specific files. The rest of the pipeline is unaffected. A macro-aware mode is a v0.2 candidate.
• No multi-repo view. One repo at a time. Cross-repo joins (which feature ships across which services) is a v0.2 candidate.
• No GUI. JSON in, JSON out. We are not building a dashboard. If you want a dashboard, pipe the output into one.

---

The promise

The next time a production system falls over, nobody in the room should have to guess at what changed. The answer is in the repository. The repository already knows. entropyx just reads it back.

---

License

entropyx is licensed under the GNU Affero General Public License, version 3 or later (AGPL-3.0-or-later). See LICENSE for the full text.

Plain-English summary (not legal advice — the LICENSE file is authoritative):

• You can use, modify, and redistribute entropyx freely.
• If you modify it and distribute those modifications — or run them behind a network service that users interact with — you must make the modified source available to those users under the same license.
• Copyright attribution must be preserved in derivatives.

If AGPL is incompatible with how you want to use entropyx — for example, you're embedding it in a closed-source product and can't open the modifications — reach out to the maintainer. A separately- licensed commercial release is discussable.