codive Documentation

codive is a local-first code context engine and MCP (Model Context Protocol) server written in Go. It indexes your repository's AST symbols, full-text content, and git state into an embedded SQLite database — giving AI coding agents local access to exact code context without reading entire files.

Latest release Go 1.27+ Windows · macOS · Linux MIT License Zero cloud dependencies
Why codive? Without a context engine, an AI agent reading a 1,200-line controller file uses context on every line. With codive get_file_skeleton, it reads signatures and line ranges instead, then opens only what it needs.

How It Works

codive runs in two modes that complement each other:

CLI Mode

Direct terminal commands for developers: codive search, codive symbol, codive blast. Results print to stdout in clean, readable format.

MCP Server Mode

Run codive serve to start a JSON-RPC 2.0 server over stdio. AI coding agents (Claude, Antigravity, Cursor) call its 18 typed tools directly via the Model Context Protocol.

Index Layer

A multi-threaded scanner walks the repository, extracts AST symbols using per-language parsers, and writes everything to a single .codive/index.db SQLite WAL file.

Auto Sync

codive watch monitors the filesystem and incrementally re-indexes changed files. Git hooks (post-commit, post-checkout) keep the index current automatically.

Installation

codive ships as a single self-contained binary. No runtime, no dependencies.

macOS & Linux

bash
curl -fsSL https://recscse.github.io/codive/install.sh | bash

The script downloads the correct binary for your OS/arch, installs it to /usr/local/bin/codive, and verifies the checksum.

Windows (PowerShell)

powershell
irm https://recscse.github.io/codive/install.ps1 | iex

Installs to %LOCALAPPDATA%\codive\bin\codive.exe and adds it to the user PATH.

Windows (CMD / curl)

cmd
curl -fsSL https://recscse.github.io/codive/install.cmd -o install.cmd && install.cmd && del install.cmd

Build from source

bash
git clone https://github.com/recscse/codive
cd codive
go build -o codive .
# Or use the Makefile:
make build          # local binary
make build-all      # cross-compile all platforms to dist/

Quickstart

  1. Install codive

    Follow the installation instructions above for your OS.

  2. Configure AI agent integrations

    Run once to auto-detect and register codive as an MCP server in all installed AI coding tools:

    bash
    codive setup
  3. Index your repository

    Navigate to any repository and build the index.

    bash
    cd /path/to/my-repo
    codive init
  4. Install git hooks (optional but recommended)

    Keeps the index synchronized automatically after every commit and branch switch:

    bash
    codive install-hooks
  5. Done — open your AI coding tool

    Claude Code, Cursor, Antigravity, or VS Code will now call codive's MCP tools automatically when working in this repository.

CLI: Index Management

codive init [path]

Scan a repository and build the SQLite index from scratch. Uses a parallel goroutine pool (2× CPU cores) for concurrent file reading and AST extraction.

bash
codive init                    # current directory
codive init /path/to/repo      # explicit path
codive init . --json           # JSON output for CI/scripting

Output: live progress bar with file count and throughput, then a summary table with indexed file count, symbol count, primary language, and total latency.

codive update [path]

Incrementally re-index only files that have changed since the last index.

codive reindex [path]

Drop the existing index and rebuild from scratch. Use when the schema has changed after an upgrade, or when the index is corrupted.

codive watch [path]

Run a watcher that polls for changed files (every 2 seconds by default) and re-indexes them. The code graph refreshes the next time it is read.

codive status [path]

Display the current index state: total files, size on disk, last sync timestamp, and a language breakdown table.

output
  codive  Status

  Repository            /work/my-repo
  Indexed Files         176 files
  Total Size            711.74 KB
  Last Updated          Tue, 02 Sep 2026 12:58:43 +0530
  Primary Language      Java

  Language Breakdown
    Java          168 files   95.5%
    XML             6 files    3.4%
    Markdown        2 files    1.1%

codive search <query> [path]

Full-text search across all indexed files using SQLite FTS5. Returns file paths and snippet context.

bash
codive search "PaymentProcessor"
codive search "@Scheduled"
codive search "spring-boot-starter-web"   # searches pom.xml dependencies

CLI: Symbol Lookup

codive symbol <name> [path]

