code-context-v2

Built for local agent workflows in Claude Code and similar CLI environments.

Why

LLMs work better with the right context. Grep finds text; this finds meaning. Ask for "authentication middleware" and get the actual auth logic, not every file that mentions "auth".

How it works:

1. Index your codebase with tree-sitter AST parsing (functions, classes, methods — not arbitrary line splits)

2. Embed chunks with Voyage AI (voyage-4-large for documents, voyage-4-lite for queries — same embedding space, asymmetric retrieval)

3. Search with PostgreSQL/pgvector + pgvectorscale by default when using .env.example (or embedded LanceDB/SQLite alternatives), then rerank-2.5 for precision

4. Query indexed content from the CLI with semantic search commands

Related MCP server: codebase-index

Architecture

Agent / CLI
    │
    ├── cc2.sh
    └── uv run code-context-manage
             │
      RetrievalPipeline
        │            │
        ▼            ▼
   Voyage AI    local vector store
 voyage-4-lite  Postgres/pgvector
  (query embed) LanceDB/SQLite fallback
 rerank-2.5
  (reranking)

Retrieval pipeline:

1. Embed query with voyage-4-lite (fast, shared space with indexed docs)

2. Retrieve candidates from embedded LanceDB, experimental SQLite + FTS5 + sqlite-vec (CC2_CODE_BACKEND=sqlite), or PostgreSQL/pgvector (CC2_CODE_BACKEND=postgres)

3. Rerank: rerank-2.5 + relative threshold (max(score_floor, top_score * factor))

4. Dedup: overlap/containment + Jaccard similarity filtering

5. Return: Markdown-formatted chunks with file paths, line numbers, relevance scores

Code layout:

• src/code_context/retrieval/ — retrieval facade plus focused helpers for intent resolution, result controls, cross-file context, and quality logging

• src/code_context/db/ — DatabasePool facade delegating to domain-specific stores for code, projects, memory, and books

• src/code_context/chunking/ — tree-sitter parsing, chunk models, and post-processing/splitting helpers

• src/code_context/indexing/ — filesystem and indexing support helpers used by Indexer

• src/code_context/cli/ — user-facing entrypoints plus shared runtime/search/sync/watcher helpers

The public APIs stay centered on RetrievalPipeline, DatabasePool, Indexer, and the CLI entrypoints; the internal modules are split to keep those surfaces stable while reducing coupling.

Quick Start

Prerequisites

• uv (Python package manager)

• Voyage AI API key (free tier available)

• Docker for the recommended PostgreSQL/pgvector + pgvectorscale backend

1. Clone and configure

git clone https://github.com/enzodevs/code-context-v2.git
cd code-context-v2

cp .env.example .env
# Edit .env: set CC2_VOYAGE_API_KEY and keep CC2_CODE_BACKEND=postgres

The recommended local backend is PostgreSQL/pgvector + pgvectorscale via the Timescale Docker image (CC2_CODE_BACKEND=postgres), using the compose service on 127.0.0.1:25432.

docker volume create code-context-pgdata
docker compose up -d postgres

PostgreSQL data is stored in the external Docker volume code-context-pgdata, mounted at the image's active PGDATA path (/home/postgres/pgdata/data). This protects the cc2 index from normal compose lifecycle commands, including docker compose down -v. Do not remove the volume with docker volume rm code-context-pgdata unless you intentionally want to delete the index.

No Docker available? Set CC2_CODE_BACKEND=lancedb in .env to use embedded LanceDB at ~/.local/share/cc2/lancedb. Experimental SQLite + FTS5 + sqlite-vec is also available with CC2_CODE_BACKEND=sqlite.

2. Install dependencies

uv sync

3. Index a project

uv run code-context-manage --index /path/to/your/project

Project indexing respects .gitignore by default. Pass --include-gitignored only when you intentionally want to index files matched by gitignore rules.

4. Use the search commands

Use either the direct Python entrypoint or the shell wrapper:

# List indexed projects
uv run code-context-manage --list

# Semantic search from inside an indexed repo (project inferred from cwd)
./cc2.sh search "auth middleware"

# Explicit project override when running outside the repo or targeting another project
./cc2.sh search "auth middleware" -p my-project

# Opt in to graph expansion from dense chunk hits
./cc2.sh search "auth middleware" -p my-project --graph

# Search within one file (also infers project from cwd)
./cc2.sh search-file src/auth.ts "token validation"

# Search indexed literature
./cc2.sh search-lit "dependency injection"

Search Controls

The CLI search commands support optional output-shaping controls:

Recommended defaults for agent workflows:

• Keep include_tests=false unless the user explicitly asks about tests.

• Start with --max-tokens between 1800 and 3200 for typical coding tasks.

• Use --json when another tool or agent will post-process the results.

Project Resolution

For CLI code search commands, -p/--project is optional when your current working directory is inside an indexed project root.

• cc2.sh passes the caller cwd through to the Python CLI.

• cc2 resolves the project by finding the indexed project_root that contains the cwd.

• If multiple indexed roots match, cc2 picks the longest matching root.

• Use -p when running outside the repo, targeting another indexed project, or overriding cwd-based resolution.

MCP Setup

Copy .mcp.json.example into your MCP client config and replace /path/to/code-context-v2 with this repository path.

