grepika: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Overview

grepika is a token-efficient MCP (Model Context Protocol) server for code search. It combines three search backends for high-quality results:

• FTS5 - SQLite full-text search with BM25 ranking
• Grep - Parallel regex search using ripgrep internals
• Sparse n-gram prefilter - Fast substring candidate filtering, exposed through the legacy trigram naming in the code

The server communicates via JSON-RPC over stdin/stdout when running as an MCP server.

Build & Run Commands

# Build
cargo build --release

# Run MCP server — global mode (recommended, LLM calls add_workspace)
./target/release/grepika --mcp

# Run MCP server — single workspace mode
./target/release/grepika --mcp --root <path>

# CLI commands
grepika index                           # Index the codebase
grepika search <query> -l 20 -m combined  # Search (modes: combined, fts, grep)
grepika get <path> -s 1 -e 100          # Get file content with line range

# Run tests
cargo test

# Run single test
cargo test test_name

# Enable profiling logs
grepika --mcp --log-file /tmp/grepika.log

Architecture

MCP Server (rmcp)          ← JSON-RPC stdin/stdout
       │
Tool Router (server.rs)    ← search, structural_search, get, outline, toc, context, stats, refs, graph, index, diff, add_workspace
       │
Workspace                  ← Holds root + SearchService + Indexer (None in global mode)
       │
SearchService              ← spawn_blocking for async bridge
       │
┌──────┼──────┐
FTS5   Grep   Sparse n-gram ← Three lexical backends with weighted score merging
       │
SQLite + r2d2 pool         ← ~/.cache/grepika/<hash>.db by default

Key Design Decisions

• spawn_blocking bridge: MCP handlers are async (rmcp), but search operations are CPU-bound. The run_tool helper in server.rs uses tokio::task::spawn_blocking to bridge this gap.