Find class, function, method, interface, or annotation definitions matching a name pattern. Returns exact file path, line number, and full signature.

output
  codive  Symbol Results

  1.  EventController                     [class]
       src/main/java/.../EventController.java:41
       @Slf4j @RestController @RequestMapping("/v1/event") public class EventController

  2.  @RestController                     [annotation]
       src/main/java/.../EventController.java:37

codive refs <symbol> [path]

Find all call sites, import statements, and usages of a given symbol across the entire repository.

CLI: Blast Radius

codive blast <symbol> [path]

Before modifying a function or class, calculate its blast radius: all upstream callers, affected files, and linked test suites. Prevents unexpected CI breakage.

bash
codive blast GenerateToken
codive blast PaymentProcessor --json

CLI: Git Diff

codive diff [path]

Show uncommitted changes mapped to enclosing AST symbols. Unlike git diff, this shows which functions changed — not just which lines — making it far more useful as context for an AI agent.

CLI: Feature Pack

codive pack <topic> [path]

Build a token-optimized context bundle for a feature area. Combines: relevant symbol definitions, file skeletons, related test suites, and stored architectural decisions — all in one compact output ready to paste into an LLM prompt.

CLI: Repo Map

codive map [path]

Print a directory-organized, symbol-annotated structural map of the repository. Supports --web to launch an interactive D3 network graph in the browser.

bash
codive map             # print to terminal
codive web --port 7890 # open the local code explorer

CLI: Explorer

codive web [path] [--port N]

Opens the local explorer in your browser, on port 7890 by default. It shows your uncommitted changes and what they affect, symbol search, callers and callees, execution flow, blast radius, a package map and source. It runs on localhost and works offline.

Accuracy: for Go functions, the explorer, codive blast and the blast_radius tool all use the type-checked call graph, and need the Go toolchain for full results. Symbols without a Go definition fall back to a text search by name, and the output says so.

CLI: Architectural Decisions

codive decisions [topic]

View architectural decisions recorded by AI agents during previous sessions. Decisions are stored in the local SQLite index and persist across IDE restarts, so agents don't re-debate the same design choices.

CLI: Setup & Hooks

codive setup [path]

Auto-detect all installed AI coding tools and register codive as an MCP server. Supports: Google Antigravity, Claude Desktop, Claude Code, Cursor IDE, VS Code (Continue, Cline), Windsurf.

codive install-hooks [path]

Install post-commit and post-checkout git hooks that call codive update automatically. This keeps the index continuously synchronized without any developer effort.

codive init-rules [path]

Auto-generate a .cursorrules / AGENTS.md / .windsurfrules file tailored to the detected language, framework, and project structure. Gives AI agents upfront architectural context.

CLI: MCP Server

codive serve [path]

Start the Model Context Protocol server over stdio. This is called automatically by your AI coding tool based on the configuration written by codive setup. You do not normally run this manually.

bash
# Only if configuring manually:
codive serve /path/to/repo
Workspace Auto-Detection: The MCP server automatically resolves the correct index for the workspace an AI agent is working in. If no index is found, it triggers a background auto-index. You never need to pass explicit paths from within an AI coding session.

MCP Tools Reference

When running as an MCP server, codive exposes 14 deterministic tools. All tools accept an optional workspace_path string argument to target a specific repository if multiple are indexed.

ToolCategory
get_repo_mapDiscovery
find_symbolNavigation
find_referencesNavigation
find_callersNavigation
find_calleesNavigation
find_tests_forTesting
get_file_skeletonReading
read_symbolReading
read_file_contextReading
search_codeSearch
get_git_changesGit
pack_feature_contextContext
blast_radiusImpact
save_decisionMemory
get_decisionsMemory

get_repo_map

Returns a directory-organized map of all indexed files annotated with symbol signatures. Features Proportional Tree Budgeting: uses a round-robin two-pass allocator that guarantees representation for every top-level package and module (even late-alphabet folders like services/ or web/) rather than cutting them off when early directories are large.

workspace_path optional
Absolute path to the repository root. Defaults to the workspace the agent is running in.
token_budget optional
Integer. Maximum number of tokens to use (default: 3000). Output is truncated at this limit.
max_depth optional
Integer. Limit directory depth shown in the map (0 = no limit).
include_symbols optional
Boolean. Include symbol signatures alongside file entries (default: true).
directory_filter optional
String. Restrict output to files under this directory prefix, e.g. src/main/java.

