KotaDB

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.

For Users

What KotaDB Does

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

5-Minute Setup

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"

Key Questions KotaDB Answers

Question	KotaDB Tool
"What breaks if I change this file?"	search_dependencies
"How risky is this refactor?"	analyze_change_impact
"Find code that does X"	search_code
"What files were recently indexed?"	list_recent_files

Why Stdio Transport?

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

Tool Tiers

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

Tier	Tools	Description
core	6	Essential code intelligence (search, index, dependencies)
default	8	Core + sync tools (kota_sync_export/import)
memory	14	Default + memory layer (decisions, failures, patterns, insights)
full	20	All tools including expertise validation

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)

---

Learn to Build AI Dev 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

---

For Contributors

Development Setup

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

Useful Scripts

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

Project Layout

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

---

API Reference

MCP Tools

KotaDB provides these tools through the Model Context Protocol:

Tool	Purpose
search_code	Search indexed code files for a term
index_repository	Index a git repository
list_recent_files	List recently indexed files
search_dependencies	Find file dependencies and dependents
analyze_change_impact	Analyze impact of proposed changes
validate_implementation_spec	Validate implementation specs
kota_sync_export	Export database to JSONL
kota_sync_import	Import JSONL into database

REST Endpoints

• 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

HTTP Transport (Alternative)

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

MCP Protocol Details

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
      }
    }
  }'

---

Multi-Repository Support

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.

---

Security

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.