grepai — set up semantic search

sonnet session

Prerequisites

Run /brewcode:setup first — it installs Homebrew, Ollama, and grepai CLI automatically in Phase 0.

Environment

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

Quick reference

FieldValue
Command/brewcode:grepai
Arguments[setup|status|start|stop|reindex|optimize|upgrade]
Modelsonnet
Contextsession
ToolsRead, Write, Edit, Bash, Task, AskUserQuestion

When to use

SituationCommand
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

  1. 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.

  2. 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.

  3. MCP configuration

    Configures the grepai MCP server entry in .claude/settings.json and adds mcp__grepai__* to allowedTools. Required once per project.

  4. 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.

  5. 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.

  6. 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.

  7. 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 argsMODE
upgradeupgrade
optimize, updateoptimize
stop, halt, killstop
start, watchstart
status, doctor, check, healthstatus
setup, configure, initsetup
reindex, rebuild, refreshreindex
(empty) + .grepai/ existsstart
(empty) + no .grepai/setup
(unrecognized text)interactive prompt

Scripts executed per mode

ModeScript(s)
setupinfra-check.sh → mcp-check.sh → bc-grepai-configurator → init-index.sh → create-rule.sh → verify.sh
statusstatus.sh
startstart.sh
stopstop.sh
reindexreindex.sh (stop → clean → rebuild → restart)
optimizeoptimize.sh (backup) → bc-grepai-configurator → reindex.sh
upgradeupgrade.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.

🤖

bc-grepai-configurator

The opus agent that analyzes your project and generates the optimal .grepai/config.yaml.

📄

setup skill

Run setup first — it installs all prerequisites including Ollama and grepai CLI.

🔗

Source on GitHub

Skill scripts, SKILL.md, and configuration templates.

🚀

brewcode overview

Full plugin overview — all skills and agents in one place.

Updating plugins

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