grepai

https://github.com/yoanbernabeu/grepai
Admin
grepai is a privacy-first, CLI-native tool that semantically searches your codebase by indexing code...
Tokens:139,260
Snippets:1,111
Trust Score:9.6
License:MIT
Update:5 days ago
Show doc for...
Tokens:
Raw
### Install and run grepai-beads-helpers setup script

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/community-tools.md

Clones the grepai-beads-helpers repository and runs the setup script to install grepai and beads, configure PATH, and initialize the beads memory system. Then runs the bulk indexing script to index all projects in ~/GitHub/ and ~/projects/.

```bash
# Clone and run setup script
git clone https://github.com/miqcie/grepai-beads-helpers.git
cd grepai-beads-helpers
./setup.sh

# Bulk index all your projects
./index-all-projects.sh
```

--------------------------------

### Start Qdrant with Docker Compose

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/configuration.md

Setup command to start Qdrant using the `qdrant` profile.

```bash
docker compose --profile=qdrant up -d

```

--------------------------------

### Start Ollama server

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/backends/embedders.md

Start the Ollama server with the `ollama serve` command.

```bash
ollama serve
```

--------------------------------

### Install specific grepai-skills categories

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/blog/introducing-grepai-skills.md

Shows how to install only specific skills, install globally, or list available skills. Use --skill to select a skill, -g for global installation, and --list to see all available skills.

```bash
# Just search-related skills
npx skills add yoanbernabeu/grepai-skills --skill grepai-search-basics

# Install globally (available in all projects)
npx skills add yoanbernabeu/grepai-skills -g

# See all available skills
npx skills add yoanbernabeu/grepai-skills --list
```

--------------------------------

### Initialize grepai project

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/blog/introducing-grepai-skills.md

Initialize your project and start watching for changes.

```bash
grepai init && grepai watch
```

--------------------------------

### Quick Start commands for grepai

Source: https://github.com/yoanbernabeu/grepai/blob/main/README.md

Initializes grepai in a project, starts the indexing daemon, performs a semantic search, and traces callers of a function. These commands are used in sequence to set up and use grepai.

```bash
grepai init                        # Initialize in your project
```

```bash
grepai watch                       # Start indexing daemon
```

```bash
grepai search "error handling"     # Search semantically
```

```bash
grepai trace callers "Login"       # Find who calls a function
```

--------------------------------

### Install grepai via Homebrew

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/blog/introducing-grepai-skills.md

Install grepai using Homebrew with the tap yoanbernabeu/tap/grepai.

```bash
brew install yoanbernabeu/tap/grepai
```

--------------------------------

### Install golangci-lint

Source: https://github.com/yoanbernabeu/grepai/blob/main/CONTRIBUTING.md

Install the golangci-lint tool used for code quality checks.

```bash
go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
```

--------------------------------

### Install grepai from Source

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/installation.md

Build grepai from source. Requires Go 1.24+. Clone the repository, build the binary, and move it to your PATH.

```bash
# Clone the repository
git clone https://github.com/yoanbernabeu/grepai.git
cd grepai

# Build the binary
make build

# The binary is created at ./bin/grepai
# Move it to your PATH
sudo mv ./bin/grepai /usr/local/bin/
```

--------------------------------

### Start indexing workspace

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/workspace.md

Start indexing the workspace in foreground or background mode. Use --background to run in the background.

```bash
# Foreground mode
grepai watch --workspace my-fullstack
```

```bash
# Background mode
grepai watch --workspace my-fullstack --background
```

--------------------------------

### Install specific skills with npx

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/skills.md

Shows various npx skills add commands for installing specific skills, globally, listing available skills, installing to specific agents, and non-interactive installation.

```bash
# Install only search-related skills
npx skills add yoanbernabeu/grepai-skills --skill grepai-search-basics

# Install globally (available in all projects)
npx skills add yoanbernabeu/grepai-skills -g

# List all available skills
npx skills add yoanbernabeu/grepai-skills --list

# Install to specific agents
npx skills add yoanbernabeu/grepai-skills -a claude-code -a cursor

# Non-interactive (CI/CD friendly)
npx skills add yoanbernabeu/grepai-skills --all -y
```

--------------------------------

### Starting the daemon with output

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/watch-guide.md

