---
name: pi-shazam
description: "MUST invoke BEFORE reading, editing, searching, or understanding ANY code in a project. pi-shazam builds a codebase graph (tree-sitter AST -> symbols -> dependencies -> PageRank) with 7 tools for query, verification, and safe code modification."
---

# pi-shazam

pi-shazam is a codebase analysis toolkit with two access paths:

- **Native Extension** — for the Pi coding agent. Tools register as first-class agent tools, appearing alongside `read`/`write`/`bash`.
- **MCP Server** (`npx pi-shazam-mcp`) — for Kimi Code, CodeBuddy, Claude, Qoder, and all other MCP-compatible agents.

Both paths share the same analysis engines (tree-sitter AST parsing, symbol dependency graph, PageRank scoring, LSP diagnostics). No duplication.

## Core Rules

1. **Shazam first, grep later.** Use shazam tools instead of grep/find for code understanding.
2. **`shazam_overview` first in every unfamiliar repo.** It shows the spine of the codebase in one call.
3. **`shazam_lookup` before using any symbol.** Verify it exists and understand its signature.
4. **`shazam_impact` before multi-file edits.** Assess blast radius before you break things.
5. **`shazam_verify` after every non-trivial edit.** The evidence gate — LSP diagnostics + graph analysis.
6. **JSON mode available on all tools.** Pass `{ "json": true }` for structured output.

## Query Tools

These tools read and analyze — they never modify files.

### shazam_overview

When you first enter a project or return after changes — use this to understand the codebase before reading a single file.

**Parameters**: `{ filter?, json?, maxTokens? }`

- `filter`: optional keyword to locate specific files
- `json`: set `true` for structured output
- `maxTokens`: limit output size

