v1.7.0 — Curated-Docs Search Lane + Recovery Ladder

Two feature waves since the last release (v1.4.0): a smarter recovery ladder that escalates failed regex searches automatically, and a new curated-docs search lane that surfaces a repo's learnings/, docs/, and git-tracked README/CLAUDE/MEMORY files alongside your session history.

What's New

Curated-docs search lane

One command now covers both "what did we discuss" (sessions) and "what's the documented gotcha" (curated notes):

• Searches the cwd repo's learnings/ then docs/ (or CLAUDE_GREP_DOCS=dir1:dir2), plus every git-tracked README.md / CLAUDE.md / MEMORY.md at any depth.
• Each hit is a navigable file:line § heading pointer — jump straight to it.
• -s fuses a dense embedding lane with a BM25 keyword lane via reciprocal-rank fusion. Keyword lane needs no index, so doc search still works when Ollama is down.
• New flags: --docs-only (head-safe, no session scan), --no-docs, --index --docs, --bench-docs, --mine-docs-queries.

Recovery ladder

When a regex returns nothing, claude-grep escalates automatically — within your chosen scope, never widening -a/-d:

1. regex as typed
2. tokenized — multi-word queries retry as AND-of-terms (no Ollama needed)
3. semantic — embedding search

A stderr note tells you which layer answered. Near-miss hints suggest a simpler pattern when a complex one fails.

Worktree-aware paths

Run from a git worktree and claude-grep substitutes the main repo path, so you search the project's real session history instead of an empty worktree scope.

Benchmark harness

claude-grep --bench bench/queries.json runs the recovery ladder over a labeled query set and reports layer attribution — measure recall changes against bench/baseline.json.

Full Changelog

• feat: curated-docs search lane (#2)
• feat: --docs-only flag for head-safe curated-docs search
• feat: search git-tracked README/CLAUDE/MEMORY in the curated-docs lane
• feat: show file:line in curated-docs hits for navigable pointers
• feat: regex->tokenized->semantic recovery ladder with layer telemetry
• feat: tokenizedSearch — AND-session, OR-message recovery
• feat: --bench harness over the live recovery ladder
• feat: substitute main repo path when run from a git worktree
• docs: restructure README for GitHub presentability

Full diff: v1.4.0...v1.7.0

v1.4.0 — Auto-fallback & Smarter Defaults

What's New

Auto-fallback to semantic search

When regex finds 0 results and Ollama is running, automatically retries with semantic search. No more manual -s flag for recall-type queries.

Self-exclusion

Automatically skips the current session file from results to prevent self-referential matches (agent searches for X, finds itself asking about X).

Short-pattern warning

Patterns with longest literal ≤3 chars get a stderr hint to use -s instead, reducing false-positive noise.

Bigger defaults for 1M context

• Default results bumped from 50 → 100
• BM25 budget doubled from 15K → 30K chars
• Same detail per result, twice the coverage

Hour-level filtering

New -H flag for hour-level time filtering (e.g., -H 4 for last 4 hours).

Full Changelog

• feat: auto-fallback, short-pattern warning, self-exclusion
• feat: bump default results to 100, BM25 budget to 30K
• feat: add -H flag for hour-level time filtering
• test: add excludeNewestFile unit tests
• CI/CD: GitHub Actions + Codecov

v1.2.0 — BM25 Compression

What's new

Terminal output now uses BM25 query-focused compression instead of blind head truncation. Agent context cost drops from ~17,500 tokens to ~1,500 tokens per search — a 10-13x reduction.

BM25 Pipeline

regex match → sentence split → tokenize (bigrams + stemming + stop words)
            → BM25 score → select top chunks → adaptive budget → dedup

Feature	Effect
Sentence-level splitting	3-5x more facts per budget
Suffix stemming	deploy matches deployed, deploying, deployment
Stop word filtering	60+ words removed from scoring
Bigram scoring	pip install boosts chunks with adjacent words
Adaptive budget	3 matches = 2000 chars each, 50 = 300 each
Content dedup	~35% fewer duplicate results
Near-miss hints	Empty results suggest simpler queries

Other

• --json output preserves full uncompressed text (unchanged)
• 10 new tests for BM25 pipeline
• Fixed splitChunks fallback for single-newline text
• Full docs in README

Install

go install github.com/evoleinik/claude-grep@v1.2.0