Quick Start

# Up and running in 60 seconds

## 1. Install

One command. Downloads the binary for your platform and auto-registers codedb as an MCP server in Claude Code, Codex, Gemini CLI, and Cursor.

    curl -fsSL https://codedb.codegraff.com/install.sh | bash

Supports macOS (ARM64, x86_64) and Linux (ARM64, x86_64). macOS binaries are codesigned and notarized.

## 2. MCP server (recommended)

After installing, codedb is automatically registered. Open any project and the 16 MCP tools are available to your AI agent.

    # Manual MCP start (auto-configured by install script)
    codedb mcp /path/to/your/project

The MCP server indexes your codebase on startup, then serves all queries over JSON-RPC 2.0 stdio. Sub-millisecond responses, every time.

## 3. HTTP server

For direct API access or integration with custom tools:

    codedb serve /path/to/your/project
    # listening on localhost:7719

## 4. CLI commands

Quick one-off queries from the terminal:

    codedb tree /path/to/project          # file tree with symbol counts
    codedb outline src/main.zig           # symbols in a file
    codedb find AgentRegistry             # find symbol definitions
    codedb search "handleAuth"            # full-text search (trigram)
    codedb word Store                     # exact word lookup (O(1))
    codedb hot                            # recently modified files

## 5. Example: agent explores a codebase

Here is how an AI agent uses codedb to understand a project:

    # 1. Get the file tree
    curl localhost:7719/tree
    # -> src/main.zig      (zig, 55L, 4 symbols)
    #    src/store.zig     (zig, 156L, 12 symbols)
    #    src/agent.zig     (zig, 135L, 8 symbols)

    # 2. Drill into a file
    curl "localhost:7719/outline?path=src/store.zig"
    # -> L20: struct_def Store
    #    L30: function init
    #    L55: function recordSnapshot

    # 3. Find a symbol across the codebase
    curl "localhost:7719/symbol?name=AgentRegistry"
    # -> {"path":"src/agent.zig","line":30,"kind":"struct_def"}

    # 4. Full-text search
    curl "localhost:7719/search?q=handleAuth&max=10"

    # 5. Check what changed
    curl "localhost:7719/changes?since=42"

## MCP tools reference

16 tools available over the Model Context Protocol:

`codedb_tree` | Full file tree with language, line counts, symbol counts
`codedb_outline` | Symbols in a file: functions, structs, imports, with line numbers
`codedb_symbol` | Find where a symbol is defined across the codebase
`codedb_search` | Trigram-accelerated full-text search
`codedb_word` | O(1) inverted index word lookup
`codedb_hot` | Most recently modified files
`codedb_deps` | Reverse dependency graph
`codedb_read` | Read file content
`codedb_edit` | Apply line-range edits (atomic writes)
`codedb_changes` | Changed files since a sequence number
`codedb_status` | Index status (file count, current sequence)
`codedb_snapshot` | Full pre-rendered JSON snapshot of the codebase
`codedb_bundle` | Batch multiple queries in one call
`codedb_remote` | Query indexed public repos via api.wiki.codes
`codedb_projects` | List all indexed local projects
`codedb_index` | Index a new local folder

## Building from source

Requires Zig 0.15+:

    git clone https://github.com/justrach/codedb.git
    cd codedb
    zig build                              # debug build
    zig build -Doptimize=ReleaseFast       # release build
    zig build test                         # run tests

See benchmarks GitHub