Command to start the background watcher and its expected output, including the PID and log file location. The daemon waits for full initialization before returning success.

```bash
$ grepai watch --background
Background watcher started (PID 12345)
Logs: /Users/you/Library/Logs/grepai/grepai-watch.log

Use 'grepai watch --status' to check status
Use 'grepai watch --stop' to stop the watcher
```

--------------------------------

### Install grepai-skills with npx

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/blog/introducing-grepai-skills.md

One-command installation for the grepai-skills collection. Works with Claude Code, Cursor, Windsurf, Codex, and 30+ other AI agents.

```bash
npx skills add yoanbernabeu/grepai-skills
```

--------------------------------

### Initialize and start grepai watch

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/watch-guide.md

Run `grepai init` to initialize grepai in your project, then start the watcher daemon with `grepai watch`. In interactive terminals, `grepai watch` opens a Bubble Tea monitoring UI by default (foreground mode).

```bash
# Initialize grepai in your project
grepai init

# Start the watcher daemon
grepai watch
```

--------------------------------

### Install grepai subagent with agent-setup

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/subagent.md

Run this command to create the deep-explore subagent configuration file `.claude/agents/deep-explore.md` in your project.

```bash
grepai agent-setup --with-subagent
```

--------------------------------

### Install Ollama for Local Embeddings

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/installation.md

Install Ollama for privacy-first local embeddings. Includes commands for macOS and Linux, starting the Ollama server, and pulling the embedding model.

```bash
# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama
ollama serve

# Pull the embedding model
ollama pull nomic-embed-text
```

--------------------------------

### grepai watch startup output

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/watch-guide.md

Example output from `grepai watch` showing the initial scan, symbol index build, and watching status. Includes provider, backend, and RPG status.

```text
Starting grepai watch in /path/to/project
Provider: ollama (nomic-embed-text)
Backend: gob
RPG: disabled

Performing initial scan...
Indexing [================] 100% (245/245) src/auth/handler.go
Initial scan complete: 245 files indexed, 1842 chunks created (took 45.2s)
Building symbol index...
Symbol index built: 3421 symbols extracted

Watching for changes... (Press Ctrl+C to stop)
```

--------------------------------

### Install Ollama (macOS and Linux)

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/backends/embedders.md

Install Ollama on macOS via Homebrew or on Linux via the install script.

```bash
# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh
```

--------------------------------

### Install grepai via Shell Script

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/installation.md

Install grepai on Linux or macOS using the official install script. This is recommended for Linux and an alternative for macOS.

```bash
curl -sSL https://raw.githubusercontent.com/yoanbernabeu/grepai/main/install.sh | sh
```

--------------------------------

### Install grepai via PowerShell

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/installation.md

Install grepai on Windows using PowerShell. Run this command in a PowerShell terminal.

```powershell
irm https://raw.githubusercontent.com/yoanbernabeu/grepai/main/install.ps1 | iex
```

--------------------------------

### grepai init git worktree examples

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/commands/grepai_init.md

Shows interactive and non-interactive usage of grepai init in a git worktree, with --inherit to skip prompts.

```bash
# Interactive: prompts to inherit
grepai init

# Non-interactive: inherit and skip all prompts
grepai init --inherit --yes
```

--------------------------------

### Install grepai-skills as Claude Code plugin

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/blog/introducing-grepai-skills.md

Adds the grepai-skills marketplace and installs the grepai-complete skill via Claude Code's plugin system.

```bash
/plugin marketplace add yoanbernabeu/grepai-skills
/plugin install grepai-complete@grepai-skills
```

--------------------------------

### Start MCP server with workspace flag

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/mcp.md

Command to start the grepai MCP server with a specific workspace, enabling cross-project search by default.

```bash
grepai mcp-serve --workspace my-fullstack
```

--------------------------------

### grepai rpg explore

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/rpg.md

Traverse dependencies around a starting node.

