Codebase Search & Intelligence using SocratiCode. Use when exploring code structure, searching concepts, finding symbol usages, inspecting impact/blast radius before refactoring, tracing execution flows, checking circular dependencies, or searching non-code context artifacts. Automatically checks index status and triggers indexing if the project is not yet indexed.
Codebase Search & Intelligence using SocratiCode. Use when exploring code structure, searching concepts, finding symbol usages, inspecting impact/blast radius before refactoring, tracing execution flows, checking circular dependencies, or searching non-code context artifacts. Automatically checks index status and triggers indexing if the project is not yet indexed.
version
1.1.0
user-invocable
true
Codebase Search & Intelligence (SocratiCode)
Always use SocratiCode MCP tools to explore codebases before reading any files directly.
Initial Prerequisites (On Any Project)
Check Index Status First (codebase_status).
Before running searches or graph queries on a project, check if it is already indexed.
Run codebase_status.
If not indexed or missing: Call codebase_index immediately to start background indexing.
Poll codebase_status until progress reaches 100% before executing codebase_search.
Building the index also automatically constructs the AST dependency graph and symbol call table.
Exploration & Analysis Workflow
Start explorations with codebase_search.
Hybrid semantic + keyword search (vector + BM25, RRF-fused) runs in a single call.
Use broad, conceptual queries for orientation: "how is authentication handled",
"database connection setup", "error handling patterns".
Use precise queries for symbol lookups: exact function names, constants, type names.
Prefer search results to infer which files to read — do not speculatively open files.
When 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 codebase_search when you're exploring, asking conceptual questions, or don't
know which files to look in.
Follow the graph before following imports.
Use 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.
Before modifying or deleting a file, check its dependents with codebase_graph_query
to understand the blast radius.
When planning a refactor, use the graph to identify all affected files before
making changes.
Use Impact Analysis BEFORE refactoring, renaming, or deleting code.
The symbol-level call graph (codebase_impact, codebase_flow, codebase_symbol,
codebase_symbols) goes one step deeper than the file graph: it knows which
functions and methods call which.
codebase_impact answers "what breaks if I change X?" (blast radius — every file
that transitively calls into the target).
codebase_flow answers "what does this code do?" by tracing forward from an entry
point. Call with no entrypoint to discover candidate entry points (auto-detected
via orphans, conventional names like main(), framework routes, tests).
codebase_symbol gives a 360° view of one function: definition, callers, callees.
codebase_symbols lists symbols in a file or searches by name.
Always prefer these over reading multiple files when the question is about
dependencies between functions, not concepts.
Read files only after narrowing down via search.
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.
Use codebase_graph_circular when debugging unexpected behaviour.
Circular dependencies cause subtle runtime issues; check for them proactively.
Also run codebase_graph_circular when you notice import-related errors or unexpected
initialisation order.
Leverage context artifacts for non-code knowledge.
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. These artifacts are auto-indexed alongside
code during codebase_index and codebase_update.
Run codebase_context early to see what artifacts are available.
Use codebase_context_search to find specific schemas, endpoints, or configs
before asking about database structure or API contracts.
If codebase_status shows artifacts are stale, run codebase_context_index to
refresh them.
Quick Tool Selection Table
Goal
Tool
Check if current project is indexed
codebase_status
Start indexing an unindexed project
codebase_index $\rightarrow$ poll codebase_status
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 if exact string
Find exact error messages, log strings, or regex patterns
grep / ripgrep
See what a file imports or what depends on it
codebase_graph_query
Check blast radius before modifying or deleting a file
codebase_impact (symbol-level) or codebase_graph_query (file-level)
