Quick Start

Up and running in 60 seconds

1. Install

On macOS and Linux, the installer downloads codedb and auto-registers detected MCP clients:

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

On native Windows x86_64, run the checksum-verifying installer in PowerShell:

irm https://raw.githubusercontent.com/justrach/codedb/v0.2.5833/install/install.ps1 | iex

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

2. MCP server (recommended)

The shell installer registers detected clients automatically. On Windows, configure the client with the absolute path to codedb.exe. Then open a project and the 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

Core 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