socraticode/AGENTS.md

Codebase Search (SocratiCode)

This project is indexed with SocratiCode. Always use its MCP tools to explore the codebase before reading any files directly.

Workflow

1. Start most 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.

2. 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.

3. 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.

4. 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.

5. 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.

6. Check codebase_status if search returns no results. The project may not be indexed yet. Run codebase_index if needed, then wait for codebase_status to confirm completion before searching.

7. 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.

When to use each tool

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 if you know already the 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)
What breaks if I change function X?	codebase_impact target=X
What does this entry point actually do?	codebase_flow entrypoint=X
List entry points in this codebase	codebase_flow (no args)
Who calls this function and what does it call?	codebase_symbol name=X
What functions/classes exist in this file?	codebase_symbols file=path
Search for symbols by name across the project	codebase_symbols query=X
Spot architectural problems	codebase_graph_circular, codebase_graph_stats
Visualise module structure (text / Mermaid)	codebase_graph_visualize
User asks for a visual / interactive / shareable graph	codebase_graph_visualize mode="interactive" — opens a self-contained HTML page with file + symbol views, blast-radius overlay, search, PNG export. Works offline (vendored Cytoscape).
Verify index is up to date	codebase_status
Discover what project knowledge (schemas, specs, configs) is available	codebase_context
Find database tables, API endpoints, infra configs	codebase_context_search

Why semantic 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. Once you know which files matter, targeted reading is both faster and more accurate. That said, grep remains the right tool when you have an exact string or pattern — use whichever fits the query.

Keep the connection alive during indexing. Indexing runs in the background — the MCP server continues working even when not actively responding to tool calls. However, some MCP hosts (VS Code, Claude Desktop, etc.) will disconnect an idle MCP connection after a period of inactivity, which cuts off the background process. Instruct your AI to call codebase_status roughly every 60 seconds after starting codebase_index until it completes. This keeps the host connection active and provides real-time progress.