Explore and understand codebases using SocratiCode semantic search, dependency graphs, and context artifacts. Use when exploring code, understanding architecture, finding functions/types, analyzing dependencies, searching database schemas or API specs, or when socraticode/codebase_search tools are available. Activates when the user asks about code structure, wants to find where a feature lives, or needs to understand how code is organized.
Use SocratiCode MCP tools to explore codebases efficiently. The core principle: search before reading — the index gives you a map of the codebase in milliseconds; raw file reading is expensive and context-consuming.
codebase_searchHybrid semantic + keyword search (vector + BM25, RRF-fused) runs in a single call.
fileFilter to narrow to a specific file path, languageFilter for a specific languageminScore (default 0.10) for precision vs recall — lower for more results, higher for stricter matchingWhen to use grep instead: If you already know the exact identifier, error string, or regex pattern, grep/ripgrep is faster and more precise — no semantic gap to bridge. Use when exploring, asking conceptual questions, or when you don't know which files to look in.
codebase_searchUse codebase_graph_query to see what a file imports and what depends on it before diving into its contents. This prevents unnecessary reading of transitive dependencies.
codebase_graph_query — imports and dependents for any file (pass relative path)codebase_graph_stats — architecture overview: total files, edges, most connected files, orphans, language breakdowncodebase_graph_circular — find circular dependencies (these cause subtle runtime bugs; check proactively when debugging unexpected behavior)codebase_graph_visualize — Mermaid diagram color-coded by language, circular deps highlighted in redThe graph is auto-built after indexing. Use codebase_graph_status to check if the graph is ready.
Once search results clearly point to 1-3 files, read only the relevant sections. Never read a file just to find out if it's relevant — search first.
A single codebase_search call returns ranked, deduplicated snippets from across the entire codebase in milliseconds. This gives you a broad map at negligible token cost — far cheaper than opening files speculatively.
Projects can define a .socraticodecontextartifacts.json config to expose database schemas, API specs, infrastructure configs, architecture docs, and other project knowledge that lives outside source code.
codebase_context — list available artifacts (names, descriptions, paths, index status)codebase_context_search — semantic search across all artifacts (or filter with artifactName)Run codebase_context early to see what's available. Use codebase_context_search before asking about database structure, API contracts, or infrastructure.
codebase_status — check index status, progress, watcher state, graph statuscodebase_update or start the watchercodebase_about — quick reference of all SocratiCode tools and a typical workflow| Goal | Tool |
|---|---|
| Understand what a codebase does / where a feature lives | codebase_search (broad query) |
| Find a specific function, constant, or type | codebase_search (exact name) or grep |
| Find exact error messages, log strings, or regex patterns | grep / ripgrep |
| See what a file imports or what depends on it | codebase_graph_query |
| Get architecture overview (files, edges, most connected) | codebase_graph_stats |
| Spot circular dependencies | codebase_graph_circular |
| Visualize module structure | codebase_graph_visualize |
| Check graph build status | codebase_graph_status |
| Verify index is up to date | codebase_status |
| Discover available schemas, specs, configs | codebase_context |
| Find database tables, API endpoints, infra configs | codebase_context_search |
| Quick overview of all tools | codebase_about |
For full parameter details on every tool, see references/tool-reference.md.