COMPLEX.md
Know where your code breaks before your agent does.
One file at the root of your repository. Computed from its history. Read by every coding agent you use.
npx complex-md--- complex_md: "0.3" generated: 2026-09-02 hotspots: - path: fastify.js churn: 234 fixes: 53 fan_in: 24 tests: 63 score: 29220 - path: lib/errors.js churn: 45 fixes: 18 fan_in: 17 tests: 10 score: 10806 co_change: - files: [lib/errors.js, types/errors.d.ts] count: 18 coupling: 95 --- ## Why these files are hot fastify.js is the constructor and plugin root: 234 of the last 2,000 commits touched it, 53 of them bug fixes, and 24 modules depend on it. Edits tend to break lib/route.js, which moves with it in 45% of its commits. Before editing this file, open lib/route.js and fastify.d.ts alongside it and run the type tests.
Why COMPLEX.md?
Every codebase has a few files that break again and again. The people who built it know which ones. Your agent does not.
COMPLEX.md is measured, not remembered. It reads your repository's own history and writes down where the risk lives, with one clear instruction for each risky file.
- Finds the files that break most often.
- Warns before a change reaches everything that depends on it.
- Keeps files that change together, together.
Every number on this page comes from a real run. Nothing is uploaded; the analysis takes about a second on your machine.
Works with the agents you already use.
- Claude Code
- Cursor
- Codex
- Gemini CLI
- GitHub Copilot
- OpenHands
- Windsurf
- Cline
- Roo Code
- OpenClaw
- Hermes
- VS Code
- opencode
- goose
- Amp
- Jules
- Zed
- Warp
- Aider
- Devin
- Factory
- Kilo Code
- Junie
- Augment
- MCP
Examples
--- complex_md: "0.3" generated: 2026-09-02 commit: af6e2e43 tool: complex-md/0.4.0 window_commits: 2000 files_analyzed: 62 profile: commits_analyzed: 1871 dependency_edges: 372 confidence: structure+history hotspots: - path: fastify.js kind: source loc: 1009 churn: 234 churn_w: 75.49 fixes: 53 authors: 66 owner_share: 0.44 fan_in: 24 tests: 63 score: 29220 - path: lib/errors.js kind: source loc: 554 churn: 45 churn_w: 15.91 fixes: 18 authors: 30 owner_share: 0.11 fan_in: 17 tests: 10 score: 10806 co_change: - files: [lib/errors.js, types/errors.d.ts] count: 18 coupling: 95 blind_spots: - 3 generated or lock files excluded --- ## Where the risk lives Risk concentrates in fastify.js, the constructor and plugin root that 24 modules depend on, and in lib/errors.js, whose type declaration in types/errors.d.ts moves with it in 95% of its commits. ## Why these files are hot fastify.js is the constructor and plugin root: 234 of the last 2,000 commits touched it, 53 of them bug fixes, and 24 modules depend on it. Edits tend to break lib/route.js, which moves with it in 45% of its commits. Before editing this file, open lib/route.js and fastify.d.ts alongside it and run the type tests. ## What to read first 1. fastify.js, the plugin root every request passes through. 2. lib/route.js, because it moves with fastify.js in nearly half of its commits.
How to use it
1. Run it once
In any git repository: npx complex-md. It reads the history,
writes COMPLEX.md at the root, and connects it to your agents.
2. Or ask your agent
No Node.js? Download the skill and hand it to any coding agent. It does the same analysis with git alone.
3. It wires itself in
A note in your agent files. Rules that wake up when a risky file is opened. Where your agent supports it, a pause before the first risky edit.
4. Run it again after big changes
The map rebuilds in a second. Commit it with your change.
Why this exists
Agents were given instructions, never evidence. AGENTS.md tells them how to work. Nothing tells them where the danger is.
That gap costs every team the same bugs, twice. COMPLEX.md closes it: an open format any repository can adopt in a minute, and a standard we believe every codebase should carry.
If your agent reads it, your code gets safer. Help make that normal.
FAQ
How is this different from AGENTS.md?
AGENTS.md says how to work in the project. COMPLEX.md says where the risk is. They link to each other.
Do I need an API key?
No. With one, the tool writes the explanations itself. Without one, your agent does. Your code never leaves your machine.
What does the score mean?
A ranking, not a prediction. Higher means an edit has more ways to go wrong. The spec shows the formula.
What about languages it cannot read?
They are listed under blind_spots, and the file says so when they dominate.
Can I write one by hand?
Yes. Plain markdown with a YAML header. The walkthrough takes seven git commands.
npx says "No versions available". Why?
Your npm config sets min-release-age, which refuses packages published this week. Run npm_config_min_release_age=0 npx -y complex-md once.
How do I keep it out of my agent's way?
--no-hooks skips the edit pause. --no-wire only writes the file. Everything added is marked and safe to remove.