DOCSEARCHbyAlgolia
Submit Docs

grepai

repository·main·Indexed 23 days ago

https://github.com/yoanbernabeu/grepai

A privacy-first CLI tool for semantic code search that uses vector embeddings to search codebases by intent and meaning. It features call graph tracing, property usage tracking, and an MCP server for AI agents. Supports multiple embedding providers including Ollama, LM Studio, OpenAI, Synthetic, and OpenRouter, with storage backends such as gob, PostgreSQL (pgvector), and Qdrant.

Tokens
34.4K
Snippets
97
Records
196
Agent score
82%

What's inside grepai

  1. What is grepai?

    main
    grepai is a privacy-first semantic code search tool. Unlike traditional tools like grep or ripgrep that rely on exact text matches, grepai uses vector embeddings to index the meaning of your code. This allows you to perform natural language searches to find code based on what it does rather than just the specific variable or function names used.

  2. Understand the cost and performance benefits of grepai in Claude Code

    main

    Using grepai instead of traditional grep within Claude Code provides significant improvements in token efficiency and API costs, particularly when performing semantic searches (describing what code does rather than searching for specific function names).

    Key Performance Gains

    Based on benchmarks against large codebases (e.g., Excalidraw):

    • Reduced API Billing: Approximately -27.5% total cost reduction.
    • Reduced Tool Calls: Approximately -55% fewer tool calls.
    • Input Token Savings: Up to -97% reduction in fresh input_tokens.
    • Cache Efficiency: Up to -71% reduction in cache_creation_input_tokens by eliminating the need for subagents.

    Why grepai is more efficient

    Traditional workflows often involve a cycle of Grep $\rightarrow$ Glob $\rightarrow$ Read $\rightarrow$ Subagent Task. This cycle consumes many tokens as the agent reads files sequentially to filter results and spawns subagents that require fresh context caching.

    grepai simplifies this to a single step: Question $\rightarrow$ Bash: grepai search "semantic query" $\rightarrow$ Targeted results.

    This approach eliminates the need for the Glob tool and prevents the spawning of subagents, which are the primary drivers of cache_creation costs.

  3. What are grepai-skills and how do they work?

    main

    Concept

    grepai-skills are knowledge modules designed for AI agents. They act as instruction manuals that teach an agent how to leverage grepai's semantic search capabilities.

    How it works

    Once installed, the agent gains contextual knowledge of grepai commands. Instead of the agent performing expensive and token-heavy manual grep searches, it will recognize natural language requests and translate them into optimized grepai calls.

    Examples of improved agent behavior:

    • Semantic Search: When asked to "Search for error handling code", the agent uses grepai search "error handling".
    • Dependency Mapping: When asked "What functions call the Login function?", the agent uses grepai trace callers "Login".
    • Troubleshooting: When the agent encounters poor search results, it uses the troubleshooting skill to run diagnostic steps.

  4. When to use Hybrid Search vs Vector-only Search

    main

    Deciding whether to enable hybrid search depends on your query patterns and index size:

    Use Hybrid Search when:

    • Queries include exact function, class, or variable names (e.g., handleUserLogin).
    • You mix natural language with identifiers (e.g., validateEmail function in user module).
    • Vector-only search is missing obvious keyword matches.

    Stick to Vector-only Search when:

    • You are working with very large indexes (100k+ chunks), as hybrid search loads all chunks into memory for text matching, which may increase latency.
    • Your queries are purely semantic/natural language with no specific identifiers.
    • You have extreme performance-critical requirements.

  5. Use grepai with Git Worktrees

    main

    grepai provides zero-config support for git worktrees. When you run commands like search, trace, or watch from a linked worktree, grepai automatically detects the worktree, locates the main repository's .grepai/ directory, and auto-initializes a local .grepai/ by copying config.yaml, index.gob, and symbols.gob. It also automatically adds .grepai/ to the worktree's .gitignore.

    This allows search and trace to work immediately in any worktree without requiring a full re-indexing.

    # In the main project
cd /path/to/my-project
grepai watch

# Create a linked worktree
git worktree add ../my-project-feature feature-branch

