GrepAI Configuration Reference

This skill provides a complete reference for all GrepAI configuration options in .grepai/config.yaml .

When to Use This Skill

• Understanding all available configuration options

• Optimizing GrepAI for your specific use case

• Troubleshooting configuration issues

• Setting up advanced configurations

Configuration File Location

/your/project/.grepai/config.yaml

Complete Configuration Schema

version: 1

═══════════════════════════════════════════════════════════════

EMBEDDER CONFIGURATION

Converts code text into vector embeddings

═══════════════════════════════════════════════════════════════

embedder:

Provider: ollama | openai | lmstudio

provider: ollama

Model name (depends on provider)

Ollama: nomic-embed-text, bge-m3, mxbai-embed-large

OpenAI: text-embedding-3-small, text-embedding-3-large

LM Studio: nomic-embed-text-v1.5, bge-small-en-v1.5

model: nomic-embed-text

API endpoint URL

Ollama default: http://localhost:11434

LM Studio default: http://localhost:1234

OpenAI: uses official API

endpoint: http://localhost:11434

Vector dimensions (auto-detected if omitted)

nomic-embed-text: 768

text-embedding-3-small: 1536

text-embedding-3-large: 3072

dimensions: 768

API key (for OpenAI, supports env vars)

api_key: ${OPENAI_API_KEY}

Parallel requests (OpenAI only, for speed)

parallelism: 4

═══════════════════════════════════════════════════════════════

STORE CONFIGURATION

Where vector embeddings are stored

═══════════════════════════════════════════════════════════════

store:

Backend: gob | postgres | qdrant

backend: gob

PostgreSQL configuration (when backend: postgres)

postgres: dsn: postgres://user:password@localhost:5432/grepai

Qdrant configuration (when backend: qdrant)

qdrant: endpoint: localhost port: 6334 use_tls: false api_key: your-qdrant-api-key # Optional

═══════════════════════════════════════════════════════════════

CHUNKING CONFIGURATION

How code files are split for embedding

═══════════════════════════════════════════════════════════════

chunking:

Tokens per chunk (smaller = more precise, larger = more context)

Recommended: 256-1024

size: 512

Overlap between chunks (preserves context at boundaries)

Recommended: 10-20% of size

overlap: 50

═══════════════════════════════════════════════════════════════

WATCH CONFIGURATION

File watching daemon settings

═══════════════════════════════════════════════════════════════

watch:

Debounce delay in milliseconds

Groups rapid file changes together

debounce_ms: 500

═══════════════════════════════════════════════════════════════

TRACE CONFIGURATION

Call graph analysis settings

═══════════════════════════════════════════════════════════════

trace:

Extraction mode: fast | precise

fast: Uses regex, no dependencies, faster

precise: Uses tree-sitter AST parsing, more accurate

mode: fast

Languages to analyze for call graphs

enabled_languages: - .go - .js - .ts - .jsx - .tsx - .py - .php - .c - .h - .cpp - .hpp - .cc - .cxx - .rs - .zig - .cs - .pas - .dpr

Patterns to exclude from trace analysis

exclude_patterns: - "_test.go" - ".spec.ts" - "*.test.js"

═══════════════════════════════════════════════════════════════

SEARCH CONFIGURATION

Search result scoring and ranking

═══════════════════════════════════════════════════════════════

search:

Score boosting configuration

boost: enabled: true

# Reduce scores for certain paths
penalties:
  - pattern: /tests/
    factor: 0.5
  - pattern: _test.
    factor: 0.5
  - pattern: .spec.
    factor: 0.5
  - pattern: /docs/
    factor: 0.6
  - pattern: /vendor/
    factor: 0.3
  - pattern: /node_modules/
    factor: 0.3

# Increase scores for certain paths
bonuses:
  - pattern: /src/
    factor: 1.1
  - pattern: /lib/
    factor: 1.1
  - pattern: /core/
    factor: 1.2
  - pattern: /app/
    factor: 1.1

Hybrid search (vector + keyword)

hybrid: enabled: false k: 60 # BM25 parameter

═══════════════════════════════════════════════════════════════

IGNORE CONFIGURATION

Files and directories to exclude from indexing

═══════════════════════════════════════════════════════════════

ignore:

Directories

• .git
• .grepai
• .svn
• .hg
• node_modules
• vendor
• target
• pycache
• .pytest_cache
• dist
• build
• out
• .next
• .nuxt

Files

• "*.min.js"
• "*.min.css"
• "*.bundle.js"
• "*.map"
• "*.lock"
• package-lock.json
• yarn.lock
• pnpm-lock.yaml
• go.sum

Generated

• ".generated."
• "*.pb.go"
• "*.d.ts"

Configuration by Use Case

Small Personal Project

version: 1 embedder: provider: ollama model: nomic-embed-text store: backend: gob chunking: size: 512 overlap: 50

Large Codebase

version: 1 embedder: provider: ollama model: bge-m3 # Larger model parallelism: 4 store: backend: postgres # Scalable storage postgres: dsn: postgres://user:pass@localhost:5432/grepai chunking: size: 768 # Larger chunks overlap: 100

Team Environment

version: 1 embedder: provider: openai model: text-embedding-3-small api_key: ${OPENAI_API_KEY} parallelism: 8 store: backend: qdrant qdrant: endpoint: qdrant.internal.company.com port: 6334 use_tls: true

Maximum Privacy

version: 1 embedder: provider: ollama model: nomic-embed-text endpoint: http://localhost:11434 store: backend: gob # Local file only

Environment Variables

GrepAI supports environment variable substitution:

embedder: api_key: ${OPENAI_API_KEY}

store: postgres: dsn: ${DATABASE_URL}

Set in your shell:

export OPENAI_API_KEY="sk-..." export DATABASE_URL="postgres://..."

Validating Configuration

Check your config is valid:

grepai status

If there are config errors, they'll be displayed.

Configuration Precedence

• .grepai/config.yaml in current directory

• Workspace configuration (if using workspaces)

• Default values

Best Practices

• Start simple: Use defaults, optimize later

• Match chunking to code style: Larger chunks for verbose code

• Use boosting: Penalize test/vendor, boost src/lib

• Secure API keys: Use environment variables, never commit

• Exclude noise: Ignore generated files, dependencies

Output Format

Valid configuration status:

✅ GrepAI Configuration Valid

Embedder: ollama (nomic-embed-text) Storage: gob (.grepai/index.gob) Chunking: 512 tokens, 50 overlap Trace mode: fast Languages: 18 enabled Ignore patterns: 12 configured Boosting: enabled