socraticode/skills/codebase-management/references/tool-reference.md

SocratiCode Management Tools — Full Reference

codebase_index

Start indexing a codebase in the background. Returns immediately.

Parameter	Type	Required	Default	Description
projectPath	string	no	cwd	Absolute path to the project directory
extraExtensions	string	no	—	Comma-separated additional extensions (e.g. ".tpl,.blade,.hbs"). Also via EXTRA_EXTENSIONS env var

Returns: Confirmation that indexing started, with instructions to poll codebase_status.

Key behaviours:

• Runs asynchronously — does NOT block. Returns immediately.
• Auto-starts file watcher upon completion (if not cancelled)
• Ensures Docker/Qdrant/Ollama infrastructure is running first
• Concurrency guard: if already indexing, returns current progress instead of starting again
• Auto-indexes context artifacts defined in .socraticodecontextartifacts.json
• Auto-builds code graph after indexing completes
• Batched and resumable: checkpoints after each batch of 50 files. Interruptions don't lose work.

---

codebase_update

Incrementally update an existing index. Only re-indexes changed files.

Parameter	Type	Required	Default	Description
projectPath	string	no	cwd	Absolute path to the project directory
extraExtensions	string	no	—	Comma-separated additional extensions

Returns: Statistics: files added/updated/removed, chunks created.

Key behaviours:

• Runs synchronously (blocking), unlike codebase_index
• Only processes files changed since last index (via content hash comparison)
• Auto-starts file watcher if not already active
• Usually not needed if the file watcher is running

---

codebase_remove

Remove a project's entire index from the vector database.

Parameter	Type	Required	Default	Description
projectPath	string	yes	—	Absolute path to the project directory

Returns: Confirmation of removal.

Key behaviours:

• Destructive — cannot be undone
• Safely stops file watcher (same-process and cross-process)
• Cancels in-progress indexing and drains current batch
• Waits for in-flight graph builds to finish before deletion
• May refuse if indexing batch can't drain within 5 minutes (retry after)

---

codebase_stop

Gracefully stop an in-progress indexing operation.

Parameter	Type	Required	Default	Description
projectPath	string	no	cwd	Absolute path to the project directory

Returns: Confirmation with current phase and batch info.

Key behaviours:

• Current batch finishes and checkpoints — all progress preserved
• Re-run codebase_index to resume from where it left off
• Handles both same-process and cross-process (orphan) indexing
• Sends SIGTERM to orphan processes holding the lock
• Non-destructive — progress is never lost

---

codebase_watch

Start/stop/status of live file watching.

Parameter	Type	Required	Default	Description
projectPath	string	no	cwd	Absolute path to the project directory
action	enum	yes	—	"start", "stop", or "status"

Returns: Action result or list of watched projects.

Key behaviours:

• start: Runs catch-up incremental update first, then starts debounced file watcher
• stop: Stops same-process watcher (cross-process watchers unaffected)
• status: Lists all watched projects including cross-process watchers
• Detects if another process already watches the same project
• Auto-started after successful codebase_index or codebase_update
• Debounced with ~500ms delay to batch rapid file changes

---

codebase_graph_build

Build the dependency graph using AST-based static analysis.

Parameter	Type	Required	Default	Description
projectPath	string	no	cwd	Absolute path to the project directory
extraExtensions	string	no	—	Additional extensions included as leaf nodes (dependency targets)

Returns: Confirmation that build started. Poll with codebase_graph_status.

Key behaviours:

• Runs asynchronously in background
• Auto-built during codebase_index (usually no need to call manually)
• Concurrency guard: if already building, shows progress
• Uses ast-grep for static import/require/export analysis across 18+ languages
• Skips files larger than 1 MB

---

codebase_graph_remove

Remove a project's persisted code graph.

Parameter	Type	Required	Default	Description
projectPath	string	yes	—	Absolute path to the project directory

Returns: Confirmation of removal.