```APIDOC
## grepai rpg explore

### Description
Traverse dependencies around a starting node.

### Method
CLI command

### Endpoint
`grepai rpg explore <node_id>`

### Parameters
#### Path Parameters
- **node_id** (string) - Required - The starting node ID, e.g., `sym:cli/search.go:runSearch`.

#### Query Parameters
- **--direction** (string) - Optional - `forward`, `reverse`, or `both`.
- **--depth**, **-d** (integer) - Optional - BFS traversal depth.
- **--edge-types** (string) - Optional - Comma-separated edge types: `feature_parent`, `contains`, `invokes`, `imports`, `maps_to_chunk`, `semantic_sim`.
- **--limit**, **-n** (integer) - Optional - Maximum nodes to return.
- **--json** (flag) - Optional - Structured JSON output.
- **--toon**, **-t** (flag) - Optional - Token-efficient structured output.

### Request Example
```bash
grepai rpg explore "sym:cli/search.go:runSearch"
grepai rpg explore "sym:cli/search.go:runSearch" --direction forward --depth 1 --edge-types invokes --json
```

### Response
#### Success Response
Returns a list of traversed nodes.

#### Response Example
(No explicit response example provided in source.)
```

--------------------------------

### Commit Message Examples

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/contributing.md

Shows example commit messages following the conventional commit format for different types and scopes.

```text
feat(embedder): add support for Cohere embeddings
fix(watcher): handle symlink loops gracefully
docs(readme): update installation instructions
```

--------------------------------

### Full Configuration Reference (YAML)

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/configuration.md

Complete example of the .grepai/config.yaml file. It includes settings for the embedder (provider, model, endpoint, API key, dimensions, parallelism), vector store (backend, PostgreSQL, Qdrant), chunking (size, overlap, custom extensions), file watching (debounce, worktrees), call graph tracing (mode, enabled languages, exclude patterns), ignore patterns, and an external gitignore path. The API key uses the ${OPENAI_API_KEY} environment variable placeholder.

```yaml
# Config file version
version: 1

# Embedder configuration
embedder:
  # Provider: "ollama" (local), "lmstudio" (local), or "openai" (cloud)
  provider: ollama
  # Model name (depends on provider)
  model: nomic-embed-text
  # Endpoint URL (depends on provider, supports Azure OpenAI)
  endpoint: http://localhost:11434
  # API key (for OpenAI provider, use environment variable)
  api_key: ${OPENAI_API_KEY}
  # Vector dimensions (depends on model, auto-detected if not set)
  dimensions: 768
  # Concurrent batch requests for OpenAI (default: 4)
  parallelism: 4

# Vector store configuration
store:
  # Backend: "gob" (file-based), "postgres" (PostgreSQL with pgvector), or "qdrant"
  backend: gob

  # PostgreSQL settings (if using postgres backend)
  postgres:
    dsn: postgres://user:pass@localhost:5432/grepai

  # Qdrant settings (if using qdrant backend)
  qdrant:
    endpoint: localhost
    port: 6334
    use_tls: false
    collection: ""  # Optional, defaults to sanitized project path
    api_key: ""     # Optional, for Qdrant Cloud

# Chunking configuration
chunking:
  # Maximum tokens per chunk
  size: 512
  # Overlap between chunks (for context continuity)
  overlap: 50
  # Optional: index extra extensions beyond the built-in supported set.
  # Entries must include the leading dot, are matched case-insensitively,
  # and still go through the binary-file and minified-file filters.
  # Examples: ".tengo" (Tengo scripts), ".el" (Emacs Lisp), ".prisma".
  # custom_extensions:
  #   - .tengo
  #   - .prisma

# File watching configuration
watch:
  # Debounce delay in milliseconds
  debounce_ms: 500
  # Auto-discover and watch linked git worktrees (default: true).
  # Only read from the main worktree's config.
  discover_worktrees: true

# Call graph tracing configuration
trace:
  # Extraction mode: "fast" (regex) or "precise" (tree-sitter)
  mode: fast
  # File extensions to index for symbols
  enabled_languages:
    - .go
    - .js
    - .ts
    - .jsx
    - .tsx
    - .py
    - .php
    - .lua
    - .c
    - .h
    - .cpp
    - .hpp
    - .cc
    - .cxx
    - .hxx
    - .rs
    - .zig
    - .cs
    - .pas
    - .dpr
  # Patterns to exclude from symbol indexing
  exclude_patterns:
    - "*_test.go"
    - "*.spec.ts"

# Patterns to ignore (in addition to .gitignore)
ignore:
  - ".git"
  - ".grepai"
  - "node_modules"
  - "vendor"
  - "target"
  - ".zig-cache"
  - "zig-out"

# Path to an external gitignore file (e.g., global gitignore)
# Supports ~ expansion for home directory
external_gitignore: "~/.config/git/ignore"

```

