From 792d46d4b8ec9a6c223c0845808ee0752bed0071 Mon Sep 17 00:00:00 2001
From: Florian BRUNIAUX <florian@bruniaux.com>
Date: Thu, 15 Jan 2026 15:31:23 +0100
Subject: [PATCH] docs(mcp): add grepai vs grep/rg benchmark comparison

- Add "Performance vs Traditional Tools" section with timing comparison
- Update decision tree with "Know exact pattern?" branch
- Update Server Comparison table with exact match recommendation
- Document key insight: grepai finds what pattern-based tools cannot

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CHANGELOG.md            |  5 +++++
 guide/ultimate-guide.md | 28 +++++++++++++++++++++++++---
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 48450b1..f244695 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -30,6 +30,11 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   - Source: [grepai GitHub](https://github.com/yoanbernabeu/grepai)
 - Updated MCP server decision tree and comparison table to include grepai
 - Added grepai configuration to `examples/config/mcp.json`
+- **grepai vs grep/rg benchmark comparison** in Section 8.4
+  - Performance comparison table: rg (~20ms) vs grep (~45ms) vs grepai (~500ms)
+  - Key insight documented: grepai finds what pattern-based tools cannot
+  - Decision tree updated with "Know exact pattern?" branch (use rg/Grep)
+  - Server Comparison table updated with exact match recommendation
 
 ---
 
diff --git a/guide/ultimate-guide.md b/guide/ultimate-guide.md
index 0f7b9f4..c4d5060 100644
--- a/guide/ultimate-guide.md
+++ b/guide/ultimate-guide.md
@@ -5155,6 +5155,24 @@ grepai watch &
 - Privacy is required (no cloud, all local)
 - Need to trace "who calls what" across the codebase
 
+**Performance vs Traditional Tools**:
+
+| Search Type | Tool | Time | Results |
+|-------------|------|------|---------|
+| Exact match | `rg` (ripgrep) | ~20ms | Exact hits only |
+| Exact match | `grep` | ~45ms | Exact hits only |
+| Semantic | `grepai` | ~500ms | Intent-based matches |
+
+**Key insight**: grepai is ~25x slower than rg for exact matches, but finds results that pattern-based tools cannot discover.
+
+```bash
+# Know exact pattern → use rg (fast)
+rg "createSession" --type ts
+
+# Don't know exact name → use grepai (semantic)
+grepai search "session creation logic"
+```
+
 > **Source**: [grepai GitHub](https://github.com/yoanbernabeu/grepai)
 
 ### Context7 (Documentation Lookup)
@@ -5299,11 +5317,14 @@ claude mcp add --help
 ```
 What do you need?
 │
+├─ Know exact pattern/text?
+│  └─ Use native Grep tool or rg (~20ms)
+│
 ├─ Deep code understanding?
 │  └─ Use Serena
 │
 ├─ Explore code by intent / semantic search?
-│  └─ Use grepai
+│  └─ Use grepai (~500ms)
 │
 ├─ Trace who calls what? (call graph)
 │  └─ Use grepai
@@ -5326,8 +5347,9 @@ What do you need?
 
 ### Server Comparison
 
-| Need | Best Server | Why |
-|------|-------------|-----|
+| Need | Best Tool | Why |
+|------|-----------|-----|
+| "Find exact string 'validateUser'" | Native Grep / rg | Fast exact match (~20ms) |
 | "Find all usages of this function" | Serena | Semantic symbol analysis |
 | "Remember this for next session" | Serena | Persistent memory |
 | "Find code that handles payments" | grepai / mgrep | Intent-based semantic search |