Coding agents

dowsing is designed with coding agents as its primary consumer. The agent-facing interface came before the human-facing tables and reports, not after.

Why agents first

When CodeScene was designed, the assumption was that a tech lead reads a dashboard. Today an agent like Claude Code decides what to refactor and then does it.

An agent does not need a warning that says "this file is complex". It needs a justified priority order. dowsing returns exactly that, as structured data.

There is no MCP server

dowsing shipped one in Phase 1 and removed it on 2026-07-31. Every tool it exposed was one-to-one with a CLI subcommand, and an agent can already run a CLI. Keeping both meant maintaining two surfaces for the same thing, while MCP tool definitions sit in the context window for a tool used once or twice per session.

What is left is smaller and reaches further:

dowsing --help

That output is the source of truth: the command list and options, followed by the things a command table cannot express — what dowsing needs from your repository, the shape of its output, exit codes, and how caching behaves. There is no separate --agent-help; an agent reaches for --help anyway, and a second flag would only duplicate the command list and drift from it.

Every command takes --json, so an agent reads data rather than formatted tables.

Install the Agent Skill

The CLI works by itself. The optional Agent Skill lets a compatible agent discover when to reach for dowsing, and — more importantly — how to read what comes back.

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

Replace claude-code with your host: codex, cursor, github-copilot, opencode, cline, kiro-cli, or windsurf. To have an agent install it for you, point it at install-agent.md.

The skill deliberately contains no flags — those live in --help, so the skill cannot go stale when the CLI changes. What it does carry is interpretation:

• Do not propose a file whose score is 0, however complex it is — nobody touches it, so there is no return
• Always confirm hidden coupling with dowsing why — duplicated code and a deliberate protocol look identical in the numbers
• Do not take churn at face value — a low effectiveRatio means renames inflated it
• Always present health with its breakdown — "health 4.9" alone is not actionable
• Frame bus factor as risk, not as a judgement of a person

Tell the repository, not just your host

A Skill is installed per host, so it only reaches agents belonging to whoever installed it. A line in AGENTS.md travels with the repository instead — every agent that works in it reads that file, whatever the host, including one that has never heard of dowsing.

npx dowsing init            # appends a dowsing section to AGENTS.md
npx dowsing init --dry-run  # see what it would write first

Running it again updates that section instead of adding a second one.

What every result carries

Analysis output includes the conditions the analysis ran under.

{
  "meta": {
    "git": {
      "since": "12 months ago",
      "commitCount": 3920,
      "exclusions": { "merges": 6, "bots": 0, "formatOnly": 1 },
      "shallow": false
    }
  },
  "config": { "complexity": "loc" }
}

This exists so that an agent does not report "it was changed 255 times" but "255 times in the last 12 months, excluding merges and bots".

Repeated calls are cheap

The first analysis of a large repository takes a few seconds. The result is cached under .dowsing/cache, keyed by HEAD, working-tree state, and the analysis options — so hotspots, then coupling, then why in the same session answer instantly.

A cache hit is announced on stderr rather than passed off as a fresh run. After a large change, pass --refresh.

dowsing does not edit your code

Fixing is the agent's job; dowsing points at where to look and then measures whether it worked.

dowsing diff origin/main

That re-measures every changed file at both revisions and reports how complexity actually moved. It does not care who made the change, so it works for a human commit, an agent's refactor, or a PR in CI — and it reports a regression as plainly as an improvement.