--------------------------------

### Quick Start: Using grepai in a linked worktree

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/git-worktrees.md

Shows the typical workflow: set up the main project, create a linked worktree, and run grepai commands in the worktree without re-indexing. The index and symbols are copied automatically.

```bash
# Your main project already has grepai set up
cd /path/to/my-project
grepai watch  # index is built here

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

# grepai works immediately in the linked worktree
cd ../my-project-feature
grepai search "authentication flow"   # uses copied index
grepai trace callers "HandleRequest"   # uses copied symbols
```

--------------------------------

### TOON output format example

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/search-guide.md

Example of the TOON (Token-Oriented Object Notation) output, a compact format for AI agents. It uses a single-line object notation.

```text
[{file_path:middleware/auth.go,start_line:15,end_line:45,score:0.89,content:func AuthMiddleware() gin.HandlerFunc { ... }}]
```

--------------------------------

### Qdrant store configuration example

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/backends/stores.md

YAML configuration for the Qdrant backend with all options: endpoint, port, use_tls, collection, and api_key. Comments indicate defaults and optional fields.

```yaml
store:
  backend: qdrant
  qdrant:
    endpoint: "localhost"  # or "localhost" (scheme auto-detected from use_tls)
    port: 6334                 # gRPC port (default: 6334)
    use_tls: false               # Enable TLS (required for Qdrant Cloud)
    collection: "myproject"       # optional
    api_key: ""                 # optional (for Qdrant Cloud)
```

--------------------------------

### JSON output format example

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/search-guide.md

Example of the JSON array returned by grepai search with --json flag. Contains file_path, start_line, end_line, score, and content.

```json
[
  {
    "file_path": "middleware/auth.go",
    "start_line": 15,
    "end_line": 45,
    "score": 0.89,
    "content": "func AuthMiddleware() gin.HandlerFunc { ... }"
  }
]
```

--------------------------------

### Verify grepai Installation

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/installation.md

Check that grepai is installed and that Ollama is running (if using local embeddings).

```bash
# Check grepai is installed
grepai version

# Check Ollama is running (if using local embeddings)
curl http://localhost:11434/api/tags
```

--------------------------------

### Start the indexing daemon

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/quickstart.md

Run `grepai watch` to start the indexing daemon. In an interactive terminal, this opens the watch UI by default. Use `--no-ui` for plain output in scripts or logs.

```bash
grepai watch
```

```bash
grepai watch --no-ui
```

--------------------------------

### Enable pgvector extension

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/configuration.md

Required setup for PostgreSQL backend. Run this SQL command on your database.

```sql
CREATE EXTENSION vector;

```

--------------------------------

### Install grepai as Oh-My-Zsh plugin

Source: https://github.com/yoanbernabeu/grepai/blob/main/README.md

Creates a custom plugin directory for grepai and generates the completion script. Then add 'grepai' to the plugins array in ~/.zshrc.

```bash
mkdir -p ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/grepai
```

```bash
grepai completion zsh > ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/grepai/_grepai
```

```bash
# Then add "grepai" to plugins=(...) in ~/.zshrc
```

--------------------------------

### Configure grepai in project .mcp.json

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/mcp.md

Create a `.mcp.json` file at the project root to share the MCP configuration with the team. The first example uses default settings, the second adds workspace mode with `--workspace my-fullstack`.

```json
{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve"]
    }
  }
}
```

```json
{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve", "--workspace", "my-fullstack"]
    }
  }
}
```

--------------------------------

### Explicit Initialization with --inherit

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/git-worktrees.md

Initializes a worktree explicitly by copying the main worktree's configuration. Use --yes for non-interactive setup.

```bash
cd /path/to/my-worktree
grepai init --inherit
```

```bash
grepai init --inherit --yes
```

--------------------------------

### Example output of grepai search

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/quickstart.md

Example output from `grepai search "error handling middleware"` showing ranked results with scores and file locations.

