socraticode/skills/codebase-exploration/references/tool-reference.md

# SocratiCode Exploration Tools — Full Reference

## codebase_search

Semantic search across an indexed codebase. Only use after `codebase_index` is complete.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | string | yes | — | Natural language search query (e.g. "authentication middleware", "database connection setup") |
| `projectPath` | string | no | cwd | Absolute path to the project directory |
| `limit` | number (1-50) | no | 10 | Maximum results. Override globally via `SEARCH_DEFAULT_LIMIT` env var |
| `fileFilter` | string | no | — | Filter results to a specific file path (relative) |
| `languageFilter` | string | no | — | Filter results to a specific language (e.g. "typescript", "python") |
| `minScore` | number (0-1) | no | 0.10 | Minimum RRF score threshold. Override via `SEARCH_MIN_SCORE`. Set to 0 to disable |

**Returns:** Ranked code chunks with file paths, line numbers, language, and RRF scores.

**Key behaviours:**
- Uses hybrid semantic + keyword (BM25) search with Reciprocal Rank Fusion
- Warns if indexing is in progress (results will be incomplete during full index)
- Warns if file watcher is not active (results may be stale)
- Results below `minScore` are filtered out with a count of omitted results

---

## codebase_status

Check index status: chunk count, indexing progress, last completed operation, file watcher state.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `projectPath` | string | no | cwd | Absolute path to the project directory |

**Returns:** Detailed status including:
- Collection name and indexed chunk count
- In-progress indexing: phase, file/chunk progress percentage, batch info, elapsed time
- Last completed operation: type, files processed, chunks created, duration
- Incomplete index detection (previous run interrupted)
- Cross-process indexing detection (another process actively indexing)
- File watcher status (active / watched by another process / inactive)
- Code graph status (files, edges, last built, cached in memory)
- Context artifacts status

**Key behaviours:**
- Call every ~60 seconds during indexing to poll progress AND keep the MCP connection alive
- Detects both same-process and cross-process indexing

---

## codebase_graph_query

Query the dependency graph for a specific file.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `projectPath` | string | no | cwd | Absolute path to the project directory |
| `filePath` | string | yes | — | Relative path of the file to query (e.g. "src/index.ts") |

**Returns:** Two lists: what this file imports (→) and what depends on it (←).

**Key behaviours:**
- Requires graph to exist (auto-built after indexing, or use `codebase_graph_build`)
- Auto-starts file watcher on query
- Use relative paths (not absolute)

---

## codebase_graph_stats

Get statistics about the code dependency graph.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `projectPath` | string | no | cwd | Absolute path to the project directory |

**Returns:** Total files, edges, average dependencies per file, circular dependency count, language breakdown, top 10 most connected files, first 20 orphan files.

---

## codebase_graph_circular

Find circular dependencies in the codebase.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `projectPath` | string | no | cwd | Absolute path to the project directory |

**Returns:** List of circular dependency chains (up to 20, with total count).

**Key behaviours:**
- Detects transitive circular dependencies
- Useful for debugging subtle runtime issues caused by import cycles

---

## codebase_graph_visualize

Visualise the dependency graph. Two modes:

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `projectPath` | string | no | cwd | Absolute path to the project directory |
| `mode` | `"mermaid" \| "interactive"` | no | `"mermaid"` | Output format |
| `open` | boolean | no | `true` | In interactive mode, auto-open the browser |

**mode="mermaid"** (default) — returns a Mermaid flowchart code block. Nodes colour-coded by language, circular dependency edges highlighted in red. Renders inline in markdown viewers, VS Code, GitHub.

**mode="interactive"** — generates a self-contained HTML page (vendored Cytoscape.js + Dagre, works offline) written to the OS temp dir and opened in the user's default browser.
- File view and (when available) Symbol view toggle
- Click a node → sidebar with imports / dependents / symbols / line numbers
- Right-click → blast radius overlay (reverse-transitive closure)
- Live search, six layouts, PNG export
- Shareable file — commit to a PR or attach to chat

**Key behaviours:**
- Interactive mode always includes the file view; the symbol view toggle is available when the symbol graph fits under embed caps (≤ 20k symbols / ≤ 60k call edges). Above that cap, the HTML still works — use `codebase_impact` / `codebase_symbols` for symbol-level queries.
- Browser auto-open is best-effort. If it fails (headless environments, blocked browsers) the tool output still includes the file path.
- Choose this mode when the user asks for a visual, interactive, or shareable graph.

---

## codebase_graph_status

Check graph build status and progress.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `projectPath` | string | no | cwd | Absolute path to the project directory |

**Returns:** If building: phase, file progress, elapsed time. If ready: node/edge counts, last built timestamp, cache status, last build duration.

**Key behaviours:**
- Use to poll progress after `codebase_graph_build`
- Shows build errors if last build failed

---

## codebase_context

List all context artifacts defined in `.socraticodecontextartifacts.json`.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `projectPath` | string | no | cwd | Absolute path to the project directory |

**Returns:** Each artifact's name, description, path, and index status (chunk count, last indexed timestamp, or "not yet indexed"). If no config exists, provides a template.

---

## codebase_context_search

Semantic search across context artifacts.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | string | yes | — | Natural language query (e.g. "tables related to billing", "authentication endpoints") |
| `projectPath` | string | no | cwd | Absolute path to the project directory |
| `artifactName` | string | no | — | Filter to a specific artifact by name. Omit to search all |
| `limit` | number (1-50) | no | 10 | Maximum results |
| `minScore` | number (0-1) | no | 0.10 | Minimum RRF score threshold |

**Returns:** Artifact content chunks with artifact name, file path, line ranges, and scores.

**Key behaviours:**
- Auto-indexes artifacts on first use (no manual step needed)
- Auto-detects stale artifacts and re-indexes changed ones
- Works with any text-based artifact: SQL, OpenAPI, Terraform, K8s, YAML, markdown, etc.

---

## codebase_about

Display information about SocratiCode and all its tools.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| (none) | — | — | — | No parameters |

**Returns:** Tool summary by category, typical workflow, infrastructure status, version info.

---

## Tips

### Search tips
- A single `codebase_search` returns ranked snippets from the entire codebase in milliseconds — far cheaper than opening files speculatively
- The RRF score combines semantic similarity and keyword match; higher scores = better relevance
- Use `fileFilter` when you know the area, `languageFilter` when cross-language results are noisy
- Lower `minScore` to 0 when exploring broadly; raise it for precision

### Graph tips
- The graph is auto-built after `codebase_index` — usually no need to call `codebase_graph_build` manually
- `codebase_graph_visualize` generates Mermaid that renders in GitHub, VS Code, and most markdown viewers
- Check `codebase_graph_circular` when debugging mysterious behaviour — circular deps cause subtle issues

### Context artifact tips
- `codebase_context_search` auto-indexes on first use — just search, no setup needed
- Stale artifacts are auto-detected and re-indexed when content changes
- Use `artifactName` filter to target specific schemas or specs
- Supported types: SQL schemas, OpenAPI/Protobuf specs, Terraform configs, K8s manifests, architecture docs, env configs — any text-based file