Key behaviours:

• Destructive — cannot be undone
• Waits for in-flight builds before deletion
• Graph auto-rebuilds during next codebase_index

---

codebase_graph_status

Check graph build status and readiness.

Parameter	Type	Required	Default	Description
projectPath	string	no	cwd	Absolute path to the project directory

Returns: If building: phase, file progress, elapsed time. If ready: node/edge counts, last built timestamp, cache status, build duration.

---

codebase_context_index

Index or re-index all context artifacts.

Parameter	Type	Required	Default	Description
projectPath	string	no	cwd	Absolute path to the project directory

Returns: Summary: artifacts indexed with chunk counts, any errors.

Key behaviours:

• Runs synchronously (blocking)
• Usually auto-triggered by codebase_context_search on first use
• Reports individual artifact errors without stopping the whole operation

---

codebase_context_remove

Remove all indexed context artifacts.

Parameter	Type	Required	Default	Description
projectPath	string	yes	—	Absolute path to the project directory

Returns: Confirmation of removal.

Key behaviours:

• Destructive — cannot be undone
• Blocked while indexing is in progress (wait for finish or use codebase_stop)
• Removes ALL artifacts (not selective)

---

codebase_health

Check infrastructure health: Docker, Qdrant, Ollama, embedding model.

Parameter	Type	Required	Default	Description
(none)	—	—	—	No parameters

Returns: Status for each component with [OK]/[MISSING] indicators.

Key behaviours:

• Checks Docker availability
• Checks Qdrant (managed container or external endpoint)
• Checks embedding provider health (Ollama, OpenAI, or Google)
• Suggests fixes for missing components
• Works with both managed (Docker) and external (remote Qdrant) modes

---

codebase_list_projects

List all projects that have been indexed.

Parameter	Type	Required	Default	Description
(none)	—	—	—	No parameters

Returns: List with project paths, collection names, last indexed timestamp, file counts, graph info, context artifact status. Flags incomplete indexes.

---

Architectural Behaviors

Concurrency guards

• Only one indexing operation per project at a time
• Only one graph build per project at a time
• Duplicate operations return current progress instead of starting again

Checkpoint & resume

• Indexing checkpoints after each batch of 50 files
• Interrupted indexing resumes from the last checkpoint automatically
• codebase_stop preserves all progress — resume with codebase_index

Cross-process coordination

• File-based locking (proper-lockfile) prevents conflicts between multiple MCP instances
• Detects watchers/indexing running in other processes
• Can terminate orphan processes via SIGTERM
• Stale locks from crashed processes are auto-reclaimed

Auto-features

• File watcher auto-starts after indexing/updates
• Context artifacts auto-indexed on first codebase_context_search
• Stale artifacts auto-detected and re-indexed
• Code graph auto-built after indexing
• Session resume: watcher restarts on first tool use for previously indexed projects

Supported file extensions

Built-in: .js, .jsx, .ts, .tsx, .mjs, .cjs, .py, .pyw, .pyi, .java, .kt, .kts, .scala, .c, .h, .cpp, .hpp, .cc, .hh, .cxx, .cs, .go, .rs, .rb, .php, .swift, .sh, .bash, .zsh, .html, .htm, .css, .scss, .sass, .less, .vue, .svelte, .json, .yaml, .yml, .toml, .xml, .ini, .cfg, .md, .mdx, .rst, .txt, .sql, .dart, .lua, .r, .R, .dockerfile

Special files: Dockerfile, Makefile, Rakefile, Gemfile, Procfile, .env.example, .gitignore, .dockerignore

Custom: Add via extraExtensions parameter or EXTRA_EXTENSIONS env var.

Chunking defaults

• Chunk size: 100 lines, 10 lines overlap
• Batch size: 50 files per batch (for resumable checkpointing)
• Max chunk chars: 2000 (safety limit)
• Max file size: 5 MB (configurable via MAX_FILE_SIZE_MB)