```text
$ grepai search "error handling middleware"

Score: 0.89 | middleware/error.go:15-45
────────────────────────────────────────
func ErrorHandler() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Next()
        if len(c.Errors) > 0 {
            err := c.Errors.Last()
            // ... handle error
        }
    }
}

Score: 0.82 | handlers/api.go:78-95
────────────────────────────────────────
// handleAPIError wraps errors with context
func handleAPIError(w http.ResponseWriter, err error) {
    // ...
}
```

--------------------------------

### Install dependencies with go mod download

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/contributing.md

Downloads the Go module dependencies required for the project.

```bash
go mod download
```

--------------------------------

### Example grepai search commands

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/getting-started.md

Shows how to use grepai search to find code by describing its functionality, such as authentication, error handling, and database operations.

```bash
# Find authentication code without knowing function names
grepai search "user login validation"

# Find error handling patterns
grepai search "how are errors handled in API requests"

# Find database operations
grepai search "where are users saved to the database"
```

--------------------------------

### grepai search usage examples

Source: https://github.com/yoanbernabeu/grepai/blob/main/CLAUDE.md

Shows basic grepai search commands with English queries for best results, and JSON output for AI agents using --compact to save tokens.

```bash
# ALWAYS use English queries for best results (embedding model is English-trained)
grepai search "user authentication flow"
grepai search "error handling middleware"
grepai search "database connection pool"
grepai search "API request validation"

# JSON output for AI agents (--compact saves ~80% tokens by omitting content)
grepai search "authentication flow" --json --compact
```

--------------------------------

### grepai search: Understand codebase examples

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/search-guide.md

Use grepai search to find database interactions and API endpoints.

```bash
# Find database interactions
grepai search "database connection and queries"

# Locate API endpoints
grepai search "REST API route handlers"
```

--------------------------------

### grepai search: Find implementation examples

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/search-guide.md

Use grepai search to locate where specific logic is implemented, such as authentication or error handling.

```bash
# Where is authentication handled?
grepai search "user authentication logic"

# How are errors processed?
grepai search "error handling middleware"
```

--------------------------------

### Quick Start: watch, trace callers, callees, and graph

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/trace.md

Ensure watch is running to index symbols. Find callers of "Login", callees of "HandleRequest", and build a call graph with depth 3.

```bash
# Ensure watch is running to index symbols
grepai watch

# Find all functions that call "Login"
grepai trace callers "Login"

# Find all functions called by "HandleRequest"
grepai trace callees "HandleRequest"

# Build a call graph with depth 3
grepai trace graph "ProcessOrder" --depth 3
```

--------------------------------

### grepai search quick start commands

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/search-guide.md

Basic commands to search codebase using natural language. Ensure watch is running to index code. Use --limit to limit results, --path to filter by path prefix, and --json --compact for token-efficient JSON output.

```bash
# Ensure watch is running to index your code
grepai watch

# Search for authentication code
grepai search "user authentication flow"

# Limit results
grepai search "error handling" --limit 5

# Filter by path prefix
grepai search "authentication" --path src/handlers/
grepai search "validation" --path src/middleware/ --limit 10

# JSON output for AI agents (--compact saves ~80% tokens)
grepai search "database queries" --json --compact
```

--------------------------------

### Real-time update logs for file changes

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/watch-guide.md

Example logs from the watcher when files are modified, created, or deleted, showing indexing and symbol extraction results.

```text
[MODIFY] src/auth/handler.go
Indexed src/auth/handler.go (4 chunks)
Extracted 12 symbols from src/auth/handler.go

[CREATE] src/api/routes.go
Indexed src/api/routes.go (3 chunks)
Extracted 8 symbols from src/api/routes.go

[DELETE] src/old/deprecated.go
Removed src/old/deprecated.go from index
```

--------------------------------

### CI/CD integration: one-time index and search

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/watch-guide.md

For CI environments, run a one-time index by starting the watcher in the background, waiting for initial indexing, then searching with JSON output.

```bash
grepai watch &
sleep 60  # Wait for initial indexing
grepai search "security vulnerabilities" --json --compact
```

--------------------------------

### Explore RPG neighborhoods with grepai rpg explore

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/rpg.md

Commands to traverse dependencies around a starting node. Supports direction, depth, edge types, and JSON output.

```bash
grepai rpg explore "sym:cli/search.go:runSearch"
grepai rpg explore "sym:cli/search.go:runSearch" --direction forward --depth 1 --edge-types invokes --json

```

--------------------------------

