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)

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