find_symbol

Locate class, function, method, annotation, or interface definitions by name. Returns exact file path, line number, symbol kind, and full signature.

query required
Name or partial name of the symbol to find. Supports substring matching across all languages.

find_references

Find all usages, call sites, and import statements for a given symbol across the entire indexed repository.

symbol required
The symbol name to find references for.
limit optional
Integer. Maximum number of call sites to return (default: 30).

find_callers

Discover all functions and line numbers that call or instantiate a given symbol. Essential before refactoring.

symbol required
The function or class name whose callers you want to find.

find_callees

List all internal functions and symbols invoked inside a given function's body. Useful for understanding a function's dependency chain without reading its full implementation.

symbol required
The function name whose internal calls you want to enumerate.

find_tests_for

Resolve test files and test case names associated with a given source file or symbol. Matches *_test.go, Test*.java, test_*.py, *.spec.ts, and similar conventions.

target required
A file path or symbol name to find tests for.

get_file_skeleton

Read a file's structure — class declarations, method signatures, field definitions — with all function bodies collapsed to line-range markers. Cut output size by about 95% on a 2,088-line file in our own benchmark (one repository, tokens estimated; results vary by file). Features Session Working-Set Deduplication: repeated calls in the same conversation automatically emit compact reference anchors, saving thousands of redundant tokens.

path required
Relative path to the file from the repository root.
force optional
Boolean. Bypass session deduplication and force re-printing the full skeleton (default: false).
Example: Instead of a whole file, get_file_skeleton returns its API surface — enough to understand all public methods, their parameters, and return types.

read_symbol

Returns just one declaration — its doc comment, signature, and complete implementation body — rather than reading the entire file.

symbol required
The target symbol name (e.g. ProcessPayment, Server.Run, or path:Name).
path optional
Relative file path to disambiguate identical symbol names across files.
limit optional
Integer. Maximum matching definitions to return (default: 5).

read_file_context

Read a file's full content along with its declared symbol outline, with automatic line-drift verification. If the file has changed since the last index, codive re-syncs the symbol table before returning content — preventing the agent from reading stale line numbers.

path required
Relative file path from the repository root.
workspace_path optional
Absolute path to the repository root. Defaults to the workspace the agent is running in.

Full-text search across all indexed file content using SQLite FTS5. Lists every matching line with its line number, grouped by file, best-matching files first. Matching ignores case and works on whole words; use grep for regular expressions or partial-word patterns.

query required
Words to find. Several words match files that contain all of them, anywhere. Wrap the query in double quotes for an exact phrase: "retry backoff".
limit optional
Integer. Maximum number of files (default: 20). The heading says when more files match. max_lines_per_file (default: 10) caps the lines listed per file; the rest are counted.

get_git_changes

Returns the current git diff with each changed file mapped to the enclosing AST functions that were modified. Unlike raw git diff, this tells the agent which methods changed, not just which lines.

Returns: branch name, list of changed files with status (modified/added/deleted), affected symbol names, and changed line counts.

pack_feature_context

The highest-value tool. Given a topic keyword, assembles a comprehensive feature context bundle containing: relevant symbol definitions, file skeletons, related test suites, FTS search matches, and stored architectural decisions. Features Subword Intent Decomposition (automatically expands queries like login or throttle to match actual symbols like VerifyCredentials or RateLimiter) and formats output using Karpathy's Attention U-Curve (types at top priming anchor, implementation functions and unit test assertions at bottom recency anchor).

topic required
A feature name, module, or concept keyword, e.g. auth, payment, EventController.

blast_radius

Before making a change, calculate the blast radius: all files that reference the target symbol, all direct callers, and all test suites that must be re-run. Returns a risk level (LOW / MEDIUM / HIGH) based on caller count and file spread.

symbol required
The function or class name whose change impact you want to assess.

save_decision / get_decisions

Persistent architectural memory. An AI agent can store design decisions (e.g. "Use DTOs between service and controller layers") during a session. These decisions are preserved in the SQLite index and retrieved in future sessions — so agents don't revisit already-resolved design questions.

