dowsing

Behavioral code analysis for TypeScript monorepos. It crosses your git history with your code structure and points at the few places worth your time.

Full documentation: https://dowsing.yhay81.com

Thirty seconds

npx dowsing analyze

Run it in a TypeScript monorepo with git history. You get a hotspot ranking, per-package risk, and hidden coupling. There is nothing to configure.

⚠ Top hotspots (complexity=loc):
┌───┬────────────────────────────────┬───────┬────────┬────────┬─────────┐
│ # │ file                           │ score │   freq │     cx │ commits │
├───┼────────────────────────────────┼───────┼────────┼────────┼─────────┤
│ 1 │ services/api/src/runtime.ts    │ 0.999 │ 100pct │ 100pct │     255 │
│ 2 │ services/api/tests/db/…test.ts │ 0.997 │ 100pct │ 100pct │     128 │
└───┴────────────────────────────────┴───────┴────────┴────────┴─────────┘

🔗 Hidden coupling — packages that change together with no dependency (1):
│ @acme/admin-web │ @acme/customer-web │ 33% │ 91 │ hidden ⚠ │

What it does that a linter does not

• Assumes you can't fix everything. Only code that is both changed often and complex gets ranked. Complex code nobody touches is left alone — fixing it pays nothing.
• Treats package boundaries as first-class. It reads pnpm / bun / npm / yarn workspaces and Turborepo / Nx / Vite+ directly, which is how it finds packages that always change together while having no dependency between them.
• Publishes every formula. A Code Health score breaks down to which smell cost how many points. Thresholds and weights are labelled as the hypotheses they are.
• Verifies that change frequency is real. A git line diff cannot tell whether meaning changed; dowsing compares the AST of each revision to separate real edits from renames, reformatting, and comment-only churn.
• Measures whether a fix actually helped. dowsing diff re-measures both revisions and reports how complexity actually moved — no matter who made the change.

Commands

| Command | What it does | | --------------------- | --------------------------------------------------------------------- | | dowsing analyze | Analyse the workspace, write .dowsing/dowsing.json, print a summary | | dowsing hotspots | The hotspot ranking on its own | | dowsing coupling | Change coupling (--hidden for pairs with no dependency) | | dowsing why <a> <b> | Why two packages change together | | dowsing health | Code Health, with the deductions that produced it | | dowsing knowledge | Ownership and bus factor, per package | | dowsing report | A single self-contained HTML report | | dowsing check | CI quality gate — non-zero exit on threshold violations | | dowsing diff <base> | Risk of what a PR touches, plus the complexity delta it caused |

Every option is listed in the CLI reference.

For coding agents

dowsing does not edit your code. It tells an agent where to look, and measures whether the change helped. There is no MCP server: an agent can already run a CLI, and the interface is one command away.

dowsing --help

That output is the source of truth for commands, options, output shapes, and exit codes. The optional Agent Skill adds what --help cannot: how to read the numbers, and what not to claim from them.

gh skill install yhay81/dowsing dowsing --agent claude-code --scope user

See Coding agents.

Requirements

Node.js ^22.18.0 || >=24.11.0, a git repository with real history (fetch-depth: 0 in CI), and TypeScript / TSX sources. Results are cached in .dowsing/cache, keyed by HEAD, working-tree state, and options.

License

MIT