agent-coderag

The API Knowledge Bridge for AI Coding Agents.
Local, fast, and token-efficient semantic search that eliminates LLM hallucinations by providing real-time local context.

Features • Quick Start • Architecture • AI Agent Guide • Contributing

Why agent-coderag?

In 2026, AI coding agents are limited by stale training data. They hallucinate library calls because they don't know your specific environment.

• The Pain: Your agent writes code for Pydantic v1 while you have v2 installed. You waste 5000+ tokens in a "Fail-Fix-Fail" loop.
• The Cure: agent-coderag extracts live API signatures and technical intent from your local environment. It feeds the LLM exactly what it needs to see—no more, no less.

Key Features

• Instant Startup: Built on onnxruntime and Rust-based tokenizers. Zero PyTorch overhead.
• Context Compression: Replace 10,000 lines of raw code with a 200-token semantic summary.
• Universal Tree-Sitter Parser: Supports 25+ languages (Python, JS/TS, Rust, Java, C++, Go, Ruby, etc.) with high precision.
• API Discovery: On-the-fly extraction of public signatures for 6 core ecosystems (Python, Java, Go, TypeScript, Rust, C#) with build-system awareness.
• Local First: All embeddings and data stay on your machine in a high-performance DuckDB VSS index.

Quick Start

Installation

pip install agent-coderag
# Install tree-sitter grammars for your languages on-demand
pip install tree-sitter-python tree-sitter-javascript

Initial Setup

# Download pre-trained multilingual embedding models (~130MB)
agent-coderag setup

# (Optional) Connect your preferred LLM for semantic distillation
# Using Ollama (Local)
agent-coderag config --url "http://localhost:11434" --provider "ollama" --model "qwen2.5-coder"

# Using OpenAI-compatible API (e.g. Groq, OpenRouter, DeepSeek)
agent-coderag config --url "https://api.deepseek.com" --provider "openai" --key "your-api-key" --model "deepseek-chat"

Offline Mode (No Provider)

If you don't configure an LLM provider, agent-coderag works in 100% Offline Mode:

• Parsing & API Discovery: Still works perfectly using local Tree-Sitter grammars and javap.
• Search: Remains fast and accurate.
• Distillation: Instead of AI-generated summaries, the system uses code signatures and entity names as fallback metadata. No data ever leaves your machine.

Remote embeddings are not 100% Offline Mode. If you set embedding_base + embedding_model, sync / search / rebuild need the network. Embedder choice is process-global (config.json); after a remote model or dimension change, run agent-coderag rebuild (or delete that --db) for each project index.

agent-coderag config \
  --embedding-url "http://localhost:8081/v1" \
  --embedding-model "text-embedding-3-small" \
  --embedding-key "your-api-key" \
  --embedding-provider "openai"

agent-coderag config --clear-embedding

First Sync & Search

# Index your entire project (respects .gitignore automatically)
agent-coderag sync --all

# Trusted Maven/Gradle projects only: allow dependency resolution
agent-coderag sync --all --allow-build-execution

# Perform a semantic search
agent-coderag search "how does the authentication middleware work?"

Dependency build execution is disabled by default. Maven and Gradle build files can execute repository-controlled code, so use --allow-build-execution only after you have reviewed and trust the project.

API Discovery

Verify external library signatures without leaving the CLI:

# Explicit language selection (Recommended for multi-language repos)
agent-coderag api requests --lang python
agent-coderag api lodash --lang typescript
agent-coderag api serde --lang rust

# Built-in auto-detection for common project types (Cargo.toml, package.json, etc.)
agent-coderag api fmt

Library Usage

1.4.0 migration: Storage lifetime and default DB resolution changed. Pin agent-coderag<1.4 until you adapt (see Database & lifetime).

from pathlib import Path

from code_rag import CodeRAG, default_db_path

async def main():
    root = Path(".")
    print(default_db_path(root))  # resolved path before first sync

    # db=None (default): legacy code_rag.db in cwd/root, else root/.coderag.db
    async with CodeRAG(root=root) as rag:
        await rag.setup()
        await rag.sync(index_all=True)
        hits = await rag.search("authentication middleware", limit=5)
        # Opens the DB only when a provider needs it (e.g. Java JAR cache).
        report = await rag.api("pydantic", lang="python")

Database & lifetime

• Default path (db=None): resolution order is (1) ./code_rag.db if it exists, (2) else {root}/code_rag.db if it exists, (3) else {root}/.coderag.db (created on first sync/rebuild). Use default_db_path(root) to preview. New projects: prefer .coderag.db (step 3) or set db= explicitly.
• Explicit path: CodeRAG(db=...) / agent-coderag --db .... Path is a file, not a directory. Relative paths resolve against process cwd, not root.
• Sidecars: DuckDB may write WAL sidecars (e.g. .coderag.db.wal) beside the index during writes; locks should not persist after an operation finishes.
• Connect timeout: connect_timeout_seconds=5 (CLI --connect-timeout) waits on file locks, then raises StorageBusyError (ErrorCode.STORAGE_BUSY). Pass 0 for a single attempt.
• Read-only search: search (and api when storage is needed) opens read-only. A missing index file is an error — use sync/rebuild to create it. An index file that exists but has no embeddings table (e.g. opened/written without a completed vector sync) raises StorageError with ErrorCode.EMBEDDINGS_MISSING — run sync (library: CodeRAG.sync) before search. With --json, success is a hit array; errors are {"status":"error","message":...} and include "code" when the exception carries an ErrorCode.
• Paths: sync stores paths relative to root (src/a.py). The first sync rewrites an older absolute index when the file is still under root or its unit hashes match a file in the tree. Search returns an absolute path under the current root. search --relative-paths, config relative_paths: true, or CodeRAG(relative_paths=True) returns the stored relative path. Until that sync runs, search returns the absolute path stored in the index. Ignore rules use the same project-relative path, so a .worktrees/<name> checkout is indexed when that directory is the root.
• Lifetime: embedder/parser/distiller stay warm; DuckDB opens per operation and closes afterward. One CodeRAG instance serializes overlapping ops. config() with embedding flags / --clear-embedding closes the process embedder so the next op rebuilds it; distill-only config refreshes Distiller and keeps the embedder.
• api() without DB: providers that do not need the index (e.g. Python) skip DuckDB entirely; Java uses a short read-only open for JAR cache lookup.
• Errors: catch CodeRAGError and inspect .code — STORAGE_BUSY, STORAGE_CORRUPT, EMBEDDING_MISMATCH, EMBEDDINGS_MISSING (from code_rag import ErrorCode).

Supported Ecosystems (Discovery)

How It Works

agent-coderag creates a semantic map of your codebase using a multi-stage pipeline:

graph LR
    Code[Local Codebase] --> Parser[Multi-Language Parser]
    Parser --> Delta[Delta-Sync SHA-256]
    Delta -- New/Changed --> Distill[LLM Distiller]
    Delta -- Unchanged --> Cache[Local Cache]
    Distill --> Embed[ONNX Embedder]
    Cache --> Embed
    Embed --> DuckDB[(DuckDB VSS)]
    DuckDB --> Agent[AI Agent Response]

1. Structural Parsing: Identifies classes, methods, and relations (imports).
2. Technical Distillation: Generates a concise "intent summary" of each code unit.
3. Vectorization: Local ONNX model creates 384-dimensional embeddings.
4. VSS Storage: DuckDB enables sub-millisecond similarity search.

Agent-Native Usage

agent-coderag is designed to be the primary tool for your AI agents.

The Protocol:

1. Search First: Instead of reading files, the agent runs agent-coderag --json search.
2. Verify Signatures: The agent runs agent-coderag api to get real signatures.
3. Read Summaries: The agent uses the summary field to decide which files are actually relevant.

Programmatic Output:

agent-coderag --json search "database init" --limit 1

Development & Testing

We maintain a strict quality bar.

# Install development dependencies
make install

# Run full test suite with coverage
make test

# Run linters (Prospector, MyPy, Bandit)
make lint

Contributing

Contributions make the open source community an amazing place to learn, inspire, and create.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'feat: add AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

🔝 Back to top

Built for agents. Driven by humans.