{
  "mcpServers": {
    "code-context": {
      "command": "uv",
      "args": ["--directory", "/path/to/code-context-v2", "run", "code-context"],
      "env": {
        "CC2_VOYAGE_API_KEY": "${CC2_VOYAGE_API_KEY}",
        "CC2_DATABASE_URL": "postgresql://coderag:your_password@localhost:25432/coderag"
      }
    }
  }
}

MCP clients should call list_projects first, then pass the returned project id as the explicit project argument to search tools. The CLI can infer the project from the current working directory; MCP calls do not receive that cwd context. Graph expansion is available through CLI --graph, CC2_GRAPH_SEARCH_ENABLED=true, or the MCP search tools' graph argument.

Search Intent Guide

Use --intent to steer reranking precision:

Default intent is implementation when omitted.

Benchmarking

Retrieval changes should be measured with local benchmark suites when available. Suite definitions live in benchmarks/retrieval/*.json, but those JSON files are ignored because they often reference local indexed project IDs and private repository paths.

# List local benchmark-enabled projects
uv run python -m scripts.benchmark_retrieval --list

# Run one local project suite
uv run python -m scripts.benchmark_retrieval my-project

# Compare against a saved local baseline
uv run python -m scripts.benchmark_retrieval my-project --compare baseline-v1

# Run all local benchmark suites and save a combined baseline
uv run python -m scripts.benchmark_retrieval all --save hybrid-v1

# Run with graph expansion enabled
uv run python -m scripts.benchmark_retrieval my-project --graph

# A/B compare dense-only vs dense + graph expansion in one run
# Prints graph-derived candidate/final counts, added/removed expected files,
# worsened top results, surviving edge types, and token impact.
uv run python -m scripts.benchmark_retrieval my-project --compare-graph

See benchmarks/retrieval/README.md for the local suite schema.

CLI

# Index a project (auto-generates ID from folder name)
uv run code-context-manage --index /path/to/project

# Index with custom ID
uv run code-context-manage --index /path/to/project --id my-project

# Include files matched by .gitignore
uv run code-context-manage --index /path/to/project --include-gitignored

# Check what changed (dry-run)
uv run code-context-manage --check my-project

# Sync only changed files
uv run code-context-manage --sync my-project

# Force full reindex
uv run code-context-manage --index /path/to/project --force

# Show statistics
uv run code-context-manage --stats

# Watch for changes (background daemon)
uv run code-context-manage --watch /path/to/project

# List indexed books
uv run code-context-manage --list-books

# Initialize additive graph tables (does not reindex code)
uv run code-context-manage graph init

# Build the phase-1 graph from the existing code index
uv run code-context-manage graph build --project my-project
uv run code-context-manage graph build --project my-project --phase existing-index

# Add Phase 2 deterministic source relations incrementally (no code reindex)
uv run code-context-manage graph build --project my-project --phase deterministic

# Check graph backfill status and edge counts by type
uv run code-context-manage graph status --project my-project

# Create a project memory root with a MEMORY.md hub
./cc2.sh memory init

# Index a Markdown memory root
./cc2.sh memory index .pi/memory --project my-project

# Search indexed memory
./cc2.sh memory search "refresh token rotation" --project my-project

Standalone memory entrypoint also exists:

uv run code-context-memory init
uv run code-context-memory index .pi/memory --project my-project
uv run code-context-memory search "refresh token rotation" --project my-project

See docs/memory.md for the memory layout, MEMORY.md hub pattern, and filters.

For the full documentation index, see docs/README.md.

There's also cc2.sh — a bash wrapper with a gum-based TUI plus non-interactive commands like search, search-file, and search-lit.

Supported Languages

Adding a new language requires a tree-sitter grammar and chunk type mappings in src/code_context/chunking/parser.py.

Configuration

All settings use the CC2_ prefix via environment variables or the repository .env file:

See src/code_context/config.py for all available settings.

Performance

• Vector search: <50ms

• Reranking: <100ms

• Total CLI search response: <200ms

• Initial indexing: ~5-10 min for 1000 files

• Incremental sync: <2s per changed file

• Storage: ~100MB per 100k chunks

How Indexing Works

1. Walk the project tree (skips node_modules, vendor, .git, dist, Laravel runtime/generated dirs, etc.)

2. Hash each file with BLAKE3 — skip unchanged files

3. Parse with tree-sitter into semantic chunks (functions, classes, methods)

4. Small files (<200 lines) still extract symbol-level chunks; generic file chunks are dropped when symbol chunks exist

5. Embed chunks with voyage-4-large in batches

6. Store chunk metadata and vectors in the selected backend; .env.example uses PostgreSQL/pgvector, with LanceDB and SQLite alternatives available

7. File reindex operations replace old chunks before adding fresh chunks; rerun cc2 sync if an interrupted process leaves a project partially indexed

Supported code languages include TypeScript, JavaScript, Python, Java, Go, Rust, SQL, PHP, and Vue single-file components. PHP files get class/function/method chunks; Vue SFCs are indexed as file-level chunks.

Laravel defaults skip Composer dependencies, runtime/cache output, built frontend assets, PHPUnit cache files, Pi/local MCP scratch, and generated Wayfinder route/action files.

Development

This project uses uv for dependency management and Ruff for linting. ty is configured warning-only as a fast type-checking signal while the existing type backlog is migrated.

uv sync --dev
uv run ruff check .
uv run ty check
uv run pytest

Maintainer and coding-agent guidance lives in AGENTS.md.

License

MIT