bc-grepai-configurator

Caution

grepai without a tuned config wastes cycles and returns noise. Default chunking is too small for Java/Kotlin, hybrid search is off, and test files compete with production code in results. Parallelism defaults may trigger the Ollama concurrency bug and stall indexing silently.

Tip

Trigger the agent with natural language. Say "configure grepai" or "setup grepai index" and it handles the rest — infrastructure check, language detection, config generation, MCP wiring, and verification. Assumes grepai and Ollama are already installed.

Quick reference

Field	Value
Model	opus
Tools	Read, Write, Edit, Bash, WebFetch, Glob, Grep
Permission mode	acceptEdits
Triggers	”configure grepai”, “grepai config”, “analyze for grepai”, “setup grepai index”
Scope	Config generation only — does not install grepai or Ollama

When to use

New project — generate .grepai/config.yaml from scratch after cloning or creating a repo
Wrong search results — test files outranking production code, or queries returning unrelated modules
Language mismatch — chunking and trace settings need tuning after adding Java/Kotlin to a JS/TS repo
After embedder switch — switching from bge-m3 to mxbai-embed-large requires a full index reset
MCP not wired — grepai_search tool missing from Claude Code after installation

Examples

configure grepai

setup grepai index for this Spring Boot monorepo

analyze for grepai — I have embedded SQL in JDBC repositories

Flow

Infrastructure check
Verifies grepai binary, Ollama daemon, and the bge-m3 embedder model. Stops with a clear error if any component is missing — no partial config written.
Project analysis
Runs Glob and Grep in parallel: detects build files (pom.xml, build.gradle, package.json), test directories, generated code paths, and embedded SQL patterns. Produces a structured analysis used in the next phase.
Config generation
Writes .grepai/config.yaml with language-tuned chunking, search boost rules (penalties for tests/generated code, bonuses for core/main), hybrid search for JVM stacks, and trace settings scoped to detected extensions only. Strips watch.last_index_time to avoid the index-skip bug.
MCP wiring
Checks for an existing grepai MCP entry in .mcp.json (project) or ~/.claude.json (global). If missing, shows the exact JSON block and the one-liner: claude mcp add grepai — grepai mcp-serve.
Verification
Confirms config exists, runs a test search, checks index size, and reports MCP status. Prints an indexed summary table — infrastructure, analysis, config settings, and next steps.

Internals — config.yaml template + phase details

Generated config.yaml skeleton:

version: 1

embedder:
  provider: ollama
  model: bge-m3
  endpoint: http://localhost:11434
  dimensions: 1024
  parallelism: 1          # Always 1 — Ollama concurrency bug #12591

store:
  backend: gob

chunking:
  size: 512               # 768-1024 for Java/Kotlin
  overlap: 50             # 75-100 for Java/Kotlin

watch:
  debounce_ms: 500
  # last_index_time: NEVER include — causes file-skip bug

search:
  boost:
    enabled: true
    penalties:
      # Tests: 0.5, Mocks: 0.4, Generated: 0.4
    bonuses:
      # Main source: 1.1, Core/domain: 1.2
  hybrid:
    enabled: false        # true for Java/Kotlin
    k: 60

trace:
  mode: fast
  enabled_languages:
    # Only extensions detected in Phase 2
  exclude_patterns:
    # Test file patterns from Phase 2

update:
  check_on_startup: false

ignore:
  - .git
  - .grepai
  # Project-specific from .gitignore analysis

Embedded SQL detection (Phase 2): Grep pattern JdbcTemplate|NamedParameterJdbcTemplate|@Query|String sql|"""\s*SELECT → sets HAS_EMBEDDED_SQL. When true, adds a warning header to config.yaml and the verify phase runs grepai trace callers instead of trace_graph to avoid the 2000+ false-edge explosion.

Chunking by stack:

Stack	size	overlap
Java/Kotlin (Spring, JPA)	768–1024	75–100
TypeScript (React, NestJS)	512–768	50–75
JavaScript (Node)	512	50
SQL migrations	384	40

Embedder options:

Model	Dims	RAM	Best for
`bge-m3` (default)	1024	1.5 GB	Multilingual
`mxbai-embed-large`	1024	1 GB	English, max accuracy
`nomic-embed-text`	768	500 MB	Fast, small repos

🔍

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.