fearmap 0.3.0

Analyse git repos and produce FEARMAP.md — a plain-English map of dangerous files

fearmap

Analyse any git repository and produce FEARMAP.md — a plain-English map of which files are dangerous to change, what breaks if you touch them, and what the original developer intended.

fearmap does one thing: it turns git history into understanding.

---

Example output

## Load-bearing files — do not touch without a plan

| File | Heat | Coupling Partners | Confidence |
|------|------|-------------------|------------|
| `src/flask/app.py` | 90/100 | ctx.py, templating.py, sessions.py, ... | HIGH |

### `src/flask/app.py`
**Intent:** The Flask class — the WSGI application object every Flask app instantiates.
Extends sansio/app.py with the I/O layer: request context push/pop, full WSGI dispatch loop.

**Danger:** The __init_subclass__ hook silently wraps overridden methods to add or strip
the AppContext argument. A method that matches neither old nor new signature will get a
deprecation warning and may behave unexpectedly.

**Ripple:** Changes to wsgi_app or full_dispatch_request break every request the framework
handles. Changes to default_config break any app relying on implicit config defaults.

---

Use inside Claude Code (recommended)

No pip install. No API key. No Python. Just type /fearmap inside a Claude Code session.

# Install once per repo
mkdir -p .claude/commands
curl -o .claude/commands/fearmap.md https://raw.githubusercontent.com/LalwaniPalash/fearmap/main/slash-command/fearmap.md

# Or install globally (works in all your repos)
mkdir -p ~/.claude/agents
curl -o ~/.claude/agents/fearmap.md https://raw.githubusercontent.com/LalwaniPalash/fearmap/main/agent/fearmap.md

Then open Claude Code and type:

/fearmap              # analyse entire repo
/fearmap src/         # scope to a directory (great for monorepos)

Claude Code mines your git history, reads your dangerous files, and writes FEARMAP.md directly. No external API calls — Claude Code is the reasoning engine.

See slash-command/README.md and agent/README.md for details.

---

Use as a CLI tool

For automation, CI, or when you prefer a terminal workflow:

pip install fearmap

⚠ fearmap sends file contents to the Claude API. Use --local mode if your code cannot leave your machine.

Setup

export ANTHROPIC_API_KEY=your_key_here

Commands

# Analyse current repo (asks for confirmation before API calls)
fearmap run

# With options
fearmap run --scope ./src --budget 1.50 --output FEARMAP.md --yes

# Local mode — no Claude calls, metrics only (no API key needed)
fearmap run --local

# Preview — show what would be analysed and estimated cost, don't run
fearmap preview

# Deep-dive on a single file
fearmap explain path/to/file.py

# Show coupling partners for a file
fearmap couples path/to/file.py

# Validate your fearmap.toml
fearmap config check

---

What you get

FEARMAP.md contains:

1. Onboarding path — the 7 best files to read if you're new to the codebase
2. Load-bearing files — files that must not be touched without a plan, with intent/danger/ripple analysis
3. Risky files — files that need careful handling
4. Dead files — candidates for removal (with a warning to verify no external callers)
5. Safe files — the ones you can change with confidence
6. Coupling map — which files always change together and why

Classifications

Classification	Meaning
LOAD-BEARING	Heat ≥ 70 AND 3+ coupling partners. If this breaks, a lot breaks.
RISKY	Heat ≥ 40 OR 2+ coupling partners. Change with care.
DEAD	No changes in 18+ months, no callers detected. Probably removable.
SAFE	Everything else. Change freely.

Heat score formula

heat = churn × 0.40 + coupling × 0.35 + authors × 0.15 + size × 0.10

All components are min-max normalised across the repo, giving a 0–100 score.

---

Configuration

fearmap.toml

[fearmap]
months = 12              # git history window
budget = 2.00            # max API spend per run (CLI only)
model = "claude-sonnet-4-20250514"
output = "FEARMAP.md"
scope = "."              # great for monorepos: set to "src/myservice"

[thresholds]
load_bearing_heat = 70
load_bearing_coupling = 3
risky_heat = 40
dead_months = 18

fearmap searches for fearmap.toml starting at the current directory and walking up to the git root. This lets monorepos have per-service configs.

.fearmapignore

**/generated/**
**/migrations/**
**/*.lock

---

Why fearmap, not [existing tool]?

Tool	What it does	What it lacks
CodeScene	Churn metrics, coupling charts	Paid, cloud, no plain-English explanations
code-maat	Same methodology	Requires JVM, no explanations
wily	Python complexity trends	Python only, no coupling, no explanations
GitStats	Commit statistics	No per-file danger analysis

fearmap is the only tool that reads your actual code and explains, in plain English, why a file is dangerous and what will break if you touch it.

---

Privacy

The CLI (fearmap run) sends file contents to the Anthropic API. Use --local mode if your code cannot leave your machine:

fearmap run --local

Local mode produces a metrics-only FEARMAP.md with classifications but no intent/danger explanations.

Mode 2 (Claude Code native) makes no external API calls beyond your normal Claude Code session.

---

Commit FEARMAP.md

FEARMAP.md is meant to be committed and versioned alongside your code. It's documentation, not a build artifact. It helps every engineer who clones your repo understand which files to fear.

---

Contributing

See docs/contributing.md.

---

License

MIT — see LICENSE.