**Returns**: module dependency map, top-10 PageRank files (hotspots), key dependencies (from package.json), recent git commits, entry points (auto-detected CLI/HTTP/event handlers), key data structures (classes/interfaces/structs sorted by PageRank), reading order, HTTP routes (web projects), and a "Module Density" list ranking directories by symbols-per-file ratio (#631 B). The JSON envelope adds a `topByDensity: OverviewModuleDensity[]` field. Key Dependencies, Recent Changes, and Module Density sections are suppressed in filter mode.

**When to use**: first turn in a new repo, after git clone, after switching to an unfamiliar project, deciding where to focus code review (hotspots show highest blast-radius files).

**Example**:

```
shazam_overview({})                          // full project overview with hotspots
shazam_overview({ filter: "auth" })          // locate auth-related files
```

### shazam_lookup

Unified symbol and file lookup. Combines symbol definition, type signature, documentation, file structure analysis, and type hierarchy into a single tool.

**Parameters**: `{ name: string, file?, mode?, showCallbacks?, direction?, json?, maxTokens? }`

- `name`: symbol name to look up, or a file path to analyze file structure
- `file`: optional file path to scope the symbol search
- `mode`: `"search"` for fuzzy concept search (e.g., "how does authentication work"); if omitted and the symbol is not found, automatically falls back to search when the query looks like natural language
- `showCallbacks`: expand anonymous functions in call graph
- `direction`: type hierarchy traversal — `"both"` (default), `"supertypes"`, or `"subtypes"`

**Returns**: When `name` is a symbol: definition, kind, signature, file location, PageRank score, callers, callees, type signatures, documentation comments, and type hierarchy. The JSON envelope attaches a `provenanceCounts` summary (resolved | name_match | heuristic | unresolved counts across incoming+outgoing edges) and sorts matches by provenance weight so the most-trustworthy symbols come first (#631 B). When `name` is a file path: all symbols in the file with signatures, visibility, line ranges, incoming call count, PageRank score, and document symbol hierarchy.

**When to use**: before importing a module, before calling a function, checking symbol visibility, understanding a symbol's type signature, getting API documentation, before editing a file for the first time (pass file path), understanding class inheritance (`direction` param), finding all interface implementations, searching for a concept across the codebase (`mode=search` or natural language query like "how is X implemented").

**Examples**:

```
shazam_lookup({ name: "createTool" })                        // symbol lookup
shazam_lookup({ name: "createTool", file: "tools/_factory.ts" })  // scoped to file
shazam_lookup({ name: "src/core/graph.ts" })                 // file structure
shazam_lookup({ name: "ExtensionAPI", direction: "subtypes" }) // type hierarchy
shazam_lookup({ name: "authentication", mode: "search" })       // concept search
shazam_lookup({ name: "how does caching work" })                 // natural language auto-search
```

### shazam_impact

Required before editing 2+ files or any shared/exported module. Also performs call chain analysis when a symbol is specified.

**Parameters**: `{ files?, symbol?, withSymbols?, compact?, depth?, flat?, direction?, json?, maxTokens? }`

- `files`: list of file paths you plan to edit (for file-level impact analysis)
- `symbol`: symbol name for call chain analysis (traces callers and callees)
- `withSymbols`: per-symbol risk breakdown
- `compact`: file names only, no detail
- `depth`: call chain traversal depth (default 3)
- `flat`: return simple flat list of all references
- `direction`: call chain direction — `"incoming"`, `"outgoing"`, or `"both"` (default)

**Returns**: When `files` is provided: every file, symbol, and test affected by your planned changes. The JSON envelope includes a `provenanceCounts` summary on every affected symbol so consumers can tell LSP-resolved callers apart from tree-sitter-heuristic ones (#631 B); the markdown output adds a compact `R:N H:M` badge to the affected-file line. When `symbol` is provided: incoming calls, outgoing calls, and full reference list for the symbol. The call-chain JSON entries also carry a per-edge `provenance` field and a `mermaid` string with a `flowchart TD` block (LLM-embeddable Mermaid call graph, capped at 30 nodes).

**When to use**: refactoring, adding a parameter to a shared function, changing a type definition, before any PR touching >1 file. Use `--symbol` when changing parameter order, removing a function, renaming an exported symbol, or changing return type.

**Examples**:

```
shazam_impact({ files: ["core/graph.ts", "tools/impact.ts"] })   // file impact
shazam_impact({ symbol: "createTool" })                           // call chain
shazam_impact({ symbol: "scanProject", depth: 4, direction: "incoming" })  // who calls scanProject
shazam_impact({ files: ["core/graph.ts"], withSymbols: true })    // symbol-level detail
```

## Write & Verification Tools

These tools modify files or verify changes.

### shazam_verify

After every write or edit, run this to confirm no errors were introduced. When diagnostics are found, fetches LSP codeAction suggested fixes.

**Parameters**: `{ quick?, lspOnly?, preCommit?, json?, maxTokens? }`

- `quick`: git changes + risk only (~2s)
- `lspOnly`: LSP diagnostics only, skip graph analysis
- `preCommit`: stricter thresholds for pre-commit gate
- `maxFiles` is no longer a per-call flag (#630). Configure it in `.pi-shazam/config.json` under `verify.maxFiles` (default 100). The dispatcher reads the config and merges it into the VerifyOptions.

**Returns**: Verdict (PASS / WARN / FAIL), LSP diagnostics with suggested fixes, risk level, orphan detection, graph diffs.

**When to use**: after every non-trivial edit, before git commit, when CI is red.

**Example**:

```
shazam_verify({})                   // full verification
shazam_verify({ quick: true })      // fast git-change-only check
shazam_verify({ preCommit: true })  // strict pre-commit gate
```

### shazam_format

When code needs formatting, use this to auto-fix format and lint issues. Runs the nearest-wins formatter (prettier, biome, eslint --fix, ruff, cargo fmt, gofmt).

**Parameters**: `{ dryRun?, file?, json?, maxTokens? }`

- `dryRun`: preview changes without applying (default `true`)
- `file`: scope to a single file

**Returns**: list of fixes applied or previewed.

**When to use**: after shazam_verify reports format/lint errors, trailing whitespace, import sorting, indentation, line length, mixed tabs/spaces, missing newlines.

**Example**:

```
shazam_format({ dryRun: true })              // preview all fixes
shazam_format({ dryRun: false, file: "src/core/graph.ts" })  // apply to one file
```

### shazam_rename_symbol

Required safety gate before renaming any symbol. This is a WRITE operation — it performs the project-wide rename via LSP textDocument/rename.

**Parameters**: `{ symbol: string, newName: string, dryRun?, json?, maxTokens? }`

- `symbol`: current symbol name
- `newName`: new symbol name
- `dryRun`: preview only, do not modify files

**Safety workflow**: use `shazam_impact --symbol` first to review all references, then rename, then verify with `shazam_verify`.

**When to use**: renaming a public API function, renaming a widely-used type, changing a class name.

**Example**:

```
shazam_rename_symbol({ symbol: "oldName", newName: "newName", dryRun: true })  // preview
shazam_rename_symbol({ symbol: "oldName", newName: "newName" })                // execute
```

## Git Tools

### shazam_changes

Git change summary with risk level. Shows what changed in the working tree and assesses the risk of each change.

**Parameters**: `{ json?, maxTokens? }`

- No required parameters — uses the project root automatically.

**Returns**: list of changed files, risk assessment, orphan symbol summary, and summary of changes. The JSON envelope adds a `structuralChanges: { added, removed, modified }` field tallying line counts from `git diff --numstat` (#631 B); the markdown output adds a compact `(+N -M lines across K files)` badge under the file list.

**When to use**: before creating a commit, reviewing what you are about to push, understanding the scope of uncommitted changes.

**Example**:

```
shazam_changes({})
```

## LSP Integration

pi-shazam auto-detects language servers for supported languages:

| Language              | Server                      | Auto-Detect |
| --------------------- | --------------------------- | ----------- |
| TypeScript/JavaScript | typescript-language-server  | yes         |
| Python                | pyright                     | yes         |
| Rust                  | rust-analyzer               | yes         |
| Go                    | gopls                       | yes         |
| JSON                  | vscode-json-language-server | yes         |
| YAML                  | yaml-language-server        | yes         |
| Dart                  | dart                        | yes         |

When a language server is unavailable, tools fall back to tree-sitter only and annotate output with `(tree-sitter only, LSP unavailable)`.

Run `/shazam-doctor` for a full health check including LSP status and recent diagnostics.

## JSON Output Envelope

All tools support `{ "json": true }` for structured output:

```json
{
	"schema_version": "1.0",
	"command": "<tool_name>",
	"project": "<absolute_path>",
	"status": "ok",
	"result": {}
}
```

## Configuration

Optional project config file at `.pi-shazam/config.json` (relative to the project root). Missing file = silent defaults; malformed JSON = a single warning, then defaults. Cached on first read — restart the extension to pick up edits.

Currently consumed fields:

- `verify.maxFiles` — max files passed to the LSP server for diagnostics in a single `shazam_verify` call (default 100). Must be a positive integer.

Example:

```json
{
	"verify": {
		"maxFiles": 50
	}
}
```

## Encoding

pi-shazam reads source files with adaptive encoding: UTF-8 -> GBK -> GB2312. It never assumes UTF-8.

## Environment

- **Runtime**: Node.js >=18, TypeScript ES2022, ESM
- **Grammar support**: 14 file extensions across 8 tree-sitter grammars (Python, TypeScript/TSX, JavaScript, Go, Rust, Dart, JSON)
- **LSP**: 7 languages with auto-spawned language servers (Python, TypeScript/JavaScript, Go, Rust, Dart, JSON, YAML)
- **Install**: `npm install pi-shazam` in Pi extensions directory