## Code Intelligence (multi-agent-toolkit `code_*`)

Compiler-grade answers about Swift and Kotlin source, from the language server
each platform already ships. Eight tools in the companion MCP server
(`@mmerterden/multi-agent-toolkit-mcp` 3.10.0 and later), all read-only except
`code_server_reset`.

### What it is for, and what `code-graph.md` already covers

These two answer different questions and neither replaces the other.

| Question | Use |
|---|---|
| Where does this concept live in a repo I do not know | `code-graph.md` - one cheap pass over the whole tree, token-budgeted |
| What depends on this area, roughly | `graph-affected` |
| Is THIS exact symbol referenced, and where | `mcp__multi-agent-toolkit__code_references` |
| What type is this, really | `mcp__multi-agent-toolkit__code_hover` |
| Does this file compile, without a full build | `mcp__multi-agent-toolkit__code_diagnostics` |

`docs/adr/0010-own-code-graph.md` states the trade the graph makes in as many
words: *"Regex over comment-stripped source is not a parser. Definitions and
imports survive that trade; call graphs and type resolution do not."* It names
two consequences - a name declared in two files is dropped rather than fanned
out, so `affected` under-reports on duplicated names, and only type-like symbols
are reference targets. Those are exactly the two the language server answers
exactly. So the graph stays the wide, cheap first pass, and `code_*` is what a
specific claim is checked against.

### The one thing to know before trusting an answer

An empty result is not the same as a negative result, and on a cold repository
it is the likelier of the two. Measured on Swift 6.3.1 against a two-file
package: the same `references` query answered 0 at 0.7s and 3 at 5.8s, with
nothing changed except that the background index had finished. On a 658-file
package with dependencies the first index had not finished at 70s.

Every index-backed result therefore carries `indexReady`, and the tools wait for
the index rather than answering early. When `indexReady` is false, an empty list
means "not indexed yet". Never report it as "unused".

`code_index_status` answers whether this machine can answer at all, and it
succeeds even when nothing is installed - it is the tool to run first on an
unfamiliar machine.

### Root decides what an answer is worth

`semantic` and `buildSettingsSource` come back on every result.

| Root | definition | references | diagnostics |
|---|---|---|---|
| `Package.swift` | yes | yes, after the index settles | yes |
| `buildServer.json` | yes | yes | yes |
| `.xcodeproj`, no build server | same-file only | no, `semantic: false` | misleading, marked non-semantic |

A modular app is mostly packages, so this matters less than it reads: the iOS
app measured here has 41 `Package.swift` roots and a single `.swift` file under
the umbrella project.

### Where a run uses them

All three are opt-in and none is on by default.

1. **Phase 4, checking a citation's claim.** `verify-citations.mjs` already
   proves a cited `file:line` exists. `code_hover` at that position proves the
   line holds what the finding says it holds, and `code_references` falsifies a
   "nothing handles this" claim.
2. **Phase 1, sharpening an impact estimate.** When `graph-affected` reports on
   a name that the graph itself flagged as ambiguous, `code_references` on the
   one symbol the task names resolves it exactly.
3. **Phase 3, fast feedback.** `code_diagnostics` on the file just edited,
   without waiting for `xcodebuild`.

### Kotlin

Runs on JetBrains `kotlin-lsp`: Alpha, partially closed source, Android Gradle
Plugin support experimental, and installed separately
(`brew tap JetBrains/utils && brew install kotlin-lsp`, JVM 17+). Answers carry
`confidence: "alpha"`, and the toolkit's own README states that no gate in that
repository exercises the Kotlin server. Treat Kotlin answers as a lead, not as
evidence, until that changes.