greppy-cli 1.0.0

Sub-millisecond semantic code search with AI reranking (Claude/Gemini)
Documentation

Greppy

 ██████╗ ██████╗ ███████╗██████╗ ██████╗ ██╗   ██╗
██╔════╝ ██╔══██╗██╔════╝██╔══██╗██╔══██╗╚██╗ ██╔╝
██║  ███╗██████╔╝█████╗  ██████╔╝██████╔╝ ╚████╔╝ 
██║   ██║██╔══██╗██╔══╝  ██╔═══╝ ██╔═══╝   ╚██╔╝  
╚██████╔╝██║  ██║███████╗██║     ██║        ██║   
 ╚═════╝ ╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝        ╚═╝

Sub-millisecond semantic code search with AI-powered reranking.

No cloud indexing. No API keys. Just greppy search "query".

What is Greppy?

Greppy is a local code search tool that combines:

  • BM25 full-text search via Tantivy for sub-millisecond queries
  • AI reranking via Claude or Gemini to surface the most relevant results
  • Background daemon with file watching for instant, always-up-to-date searches

Why Greppy?

AI coding tools (Claude Code, Cursor, Aider, OpenCode) need fast code search. Existing solutions are either:

  • Too slow - grep/ripgrep scan files on every query
  • Cloud-dependent - Sourcegraph, GitHub search require network
  • Not semantic - keyword matching misses context

Greppy gives you <1ms semantic search that runs entirely on your machine.

Installation

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/KBLCode/greppy/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/KBLCode/greppy/main/install.ps1 | iex

Cargo

cargo install greppy-cli

From Source

git clone https://github.com/KBLCode/greppy
cd greppy
cargo install --path .

Quick Start

# 1. Index your project (one-time setup)
cd your-project
greppy index

# 2. (Optional) Authenticate for AI-powered reranking
greppy login

# 3. Search!
greppy search "authentication middleware"

That's it! Greppy works immediately after indexing. Authentication is optional but recommended for better results.

Search Modes

Semantic Search (Default)

greppy search "error handling"

When authenticated, Greppy:

  1. Runs a fast BM25 search to find candidate results
  2. Sends candidates to Claude or Gemini for reranking
  3. Returns results ordered by semantic relevance

If not authenticated, automatically falls back to direct mode.

Direct Search (BM25 Only)

greppy search -d "TODO"
greppy search --direct "FIXME"

Pure BM25 search without AI. Faster, but results are ranked by keyword frequency rather than semantic relevance.

Search Options

Usage: greppy search [OPTIONS] <QUERY>

Options:
  -d, --direct             Direct mode (BM25 only, no AI)
  -n, --limit <N>          Maximum results (default: 20)
      --json               JSON output for scripting
  -p, --project <PATH>     Project path (default: current directory)

Examples

# Find authentication code
greppy search "user authentication"

# Find all TODOs (direct mode, faster)
greppy search -d "TODO" -n 50

# JSON output for scripting
greppy search "database" --json | jq '.results[0].path'

# Search a specific project
greppy search "config" -p ~/projects/myapp

Authentication

Greppy uses OAuth to authenticate with AI providers. No API keys needed!

Login

greppy login

  1. Select your provider using arrow keys:

    • Claude (Anthropic) - Uses your Claude.ai account
    • Gemini (Google) - Uses your Google account

  2. Complete the OAuth flow in your browser

  3. You're ready to use semantic search!

Logout

greppy logout

Removes all stored credentials from your system keychain.

How It Works

  • Tokens are stored securely in your system keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
  • Uses OAuth free tier - no API billing
  • Without authentication, searches fall back to direct BM25 mode automatically

Daemon

The background daemon provides sub-millisecond queries and automatic index updates.

Commands

greppy start    # Start the daemon
greppy stop     # Stop the daemon
greppy status   # Check if daemon is running

Features

  • In-memory indexes - Queries return in <1ms
  • File watching - Automatically updates indexes when files change
  • Query caching - Repeated queries are instant

Platform Support

Platform IPC Method
macOS Unix socket (~/.greppy/daemon.sock)
Linux Unix socket (~/.greppy/daemon.sock)
Windows TCP localhost (port in ~/.greppy/daemon.port)

Indexing

Basic Usage

# Index current directory
greppy index

# Index specific project
greppy index -p ~/projects/myapp

# Force full re-index
greppy index --force

What Gets Indexed

Greppy automatically:

  • Respects .gitignore patterns
  • Chunks code into semantic units (functions, classes, methods)
  • Extracts symbol names for boosted matching
  • Skips binary files and common non-code directories

Supported Languages

TypeScript, JavaScript, Python, Rust, Go, Java, Kotlin, Ruby, PHP, C, C++, C#, Swift, Elixir, Haskell, Lua, Shell, SQL, Vue, Svelte, HTML, CSS, JSON, YAML, Markdown, and more.

Performance

Mode Latency Notes
Daemon (warm) <1ms Index in memory
Direct (warm) 1-10ms Index on disk
Direct (cold) 50-100ms First query loads index
Semantic (AI) 500-2000ms Includes AI reranking

Indexing speed: ~17,000 chunks/second

Memory usage: ~55MB during indexing

Configuration

Optional config at ~/.greppy/config.toml:

[general]
default_limit = 20

[ignore]
patterns = ["node_modules", ".git", "dist", "build", "__pycache__"]

[index]
max_file_size = 1048576  # 1MB
max_files = 100000

[cache]
query_ttl = 60
max_queries = 1000

Environment Variables

Variable Description
GREPPY_HOME Override config/data directory (default: ~/.greppy)
GREPPY_LOG Log level: debug, info, warn, error

How It Works

  1. Indexing - Greppy walks your project, respecting .gitignore, and chunks code into semantic units (functions, classes, methods)

  2. Storage - Chunks are stored in a Tantivy index with BM25 ranking

  3. Search - Queries are parsed and matched against the index with symbol name boosting

  4. AI Reranking - When authenticated, top BM25 results are sent to Claude or Gemini for semantic reranking

  5. Watching - The daemon monitors file changes and incrementally updates indexes

Integration with AI Tools

Greppy works great with AI coding assistants:

  • Claude Code - Use as a code search tool
  • OpenCode - Integrate via CLI
  • Cursor - Call from terminal
  • Aider - Use for codebase exploration
  • Custom MCP servers - JSON output for easy parsing

JSON Output

greppy search "auth" --json

{
  "results": [
    {
      "path": "src/auth/login.rs",
      "content": "pub async fn login() -> Result<()> { ... }",
      "symbol_name": "login",
      "symbol_type": "method",
      "start_line": 1,
      "end_line": 50,
      "language": "rust",
      "score": 4.23
    }
  ],
  "query": "auth",
  "elapsed_ms": 0.8,
  "project": "/path/to/project"
}

Troubleshooting

"Not logged in" message

This is informational, not an error. Without authentication, Greppy uses direct BM25 search which still works great for most queries.

To enable AI reranking:

greppy login

Daemon won't start

Check if another instance is running:

greppy status
greppy stop
greppy start

Index seems outdated

Force a full re-index:

greppy index --force

Or start the daemon for automatic updates:

greppy start

OAuth login fails

  1. Make sure you have a browser available
  2. Check your internet connection
  3. Try logging out and back in: 
    greppy logout
greppy login

License

MIT

Links