# In the linked worktree, grepai works immediately
cd ../my-project-feature
grepai search "authentication flow"
grepai trace callers "HandleRequest"

  6. How workspaces work in grepai

    main

    A workspace is a grouping of multiple projects under a shared vector store index. This allows you to perform semantic searches across your entire stack (e.g., frontend, backend, and shared libraries) with a single query.

    Key characteristics:

    • Cross-project search: Results from all projects in the workspace are ranked together by relevance.
    • Project-scoped filtering: You can narrow search results to specific projects within a workspace using the --project flag.
    • Unique Indexing: Even if the same project is added to multiple workspaces, each workspace maintains its own index with unique path prefixes (e.g., workspace-name/project-name/path/to/file).
    • Configuration Hierarchy:
      • Workspace-level: The vector store (backend/DSN) and the embedder model must be defined at the workspace level to ensure compatibility across all projects.
      • Project-level: Chunking strategies (size, overlap) and ignore patterns can be customized per project within the same workspace.

  7. Tune chunking parameters

    main

    Chunking determines how code is split before embedding. You can adjust size (tokens per chunk) and overlap (context continuity).

    chunking:
  size: 512
  overlap: 50
    • Larger chunks: Better context, fewer results, slower.
    • Smaller chunks: More precise matches, more results, faster.
    • More overlap: Better continuity, larger index.

    Automatic Re-chunking: If the configured size exceeds the embedder's context limit, grepai will automatically attempt to split the chunk into smaller pieces (up to 3 attempts) to prevent errors.

  8. How grepai architecture works

    main

    grepai operates through a three-stage pipeline to enable semantic search:

    1. Indexing: Your source code files are processed by an Embedder (which can be local via Ollama or cloud-based via OpenAI).
    2. Storage: The resulting vector embeddings are stored in a Vector Store (supporting GOB or Postgres).
    3. Search: When you perform a semantic search, the query is converted into a vector and matched against the stored embeddings to return relevant code snippets.
    ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your Code     │     │    Embedder     │     │  Vector Store   │
│   (files)       │ ──► │  (Ollama/OpenAI)│ ──► │  (GOB/Postgres) │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                              ┌─────────────────────────────────────┐
                              │  Semantic Search                    │
                              │  "authentication flow" → results    │
                              └─────────────────────────────────────┘

  9. Understand grepai backend behavior in worktrees

    main

    The behavior of grepai in a worktree depends on the storage backend being used:

    • GOB: The index is copied as a seed, but each worktree maintains an independent index. Changes in one worktree do not affect others.
    • PostgreSQL / Qdrant: Configuration is inherited, and each worktree scopes its data within a shared store. This allows embeddings to be reused across worktrees and is recommended for teams using multiple worktrees for shared indexing.

  10. How Hybrid Search works: Text Search and RRF Fusion

    main

    Hybrid search uses two distinct mechanisms to rank results:

    Text Search Mechanism

    The text search component performs simple keyword matching:

    1. The query is tokenized into words (lowercase, minimum 2 characters).
    2. Each chunk is scored based on the ratio: matches / total_words.
    3. Results are sorted by this score.

    RRF (Reciprocal Rank Fusion) Mechanism

    To merge the vector search list and the text search list, grepai uses Reciprocal Rank Fusion. This method is robust because it does not require normalizing scores between the two different search sources. The formula applied is:

    score(doc) = Σ 1/(k + rank_i) for each source.

  11. Understand the Repository Planning Graph (RPG) implementation

    main

    The grepai/rpg package implements the Repository Planning Graph (RPG), which serves as a unified Intermediate Representation (IR) for agentic reasoning. The graph model $G=(V, E)$ uses two types of nodes:

    • $V_H$ (High-level): Represented by NodeKind values for Areas or Categories.
    • $V_L$ (Low-level): Represented by NodeKind values for Files or Symbols.

    Edges are typed to support a dual view of the repository:

    • Functional View: Uses EdgeFeatureParent.
    • Dependency View: Uses EdgeInvokes or EdgeImports.

    The graph is maintained via an Evolver that supports incremental updates (Delete/Modify/Add) with orphan pruning and drift detection.

  12. How semantic search works in grepai

    main

    The grepai search process follows these steps:

    1. Query embedding: The search query is converted into a vector using a configured embedder (Ollama, OpenAI, or LM Studio).
    2. Similarity search: Cosine similarity is calculated between the query vector and the indexed code chunk vectors.
    3. Boost adjustment: Scores are adjusted based on file paths. By default, Structural Boosting is enabled, which boosts source directories (e.g., /src/, /lib/, /app/) and penalizes tests, mocks, fixtures, and generated files.
    4. Result ranking: Results are sorted by the final relevance score (0.0 to 1.0).

    Note on Hybrid Search: By default, search is purely semantic. You can enable Hybrid Search in your configuration to combine vector similarity with text matching using Reciprocal Rank Fusion (RRF). This is useful when your query contains exact identifiers or keywords.