topic required
Short topic label, e.g. auth-strategy, api-versioning.
summary required (save only)
The decision text to record.

get_execution_flow

Traces what a route, command or function reaches, from the code graph. Go only for call links.

node_id required
A graph node ID, such as endpoint:GET:/api/users or sym:pkg/auth.go:Login:24.
depth optional
Maximum call depth. Default 6.

get_codebase_graph

Returns graph nodes and edges for files, symbols, endpoints and packages. Each edge says whether it was resolved directly or inferred.

limit optional
Maximum nodes to return. Default 2000.

find_files

Finds indexed files by name or path.

Google Antigravity Integration

Run codive setup to register automatically, or add manually to ~/.gemini/config/mcp_config.json:

json — ~/.gemini/config/mcp_config.json
{
  "mcpServers": {
    "codive": {
      "command": "codive",
      "args": ["serve"]
    }
  }
}

Claude Code / Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

json — claude_desktop_config.json
{
  "mcpServers": {
    "codive": {
      "command": "codive",
      "args": ["serve"]
    }
  }
}

Cursor IDE

Add to ~/.cursor/mcp.json:

json — ~/.cursor/mcp.json
{
  "mcpServers": {
    "codive": {
      "command": "codive",
      "args": ["serve"]
    }
  }
}

VS Code — Continue / Cline

Add to ~/.continue/config.json under the experimental.modelContextProtocolServers key, or use Cline's MCP server settings UI to add a new server with command codive and args ["serve"].

Index Architecture

The .codive/index.db SQLite database contains four tables:

TableContentsUsed by
files One row per file: path, language, size, last-modified timestamp, content hash get_repo_map, update
symbols One row per symbol: file path, line number, kind (class/function/annotation/dependency), name, full signature find_symbol, find_callers, blast_radius
files_fts SQLite FTS5 virtual table over all file content for full-text search search_code, pack_feature_context
decisions Architectural decision records: topic, summary, created timestamp save_decision, get_decisions

SQLite WAL Mode

All connections use WAL (Write-Ahead Logging) mode for concurrent read/write safety:

DSN parameters
file:index.db?_pragma=journal_mode(WAL)
             &_pragma=busy_timeout(10000)
             &_pragma=synchronous(NORMAL)
             &_pragma=cache_size(-64000)
             &_pragma=foreign_keys(ON)

This prevents the database is locked (261) error that occurs when multiple MCP clients connect simultaneously. Connection pool is bounded (max 4 open, max 2 idle) to prevent file descriptor exhaustion.

Language Support

LanguageSymbols ExtractedBuild Manifests
Go structs, interfaces, functions, constants, type aliases go.mod dependencies
Java / Spring Boot classes, interfaces, records, methods, fields, annotations (@RestController, @Service, @Bean, @Scheduled, all HTTP mappings) pom.xml, build.gradle
TypeScript / JavaScript classes, interfaces, arrow functions, named exports, React components package.json dependencies
Python classes, functions, decorators, dataclasses requirements.txt, pyproject.toml
Rust structs, enums, traits, impl blocks, functions Cargo.toml

All other file types — including C/C++ — are indexed for full-text search (search_code) but have no AST symbol extractor yet, so find_symbol and call-graph tools won't see declarations in them. Binary files, build artifacts, and vendor directories are automatically excluded. Want to add a parser for your language? See CONTRIBUTING.md.

Building from Source

codive uses a standard Go module build. No CGO, no external runtime libraries required (SQLite is compiled in via modernc.org/sqlite).

Prerequisites

  • Go 1.27 or later
  • Git (for version injection via ldflags)

Build commands

bash
# Local binary (current OS/arch)
make build

# Run tests
make test

# Cross-compile all platforms (outputs to dist/)
make build-all

# Manual build with version injection
go build \
  -ldflags "-s -w \
    -X main.Version=v1.0.0 \
    -X main.GitCommit=$(git rev-parse --short HEAD) \
    -X main.BuildDate=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -o codive .

Release targets

make build-all compiles for: windows/amd64, windows/arm64, darwin/amd64, darwin/arm64, linux/amd64, linux/arm64. Binaries are written to dist/.