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.
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
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)
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)
curl -fsSL https://recscse.github.io/codive/install.cmd -o install.cmd && install.cmd && del install.cmd
Build from source
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
-
Install codive
Follow the installation instructions above for your OS.
-
Configure AI agent integrations
Run once to auto-detect and register codive as an MCP server in all installed AI coding tools:
bashcodive setup
-
Index your repository
Navigate to any repository and build the index.
bashcd /path/to/my-repo codive init
-
Install git hooks (optional but recommended)
Keeps the index synchronized automatically after every commit and branch switch:
bashcodive install-hooks
-
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.
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.
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%
CLI: Code Search
codive search <query> [path]
Full-text search across all indexed files using SQLite FTS5. Returns file paths and snippet context.
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.
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.
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.
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.
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.
# Only if configuring manually: codive serve /path/to/repo
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.
| Tool | Category |
|---|---|
get_repo_map | Discovery |
find_symbol | Navigation |
find_references | Navigation |
find_callers | Navigation |
find_callees | Navigation |
find_tests_for | Testing |
get_file_skeleton | Reading |
read_symbol | Reading |
read_file_context | Reading |
search_code | Search |
get_git_changes | Git |
pack_feature_context | Context |
blast_radius | Impact |
save_decision | Memory |
get_decisions | Memory |
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.
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.
find_references
Find all usages, call sites, and import statements for a given symbol across the entire indexed repository.
find_callers
Discover all functions and line numbers that call or instantiate a given symbol. Essential before refactoring.
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.
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.
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.
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.
ProcessPayment, Server.Run, or path:Name).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.
search_code
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.
"retry backoff".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).
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.
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.
auth-strategy, api-versioning.get_execution_flow
Traces what a route, command or function reaches, from the code graph. Go only for call links.
endpoint:GET:/api/users or sym:pkg/auth.go:Login:24.get_codebase_graph
Returns graph nodes and edges for files, symbols, endpoints and packages. Each edge says whether it was resolved directly or inferred.
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:
{
"mcpServers": {
"codive": {
"command": "codive",
"args": ["serve"]
}
}
}
Claude Code / Claude Desktop
Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):
{
"mcpServers": {
"codive": {
"command": "codive",
"args": ["serve"]
}
}
}
Cursor IDE
Add to ~/.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:
| Table | Contents | Used 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:
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
| Language | Symbols Extracted | Build 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
# 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/.