Ask Claude about your code. Get instant answers.

KotaDB gives Claude Code superpowers for understanding your codebase. Index your repository once, then ask questions like "What breaks if I change this file?" and get accurate, dependency-aware answers.

KotaDB is a local code intelligence tool that helps Claude Code understand your codebase structure:

• Impact Analysis: Know exactly what files depend on what you're changing
• Code Search: Find code by meaning, not just text matching
• Dependency Graphs: See how your files connect to each other
• Zero Cloud: Everything runs locally - your code never leaves your machine

Prerequisites: Bun v1.1+ (required)

Step 1: Add to Claude Code

Add this to your Claude Code MCP config (~/.claude/mcp.json):

{
  "mcpServers": {
    "kotadb": {
      "command": "bunx",
      "args": ["kotadb@next", "--stdio"]
    }
  }
}

Step 2: Start Asking Questions

Just ask! KotaDB auto-indexes on first use:

"What files depend on src/index.ts?"

KotaDB automatically indexes your codebase and answers your question. No manual setup needed.

Once indexed, Claude can answer questions like:

• "What files import this module?"
• "What would break if I refactored this function?"
• "Find all files related to authentication"

KotaDB uses stdio (standard input/output) instead of HTTP ports:

• No port conflicts: Works alongside other tools without configuration
• Simpler setup: Just add the MCP config and go
• Better isolation: Claude Code manages the process lifecycle
• Recommended by MCP: Official pattern for local tools

KotaDB supports different tool tiers via the --toolset flag:

Example configurations:

• bunx kotadb@next --stdio (default: 8 tools)
• bunx kotadb@next --stdio --toolset core (minimal: 6 tools)
• bunx kotadb@next --stdio --toolset memory (with memory: 14 tools)
• bunx kotadb@next --stdio --toolset full (all: 20 tools)

KotaDB is part of my journey building AI-powered developer tools. I share everything I learn:

🎥 YouTube - Tutorials on Claude Code, MCP, and building tools like this
→ youtube.com/@jaymin-west

👥 Prompt to Prod Community - Learn to ship AI apps, not just prompt
→ skool.com/prompt-to-prod

Built by Jaymin West

# Install dependencies
cd app && bun install

# Start the API server
cd app && bun run src/index.ts

# Run tests
cd app && bun test

# Type-check
cd app && bunx tsc --noEmit

The server listens on port 3000 by default. Override with PORT=4000.

Data is stored in ~/.kotadb/kotadb.sqlite by default.

• cd app && bun --watch src/index.ts - Start server in watch mode
• cd app && bun test - Run the test suite
• cd app && bunx tsc --noEmit - Type-check the project

For detailed development setup, see DEVELOPMENT.md.

app/                   # Application layer (TypeScript/Bun API service)
  src/
    api/               # HTTP routes and database access
    db/                # SQLite client initialization and helpers
    indexer/           # Repository crawling, parsing, and extraction
    mcp/               # Model Context Protocol implementation
    types/             # Shared TypeScript types
  tests/               # Test suite

automation/            # Agentic layer (AI developer workflows)
  adws/                # ADW automation scripts

.claude/commands/      # Claude Code slash commands
.github/workflows/     # CI workflows
docs/                  # Documentation

KotaDB provides these tools through the Model Context Protocol:

• GET /health - Heartbeat endpoint
• POST /index - Queue repository for indexing
• GET /search?term=foo - Search for files containing term
• GET /files/recent - Recent indexing results

For multi-client scenarios or remote access, use HTTP transport:

{
  "mcpServers": {
    "kotadb": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Accept": "application/json, text/event-stream",
        "MCP-Protocol-Version": "2025-06-18"
      }
    }
  }
}

Customize the port with --port:

kotadb --port 4000

Endpoint: POST /mcp

Required Headers:

• Accept: application/json, text/event-stream
• MCP-Protocol-Version: 2025-06-18
• Content-Type: application/json

Example: Initialize Handshake

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "my-client", "version": "1.0"}
    }
  }'

Example: Search Dependencies

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "search_dependencies",
      "arguments": {
        "file_path": "src/auth/context.ts",
        "direction": "dependents",
        "depth": 2
      }
    }
  }'

KotaDB v2.0.0 uses project-local storage in .kotadb/ directories, providing automatic isolation between projects. All MCP tools support an optional repository parameter for filtering results.

// List all recent files
await tools.list_recent_files({ limit: 20 });

// Filter by repository
await tools.list_recent_files({ 
  limit: 20, 
  repository: "your-org/your-repo" 
});

See docs/guides/multi-repo-best-practices.md for detailed guidance.

By default, KotaDB only accepts requests from localhost origins. Configure KOTA_ALLOWED_ORIGINS environment variable (comma-separated) if needed.

The indexer clones repositories automatically when localPath is not provided. Override the GitHub clone source with KOTA_GIT_BASE_URL.