Map features in any codebase from git history alone. No Jira required.
Point faultlines at a git repo and get back a feature map — which parts of your product accumulate the most bug fixes, who owns what, and where the risk is hiding. Works on any language, any size, any repo.
pip install faultlines
export ANTHROPIC_API_KEY=sk-ant-... # or use Ollama for free local analysis
faultlines analyze .That's it. You'll see something like:
╭──────────────────────────── FeatureMap Analysis ─────────────────────────────╮
│ Repository: /home/you/your-project │
│ Features found: 22 Bug fix commits: 125 Health: 60.2/100 │
╰──────────────────────────────────────────────────────────────────────────────╯
Features by Risk
╭─────┬────────────────────────┬────────┬─────────┬───────────┬────────────────╮
│ │ Feature │ Health │ Commits │ Bug Fixes │ Bug % │
├─────┼────────────────────────┼────────┼─────────┼───────────┼────────────────┤
│ ✗ │ payments │ 23 │ 112 │ 38 │ 33.9% │
│ ✗ │ booking-engine │ 29 │ 487 │ 151 │ 31.0% │
│ ! │ auth │ 54 │ 48 │ 12 │ 25.0% │
│ ✓ │ dashboard │ 83 │ 67 │ 2 │ 3.0% │
╰─────┴────────────────────────┴────────┴─────────┴───────────┴────────────────╯
- Reads your git history — commits, blame, file changes over the last year
- Clusters files into features — using Claude Sonnet (or local Ollama) to group by business domain, not folder names
- Scores each feature — by bug-fix density, churn, bus factor, and age-weighted trends
- Detects user flows — with
--flows, breaks features into end-to-end user journeys (checkout-flow,signup-flow,manage-team-flow) - Maps test coverage per feature — with
--coverage, shows which features and flows are well-tested and which are exposed - Outputs JSON —
~/.faultlines/feature-map-*.json, ready for dashboards or CI
Without --llm: "components", "views", "hooks" ← technical folders
With --llm: "payments", "booking-engine", "auth" ← business features
The LLM reads your file tree and commit messages to produce names an engineering manager would actually use.
Every number below is from a real faultlines analyze --llm --flows run. Reproduce any of them yourself.
| Repo | Files | Features | Flows | Time | What it found |
|---|---|---|---|---|---|
| cal.com | 10,463 | 282 | 725 | 23m | trpc/viewer, web/bookings, ee/billing, web/settings |
| plane | 4,932 | 134 | 408 | 12m | web/issues, editor/extensions, web/workspace, web/pages |
| Ghost | 6,898 | 101 | 281 | 14m | admin-x, ghost/members, ghost/email, stats |
| outline | 2,390 | 22 | 188 | 6m | rich-text-editor, api-backend, dashboard, plugins |
| documenso | 2,530 | 49 | 191 | 8m | trpc/envelope, remix/document-signing, ee/billing |
| formbricks | 3,316 | 33 | 136 | 8m | web/survey, web/organization, web/auth |
| excalidraw | 1,225 | 15 | 35 | 4m | excalidraw/shared-ui, excalidraw/data, renderer |
| trpc | 1,573 | 14 | 37 | 1m | server/core, client/links, openapi, next-adapter |
| gin | 130 | 22 | — | 15s | binding, render, context, recovery, logger |
| fastapi | 2,981 | 14 | — | 80s | routing, dependencies, security, openapi, middleware |
Libraries (gin, fastapi) are auto-detected and show modules instead of business features. Flows are suppressed for libraries since they don't have end-user journeys.
pip install faultlinesRequires Python 3.11+.
pip install 'faultlines[ollama]'faultlines analyze .
faultlines analyze ./path/to/repo
faultlines analyze . --days 90 --top 5# Claude (cloud) — best quality
export ANTHROPIC_API_KEY=sk-ant-...
faultlines analyze . --llm
# With flow detection
faultlines analyze . --llm --flows
# Focus on source directory
faultlines analyze . --llm --flows --src src/
# Ollama (local, free)
ollama pull llama3.1:8b
faultlines analyze . --llm --provider ollamaGet your API key at console.anthropic.com.
Automatically detects and analyses workspace packages:
- pnpm (
pnpm-workspace.yaml) - npm/yarn (
package.jsonworkspaces) - Turborepo, Nx, Lerna
- Cargo workspaces, Go workspaces
Large monorepos are scanned per-package in parallel (4 workers).
With --flows, each feature is broken into user-facing flows — named action sequences like checkout-flow or manage-team-flow.
╭──────┬───────────────────────────┬────────┬─────────┬───────────╮
│ │ Feature / Flow │ Health │ Commits │ Bug Fixes │
├──────┼───────────────────────────┼────────┼─────────┼───────────┤
│ ✗ │ web/settings │ 23 │ 206 │ 144 │
│ │ ├─ manage-org-roles │ 11 │ 37 │ 30 │
│ │ ├─ manage-oauth-clients │ 15 │ 13 │ 10 │
│ │ └─ manage-billing │ 50 │ 24 │ 12 │
│ ✓ │ auth/server │ 87 │ 18 │ 6 │
│ │ └─ login-flow │ 87 │ 18 │ 6 │
╰──────┴───────────────────────────┴────────┴─────────┴───────────╯
Flow names and health scores are real — from actual Haiku detection against git commit history.
With --coverage, faultlines reads your existing coverage report and maps it to features and flows:
# Python
coverage run -m pytest && coverage json
faultlines analyze . --llm --flows --coverage coverage.json
# JS/TS (Jest or Vitest)
npx jest --coverage
faultlines analyze . --llm --flows --coverage coverage/coverage-summary.json
# Auto-detect (looks for common coverage files)
faultlines analyze . --llm --flows --coverageSupports: Python coverage.py (.coverage, coverage.json), Cobertura XML, Jest/NYC, LCOV.
╭───┬──────────────────┬────────┬───────┬─────────╮
│ │ Feature │ Health │ Bug % │ Cov % │
├───┼──────────────────┼────────┼───────┼─────────┤
│ ✗ │ element/arrows │ 13 │ 75% │ 50% │
│ ✗ │ font-management │ 16 │ 67% │ 97% │
│ ! │ excalidraw/data │ 39 │ 63% │ 60% │
│ ✓ │ math │ 69 │ 50% │ 91% │
╰───┴──────────────────┴────────┴───────┴─────────╯
The insight: element/arrows has 75% bug ratio and only 50% coverage — the exact spot where adding tests would prevent the most regressions.
Results save to ~/.faultlines/feature-map-{repo}-{timestamp}.json:
{
"repo_path": "/path/to/repo",
"remote_url": "https://github.com/org/repo",
"features": [
{
"name": "payments",
"description": "Stripe payment processing and subscription billing",
"health_score": 23.0,
"bug_fix_ratio": 0.339,
"total_commits": 112,
"bug_fixes": 38,
"authors": ["alice", "bob"],
"paths": ["src/payments/stripe.py", "src/payments/webhooks.py"],
"flows": [
{
"name": "checkout-flow",
"health_score": 18.0,
"total_commits": 67,
"bug_fixes": 28,
"bus_factor": 1,
"hotspot_files": ["src/payments/charge.ts"]
}
]
}
]
}The health score (0–100) uses an age-weighted sigmoid based on bug-fix ratio:
| Bug fix % | Health | Status |
|---|---|---|
| 0–20% | 85–99 | ✓ Healthy — mostly feature work |
| 20–40% | 55–85 | ✓ Normal active development |
| 40–55% | 30–55 | ! Elevated — worth watching |
| 55–75% | 10–30 | ✗ High debt — maintenance-dominant |
| 75%+ | 0–10 | ✗ Critical — almost all bug fixes |
Recent bugs (< 30 days) weigh 2x more than older ones, so features that are actively getting worse score lower.
faultlines analyze [REPO_PATH]
| Flag | Default | Description |
|---|---|---|
--llm |
off | AI-powered semantic feature detection |
--flows |
off | Detect user-facing flows (requires --llm) |
--provider |
anthropic |
LLM provider: anthropic or ollama |
--model |
auto | Model override |
--api-key |
env | Anthropic API key |
--src |
— | Focus on subdirectory (e.g. src/) |
--days |
365 |
Days of git history |
--top |
3 |
Top risk zones to highlight |
--output |
~/.faultlines/ |
Output file path |
--coverage |
auto | Path to coverage report (lcov, jest, cobertura, coverage.py) |
--no-save |
— | Don't save JSON |
--legacy |
— | Use pre-rewrite 5-strategy pipeline |
--ollama-url |
localhost:11434 |
Custom Ollama URL |
git log+git blame→ commit history with file attribution- Heuristic candidates from directory structure and import graph
- Claude Sonnet (or Ollama) merges/renames/splits candidates into business features via an operations-based prompt
- Per-feature health scoring with sigmoid-weighted bug-fix ratio
- Optional: Haiku detects user-facing flows per feature from signatures and commit patterns
- JSON output + terminal report
For monorepos, step 3 runs per-package in parallel (ThreadPoolExecutor, 4 workers).
| Repo size | Estimated LLM cost | Time |
|---|---|---|
| < 500 files | ~$0.01–0.05 | 15–30s |
| 500–2,000 | ~$0.10–0.30 | 1–5m |
| 2,000–5,000 | ~$0.30–0.70 | 5–12m |
| 5,000–10,000 | ~$0.70–2.00 | 10–25m |
Ollama is free (runs locally). Heuristic mode (no --llm) is free and instant.
- Engineering managers — see where technical debt actually lives, not where you think it lives
- Tech leads — prioritise refactoring with data, not gut feeling
- New team members — understand which parts of the codebase need the most care
- Sprint planning — make "should we refactor X?" a data conversation
Issues, PRs, and feedback welcome at github.com/PashaSchool/faultlines.