grepai — set up semantic search

sonnet session

Prerequisites

Run /brewcode:grepai setup — it checks/installs Homebrew, Ollama, and the grepai CLI, builds the index, and self-installs the grepai hooks into your project.

Self-install hooks

setup mode detects whether grepai hooks are present in your project. If not, it copies grepai-session.mjs (SessionStart auto-start/health) and grepai-reminder.mjs (PreToolUse:Bash reminder) from the plugin’s skills/grepai/assets/ into .claude/grepai/hooks/, then merges the SessionStart and PreToolUse:Bash entries into .claude/settings.json using jq (python3 fallback, no-clobber, idempotent). A summary of created files is printed when done.

Environment

Ollama + bge-m3 model · GOB on-disk index · Java / Kotlin / JS / TS projects

Quick reference

Field	Value
Command	`/brewcode:grepai`
Arguments	`[setup\|status\|start\|stop\|reindex\|optimize\|upgrade]`
Model	sonnet
Context	session
Tools	Read, Write, Edit, Bash, Task, AskUserQuestion

When to use

Situation	Command
First-time setup on a new project	`/brewcode:grepai setup`
Check index health and watch status	`/brewcode:grepai status`
Resume watch after restart	`/brewcode:grepai start`
Stop the background watch process	`/brewcode:grepai stop`
Rebuild stale index after large refactor	`/brewcode:grepai reindex`
Tune boost patterns, update trace languages	`/brewcode:grepai optimize`
Update grepai CLI via Homebrew	`/brewcode:grepai upgrade`
Not sure which mode	`/brewcode:grepai` (interactive prompt)

Examples

First-time setup

/brewcode:grepai setup

The skill runs infra-check, configures MCP, spawns bc-grepai-configurator to generate .grepai/config.yaml, then builds the initial index synchronously (10–30 min on large repos).

Daily health check

/brewcode:grepai status

Reports grepai CLI version, Ollama state, bge-m3 model, MCP connection, index size, watch process, and rule presence.

Rebuild after a major merge

/brewcode:grepai reindex

Stops watch, wipes the index, rebuilds from scratch, restarts watch. Monitor with tail -f .grepai/logs/grepai-watch.log.

Flow

Mode detection
The skill runs detect-mode.sh against $ARGUMENTS. Keywords like setup, start, status map to modes; empty args auto-detect from whether .grepai/ exists; unrecognized text falls back to interactive prompt.
Infra check (setup/optimize)
Verifies Homebrew, Ollama daemon, bge-m3 model download, and grepai CLI. Stops with a clear error if any component is missing.
MCP configuration
Configures the grepai MCP server entry in .claude/settings.json and adds mcp__grepai__* to allowedTools. Required once per project.
Config generation — bc-grepai-configurator agent
The bc-grepai-configurator agent (opus) analyzes build files, source layout, and test patterns to produce an optimal .grepai/config.yaml with boost weights and trace-language settings.
Index build
Runs init-index.sh synchronously. Embeds all source files via bge-m3 and writes GOB shards to .grepai/. Large repos (5k+ files) take 10–30 min — monitor the log.
Rule creation
Writes a .claude/rules/grepai-first.md rule so Claude always reaches for grepai_search / trace_callers / trace_callees before Glob or Grep.
Verification
Runs verify.sh — confirms MCP responds, index is readable, and the rule file exists. Prints a status table with ✅/❌ per component.

Config schema & internals

Mode detection table

Keyword in args	MODE
`upgrade`	upgrade
`optimize`, `update`	optimize
`stop`, `halt`, `kill`	stop
`start`, `watch`	start
`status`, `doctor`, `check`, `health`	status
`setup`, `configure`, `init`	setup
`reindex`, `rebuild`, `refresh`	reindex
(empty) + `.grepai/` exists	start
(empty) + no `.grepai/`	setup
(unrecognized text)	interactive prompt

Scripts executed per mode

Mode	Script(s)
setup	`infra-check.sh` → `mcp-check.sh` → bc-grepai-configurator → `init-index.sh` → `create-rule.sh` → `verify.sh`
status	`status.sh`
start	`start.sh`
stop	`stop.sh`
reindex	`reindex.sh` (stop → clean → rebuild → restart)
optimize	`optimize.sh` (backup) → bc-grepai-configurator → `reindex.sh`
upgrade	`upgrade.sh` (brew upgrade)

Status output format

The skill always prints a status table after any mode completes:

| Component    | Status              |
|--------------|---------------------|
| grepai CLI   | ✅ v0.x.y           |
| ollama       | ✅ running          |
| bge-m3 model | ✅ loaded           |
| MCP          | ✅ connected        |
| Permissions  | ✅ allowedTools set |
| .grepai/     | ✅ exists           |
| index        | 12 shards / 4.2 GB  |
| watch        | ✅ running (PID 789)|
| rule         | ✅ grepai-first.md  |

Long-running operations warning

setup (Phase 4) and reindex run the embedding pass synchronously. On repos with 5 000+ files, expect 10–30 minutes. The process writes progress to .grepai/logs/grepai-watch.log.

📄

Updating plugins

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