socraticode/CLAUDE.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.

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

4. Use codebase_graph_circular when debugging unexpected behavior. Circular dependencies cause subtle runtime issues; check for them proactively.

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

6. 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
Spot architectural problems	codebase_graph_circular, codebase_graph_stats
Visualise module structure	codebase_graph_visualize
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.