SocratiCode Codebase Exploration

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.

Workflow

1. Start most explorations with codebase_search

Hybrid semantic + keyword search (vector + BM25, RRF-fused) runs in a single call.

• Broad queries for orientation: "how is authentication handled", "database connection setup", "error handling patterns"
• Precise queries for symbol lookup: exact function names, constants, type names
• Prefer search results to infer which files to read — do not speculatively open files
• Use fileFilter to narrow to a specific file path, languageFilter for a specific language
• Adjust minScore (default 0.10) for precision vs recall — lower for more results, higher for stricter matching

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 exploring, asking conceptual questions, or when you 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.

• 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 breakdown
• codebase_graph_circular — find circular dependencies (these cause subtle runtime bugs; check proactively when debugging unexpected behaviour)
• codebase_graph_visualize — Mermaid diagram colour-coded by language, circular deps highlighted in red. Pass mode: "interactive" to open a self-contained HTML explorer (file + symbol views, blast-radius overlay, search, PNG export — works offline) instead.

The graph is auto-built after indexing. Use codebase_graph_status to check if the graph is ready.

3. Read files only after narrowing 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.

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.

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

• codebase_context — list available artifacts (names, descriptions, paths, index status)
• codebase_context_search — semantic search across all artifacts (or filter with artifactName)
• Artifacts are auto-indexed on first search and auto-detect staleness

Run codebase_context early to see what's available. Use codebase_context_search before asking about database structure, API contracts, or infrastructure.

5. Check status if something seems wrong

• codebase_status — check index status, progress, watcher state, graph status
• If search returns no results, the project may not be indexed yet
• If the watcher is inactive, results may be stale — run codebase_update or start the watcher

6. Get an overview of all tools

• codebase_about — quick reference of all SocratiCode tools and a typical workflow

Goal → Tool Quick Reference

For full parameter details on every tool, see references/tool-reference.md.

SocratiCode Management

Set up, index, and manage SocratiCode codebase indexing, file watching, code graphs, and context artifacts.

First-Time Setup

1. Check infrastructure: codebase_health — verifies Docker, Qdrant, Ollama/embedding provider, and embedding model
2. Start indexing: codebase_index — runs in background, returns immediately
3. Poll progress: codebase_status — call every ~60 seconds until 100% complete
   • This also keeps the MCP connection alive (some hosts disconnect idle connections)
4. Done: Graph auto-builds after indexing. File watcher auto-starts. Ready to search.

On first use, SocratiCode automatically pulls Docker images, starts containers, and downloads the embedding model (~5 min one-time setup).

Incremental Updates & File Watching

The file watcher keeps the index automatically updated. It auto-starts after indexing.

• codebase_watch { action: "start" } — start the watcher (runs catch-up update first)
• codebase_watch { action: "stop" } — stop the watcher
• codebase_watch { action: "status" } — list watched projects (including cross-process)
• codebase_update — manual incremental update (only changed files, synchronous). Usually not needed if watcher is active.

Managing Indexes

• codebase_stop — gracefully pause in-progress indexing. Current batch finishes and checkpoints. All progress preserved. Resume with codebase_index.
• codebase_remove — delete entire index (destructive). Safely stops watcher, cancels indexing, waits for graph builds.
• codebase_list_projects — list all indexed projects with metadata, graph info, and artifact status.

Managing the Code Graph

The dependency graph is auto-built after indexing. Manual management is rarely needed.

• codebase_graph_build — manually rebuild (background, async). Poll with codebase_graph_status.
• codebase_graph_remove — delete graph (auto-rebuilds on next codebase_index)
• codebase_graph_status — check build progress or graph readiness

Context Artifacts Setup

To index non-code knowledge, create .socraticodecontextartifacts.json in the project root:

{
  "artifacts": [
    {
      "name": "database-schema",
      "path": "./docs/schema.sql",
      "description": "PostgreSQL schema — all tables, indexes, constraints, foreign keys."
    }
  ]
}

Supported types: SQL schemas, OpenAPI/Protobuf API specs, Terraform/CloudFormation configs, Kubernetes manifests, architecture docs, environment configs — any text-based file or directory.

• codebase_context_index — manually index/re-index all artifacts (usually auto-triggered)
• codebase_context_remove — remove all indexed artifacts (blocked during indexing)

Troubleshooting

Key Environment Variables

For full parameter details on every tool, see references/tool-reference.md.