### Run workspace watchers for active development

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/blog/multi-project-workspace.md

Commands to start watchers for Product A in the background, check status, run Product B in the foreground for debugging, and continue using the legacy tool unchanged.

```bash
# Product A - background daemon
grepai watch --workspace product-a --background

# Check status
grepai watch --workspace product-a --status

# Product B - foreground for debugging
grepai watch --workspace product-b

# Legacy tool - unchanged
cd ~/projects/legacy-tool && grepai watch --background
```

--------------------------------

### Initialize grepai

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/quickstart.md

Navigate to your project directory and run `grepai init` to create a `.grepai/` directory with a `config.yaml` file.

```bash
cd /path/to/your/project
grepai init
```

--------------------------------

### JSON Output Format Example

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/trace.md

Shows the output format for `grepai trace callers "Login" --json`. The response includes query, mode, count, and results with file, line, caller, and context.

```json
{
  "query": "Login",
  "mode": "callers",
  "count": 3,
  "results": [
    {
      "file": "handlers/auth.go",
      "line": 42,
      "caller": "HandleAuth",
      "context": "user.Login(ctx, credentials)"
    }
  ]
}
```

--------------------------------

### Install PostgreSQL with pgvector

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/backends/stores.md

Commands to install PostgreSQL and pgvector on macOS with Homebrew and on Ubuntu/Debian with apt. For Ubuntu, pgvector must be installed from source or package after installing PostgreSQL.

```bash
# macOS with Homebrew
brew install postgresql pgvector

# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib
# Then install pgvector from source or package
```

--------------------------------

### grepai init options

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/commands/grepai_init.md

Lists all available flags for grepai init, including backend, provider, inherit, ui, and yes.

```bash
  -b, --backend string    Storage backend (gob, postgres, or qdrant)
  -h, --help              help for init
      --inherit           Inherit configuration from main worktree (for git worktrees)
  -p, --provider string   Embedding provider (ollama, lmstudio, or openai)
      --ui                Run interactive Bubble Tea UI wizard
      --yes               Use defaults without prompting
```

--------------------------------

### Verify grepai installation with which grepai

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/mcp.md

Use this command to check if grepai is installed and accessible in your PATH. If it is not found, ensure it is installed and added to your PATH.

```bash
which grepai
```

--------------------------------

### Build the project

Source: https://github.com/yoanbernabeu/grepai/blob/main/CONTRIBUTING.md

Build the project using make or directly with go build.

```bash
make build
# or
go build ./cmd/grepai
```

--------------------------------

### grepai init command synopsis

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/commands/grepai_init.md

Shows the basic usage of the grepai init command with optional flags.

```bash
grepai init [flags]
```

--------------------------------

### Initialize grepai with Qdrant backend

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/backends/stores.md

Command to initialize grepai with the Qdrant backend.

```bash
grepai init --backend qdrant
```

--------------------------------

### Clone and enter the repository

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/contributing.md

Clone the repository from your fork and navigate into the project directory.

```bash
git clone https://github.com/YOUR_USERNAME/grepai.git
cd grepai
```

--------------------------------

### Build and Development Commands

Source: https://github.com/yoanbernabeu/grepai/blob/main/CLAUDE.md

Make targets for building, testing, linting, running, and cross-compiling the grepai binary. Use these commands during development.

```bash
# Build the binary
make build

# Run tests with race detection
make test

# Run tests with coverage report
make test-cover

# Lint with golangci-lint
make lint

# Build and run
make run

# Cross-compile for all platforms
make build-all
```

--------------------------------

### grepai watch background commands

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/watch-guide.md

Commands to start, check, and stop the background watcher. The --background flag starts the daemon, --status checks if it is running, and --stop gracefully stops it.

```bash
# Start the watcher in background
grepai watch --background

# Check if the watcher is running
grepai watch --status

# Stop the background watcher gracefully
grepai watch --stop
```

--------------------------------

### Build the project with make build

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/contributing.md

Builds the project binary using the Makefile target.

```bash
make build
```

--------------------------------

### Migrate to workspace with grepai CLI

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/workspace.md

Commands to create a workspace, add projects, optionally clean old chunks, and re-index via workspace. Use the same DSN as existing projects. Cleaning old chunks is optional but recommended to avoid duplicate search results.

