---
name: structural-nav
description: Choose readseek MCP tools or passive Read/Grep/Write hooks and Edit drift guards for structural navigation. Avoid duplicate calls.
---

# Structural navigation with readseek

Use MCP tools for intentional structural navigation. Let hooks enrich native
operations that are already needed. Do not call an MCP tool only to reproduce
context a hook just supplied.

## Choose the operation

| Need | Use |
| --- | --- |
| Locate a symbol declaration | `def` |
| Find identifier usages | `refs` |
| Identify the token or enclosing symbol at a cursor | `hover` |
| Search an AST pattern such as `console.log($$$ARGS)` | `search` |
| Show a file's symbol outline | `map` |
| Check parser errors or missing syntax | `check` |
| Read implementation text | Native `Read`; its hook may append an outline |
| Search literal text or regex | Native `Grep`; its hook may group matches by symbol |

Claude Code scopes these names under the plugin's `readseek` MCP server.

## Active MCP workflow

- Use `hover` before `def` or binding-specific `refs` when a cursor identifies
  the target more reliably than a guessed name.
- Pass `hover`'s qualified name to `def` when available.
- Use `refs` with `scope`, `line`, and optional `column` for one binding. Omit
  `scope` only when same-named bindings are acceptable.
- Use `search` for AST patterns and native `Grep` for plain text.
- Use `map` when only names, kinds, ranges, and anchors are needed; use native
  `Read` for implementation text.
- After `Edit`, use `check` when a quick syntax check is useful. The Edit hook
  only re-anchors and does not run `check`.
- After `Write`, wait for the Write hook's diagnostics instead of repeating
  `check`.

## Passive hook behavior

Wait for hooks when the native operation was already necessary:

- `Read` may append `## Structure (via readseek)` for a non-trivial file.
- `Grep` or a supported Bash search may group matches by their innermost symbol
  or outline files from filename-only results.
- `Edit` may reject stale anchors and require a fresh read.
- `Write` records the new anchor and runs `readseek check`. Empty output means a
  clean parse (or a no-op), not a failed check.

Call an MCP tool after a hook only when it answers a different question or the
hook context is insufficient. If the binary is still installing, continue with
native tools instead of retrying the same MCP call.