SocratiCode

The Problem

Developers need instant, accurate context about huge codebases (tens of millions of lines) without manually curating docs or running heavyweight indexing pipelines. Existing “AI‑grep” tools require large token budgets, many API calls, and fragile setup, which slows down debugging, onboarding, and AI‑assisted development.

What This Does

SocratiCode installs a local indexing service that watches a repository, builds polyglot dependency graphs, and serves a hybrid semantic‑plus‑structural search API. The core runtime lives under src/ – e.g. src/services/qdrant.ts (vector store wrapper), src/services/indexer.ts (checkpointed indexing), and src/services/docker.ts (Docker orchestration). Configuration lives in src/config.ts and src/constants.ts. The plugin wrappers (.claude-plugin/, .cursor-plugin/, etc.) expose the same engine to different IDE/agent hosts.

How It Is Wired

Execution starts at src/index.ts → main (line 375). main creates the SocraticodeConfig, then calls autoResumeIndexedProjects, which eventually invokes getLockHolderPid (filesystem read). From there the flow follows the internal call graph:

• main → autoResumeIndexedProjects → ensureInfrastructure (src/tools/index-tools.ts) → startQdrant (src/services/qdrant.ts) → withRetry → getClient (calls the Qdrant client library).
• Indexing is driven by src/services/indexer.ts: indexProject calls onProgress (used by many progress‑reporting spots) and ensureCollection in qdrant.ts.
• File‑system writes are funneled through src/services/lock.ts (acquireProjectLock, releaseProjectLock).
• Semantic search queries travel src/tools/query-tools.ts → handleQueryTool → isIndexingInProgress (indexer.ts) → ensureReady (provider-*.ts) → the embedding provider (provider-openai.ts, provider-ollama.ts, or provider-google.ts).

The most widely referenced functions are:

These constitute the “blast radius” – changes here ripple through dozens of modules. Hub modules identified by the import graph are src/services/logger.ts, src/constants.ts, and src/services/docker.ts, each imported by >10 other files. No circular dependencies were found, but the hub nature makes them high‑impact change points.

How To Use It

# Clone the repo (use the exact URL)
git clone https://github.com/moses-y/SocratiCode
cd SocratiCode

# Install Node dependencies
npm ci

# Start supporting services (Qdrant vector store, optional Ollama)
docker-compose up -d   # pulls qdrant & ollama images defined in docker-compose.yml

# Launch the indexing server (CLI entry)
node -r ts-node/register src/index.ts   # runs main()

Configuration – edit src/config.ts or provide a JSON file referenced by src/config.ts (e.g. config.json) for Git branch detection, collection names, and Docker image tags. The repository includes a sample .socraticodeignore.example for path exclusions.

Running a query – once the server is up, send a POST to http://localhost:8000/query (the exact endpoint is defined in src/services/startup.ts). The request body matches the QueryRequest type in src/types.ts.

Real‑World Use

A CI pipeline can invoke node src/index.ts --mode=resume to ensure the index is always up‑to‑date before a test run. An LLM‑powered assistant (Claude, Cursor, etc.) then calls the local HTTP API to retrieve relevant symbols, file snippets, or dependency graphs, allowing a developer to ask “show me all functions that touch the User table” without scanning the repo manually.

Code Health & Issues

• MEDIUM – Enable Dependabot or Renovate – package.json is the only manifest; no bot configured.
• MEDIUM – Add a dependency‑vulnerability scan to CI – .github/workflows/ci.yml lacks a scan step.
• MEDIUM – Checkout should use persist-credentials: false – current workflow leaves the token in .git/config.
• LOW – Set timeout-minutes on CI jobs – prevents runaway builds.

Static analysis also flagged:

• HIGH – Duplicated code blocks across constants.ts, code-graph.ts, docker.ts, and tests – 81 identical 6‑line fragments. Consolidate into shared helpers.
• MEDIUM – Oversized files (qdrant.ts, indexer.ts, graph-imports.test.ts each > 750 lines). Split by responsibility.
• MEDIUM – High branching density in embedding-config.ts, config.ts, context-tools.ts. Refactor to strategy tables or smaller functions.
• MEDIUM – Hub modules (logger.ts, constants.ts, docker.ts) are imported by > 20 modules; keep their API stable.

No critical or low‑severity structural red flags were found; tests, CI, Dockerfile, and license are present.

The Bottom Line

SocratiCode delivers a self‑contained, zero‑setup indexing engine that can handle enterprise‑scale repositories and expose a fast, local search API. The codebase is well‑tested but contains a few large, highly‑connected modules and duplicated snippets that increase maintenance risk. Teams needing private, on‑prem AI code‑understanding—especially those already using Docker and Node—will find it ready to adopt, provided they address the modest health items (dependency updates, CI hardening, and refactoring of hub files).