```bash
# 1. Create workspace pointing to the SAME PostgreSQL database
grepai workspace create my-workspace
# Use the same DSN as your existing projects

# 2. Add projects
grepai workspace add my-workspace /path/to/frontend
grepai workspace add my-workspace /path/to/backend

# 3. (Optional) Clean old non-prefixed chunks from database
# Old chunks don't have the workspace prefix pattern
psql -d your_db -c "DELETE FROM chunks WHERE file_path NOT LIKE '%/%/%';"

# 4. Re-index via workspace
grepai watch --workspace my-workspace
```

--------------------------------

### grepai_index_status tool usage

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/mcp.md

Example of how an AI agent can call the grepai_index_status tool with no arguments.

```text
Tool: grepai_index_status
Arguments: {}
```

--------------------------------

### grepai_trace_callers tool usage

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/mcp.md

Example of how an AI agent can call the grepai_trace_callers tool with a symbol.

```text
Tool: grepai_trace_callers
Arguments: {"symbol": "HandleLogin"}
```

--------------------------------

### Create and populate workspaces for Product A and Product B

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/blog/multi-project-workspace.md

Commands to create two grepai workspaces (product-a and product-b) and add their respective projects. Note that shared-auth is added to both workspaces, and each workspace maintains its own index with unique prefixes.

```bash
# Workspace for Product A
grepai workspace create product-a
# Select: PostgreSQL, Ollama with nomic-embed-text

grepai workspace add product-a ~/projects/ecommerce-frontend
grepai workspace add product-a ~/projects/ecommerce-api
grepai workspace add product-a ~/projects/shared-auth

# Workspace for Product B
grepai workspace create product-b
# Select: PostgreSQL (same or different DSN), Ollama

grepai workspace add product-b ~/projects/admin-frontend
grepai workspace add product-b ~/projects/admin-api
grepai workspace add product-b ~/projects/shared-auth
```

--------------------------------

### Run linter

Source: https://github.com/yoanbernabeu/grepai/blob/main/CONTRIBUTING.md

Run the linter using make.

```bash
make lint
```

--------------------------------

### grepai_search tool usage

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/mcp.md

Example of how an AI agent can call the grepai_search tool with a query and limit.

```text
Tool: grepai_search
Arguments: {"query": "user authentication flow", "limit": 5}
```

--------------------------------

### grepai_rpg_search tool usage

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/mcp.md

Example of how an AI agent can call the grepai_rpg_search tool with a query, kinds, and limit.

```text
Tool: grepai_rpg_search
Arguments: {"query": "command line search flow", "kinds": "symbol,file", "limit": 5}
```

--------------------------------

### Create workspace with PostgreSQL backend

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/workspace.md

Use this command to create a workspace with a shared backend. Select PostgreSQL when prompted.

```bash
# Create workspace with PostgreSQL
grepai workspace create my-workspace
# Select PostgreSQL when prompted
```

--------------------------------

### Indexing commands

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/blog/multi-project-workspace.md

Commands to start the workspace watcher in foreground or background, check daemon status, and stop the daemon.

```bash
# Start workspace watcher (foreground)
grepai watch --workspace <name>

# Background daemon
grepai watch --workspace <name> --background

# Check daemon status
grepai watch --workspace <name> --status

# Stop daemon
grepai watch --workspace <name> --stop
```

--------------------------------

### Enable Bash shell completion for grepai on macOS

Source: https://github.com/yoanbernabeu/grepai/blob/main/README.md

Generates the Bash completion script and writes it to the Homebrew prefix. Requires bash-completion@2 to be installed.

```bash
# macOS (requires bash-completion@2)
grepai completion bash > $(brew --prefix)/etc/bash_completion.d/grepai
```

--------------------------------

### Run tests

Source: https://github.com/yoanbernabeu/grepai/blob/main/CONTRIBUTING.md

Run the test suite using make or go test with race detection.

```bash
make test
# or
go test -v -race ./...
```

--------------------------------

### Create PostgreSQL database and vector extension

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/backends/stores.md

SQL commands to create the 'grepai' database, connect to it, and enable the pgvector extension.

```sql
CREATE DATABASE grepai;
\c grepai
CREATE EXTENSION vector;
```

--------------------------------

### Update grepai via Shell Script or Binary

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/installation.md

Check for available updates and download/install the latest version if installed via shell script or binary.

```bash
# Check for available updates
grepai update --check

# Download and install the latest version
grepai update
```

--------------------------------

### List and show workspace configuration

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/workspace.md

Use these commands to check workspace configuration when a workspace is not found.

```bash
grepai workspace list
grepai workspace show my-workspace
```

--------------------------------

### New Store Template (Go)

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/contributing.md

Template for creating a new store in the store/ directory. Implements the Store interface with Store, Search, Delete, and Close methods.

```go
// store/mystore.go
package store

type MyStore struct {
    // ...
}

func NewMyStore(config Config) (*MyStore, error) {
    // ...
}

func (s *MyStore) Store(ctx context.Context, chunks []Chunk) error {
    // ...
}

func (s *MyStore) Search(ctx context.Context, embedding []float32, limit int) ([]Result, error) {
    // ...
}

func (s *MyStore) Delete(ctx context.Context, filePath string) error {
    // ...
}

func (s *MyStore) Close() error {
    // ...
}

```

--------------------------------

### grepai_rpg_explore

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/mcp.md

Traverses an RPG graph neighborhood. Accepts a start node ID and optional parameters for direction, depth, edge types, limit, and format.

```APIDOC
## grepai_rpg_explore

### Description
Traverses an RPG graph neighborhood.

### Parameters
- **start_node_id** (string) - Required - The ID of the starting node.
- **direction** (string) - Optional - Direction of traversal.
- **depth** (number) - Optional - Depth of traversal.
- **edge_types** (string) - Optional - Types of edges to traverse.
- **limit** (number) - Optional - Maximum number of results.
- **format** (string) - Optional - Output format: `json` or `toon`.

### Response
Returns neighborhood data in the specified format.
```

--------------------------------

### Create feature branch from main

Source: https://github.com/yoanbernabeu/grepai/blob/main/CLAUDE.md

Commands to create a feature branch from main, following the naming convention <type>/<issue-number>-<short-description>. Example: feat/42-add-new-embedder.

```bash
git checkout main
git pull origin main
git checkout -b <type>/<issue-number>-<short-description>
# Example: feat/42-add-new-embedder
```

--------------------------------

### Override log directory with --log-dir

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/watch-guide.md

Commands to start, check, and stop the background watcher with a custom log directory using the --log-dir flag.

```bash
grepai watch --background --log-dir /custom/path
grepai watch --status --log-dir /custom/path
grepai watch --stop --log-dir /custom/path
```

--------------------------------

### Example search result output

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/search-guide.md

Shows the format of a search result with score, file location, and code content. Score is relevance (0.0-1.0), higher is better.

```text
Score: 0.89 | middleware/auth.go:15-45
----------------------------------------
func AuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        // ... validate token
    }
}
```

--------------------------------

### Override Config via Environment

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/configuration.md

Shows how to override configuration settings using environment variables.

```bash
export GREPAI_EMBEDDER_PROVIDER=openai
export GREPAI_STORE_BACKEND=postgres
```

--------------------------------

### How grepai watch works (ASCII diagram)

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/watch-guide.md

ASCII diagram showing the pipeline: Initial Scan -> File Watcher -> Index Update, with debouncing (500ms) applied to file watcher events.

```text
+------------------+     +------------------+     +------------------+
|   Initial Scan   | --> |   File Watcher   | --> |  Index Update    |
|   (full index)   |     |   (fsnotify)     |     |  (incremental)   |
+------------------+     +------------------+     +------------------+
                                |
                                v
                        +------------------+
                        |   Debouncing     |
                        |   (500ms)        |
                        +------------------+
```

--------------------------------

### Re-index after model change

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/backends/embedders.md

After changing the embedding model, you must re-index because embeddings from different models are incompatible. This command removes the existing index files and starts the watch process.

```bash
rm -rf .grepai/index.gob .grepai/symbols.gob
grepai watch
```

--------------------------------

### Build full dependency chain with grepai trace graph

Source: https://github.com/yoanbernabeu/grepai/blob/main/docs/src/content/docs/trace.md

Use `grepai trace graph` with `--depth 4` to get a full dependency chain for a critical function.

```bash
# Full dependency chain for a critical function
grepai trace graph "DatabaseConnect" --depth 4
```
Tokens:
Raw