clawgrep#

Semantic + keyword file search. Output is grep-compatible. Runs fully locally. On first run, automatically downloads a small ONNX embedding model (~30 MB) from Hugging Face and caches it in the local cache directory. After that, all searches are offline.

Check availability#

bash

clawgrep --version

If not found, install from the open-source repository using any of these methods (only one needed):

bash

cargo install clawgrep        # Rust (recommended)
npm install -g clawgrep        # Node.js
pip install clawgrep           # Python

Basic usage#

bash

clawgrep --no-color "query" <path>

Always pass --no-color when parsing output programmatically.

Search a workspace#

bash

clawgrep --no-color "previous discussion about auth flow" ./memory

Output format#

Grep-compatible, one result per line, ranked by relevance (best first):

text

$ clawgrep --no-color "previous discussion about auth flow" ./memory
memory/2025-06-12-auth-design.md:8:Decided to use OAuth2 with PKCE for all client auth.
memory/2025-06-12-auth-design.md:14:Token refresh should be transparent to the user.
memory/2025-06-10-planning.md:3:Auth flow is the top priority for the sprint.
memory/archive/2025-05-session-notes.md:42:Discussed moving auth to a separate service.
memory/archive/2025-05-session-notes.md:87:Need to revisit token expiry policy.

Each line is file:line:text. Context lines (from -C) use - as the separator instead: file-line-text.

Exit codes#

CodeMeaning0Match found1No match2Error

Same as grep. Use -q for existence checks without output.

Choosing search mode#

Default weights: 70% semantic, 30% keyword.

Concept search (don't know exact wording):

bash

clawgrep --no-color "decision about migration strategy" ./memory

Exact identifier search (note IDs, tags, serial numbers):

bash

clawgrep --no-color --keyword-weight 0.8 --semantic-weight 0.2 "PROJ-1042" ./memory

Key flags#

FlagPurpose-k NNumber of results (default: 5)-C NContext lines before and after-lPrint only matching filenames-qQuiet; just set exit code--show-scoreAppend relevance score--path-boost NBoost filename matches (>1.0 = higher)--min-score NFilter low-relevance results (0.0–1.0)

See CLI reference for all flags.

Best practices#

1. Use --no-color always when parsing output.
2. Keep -k small (3–5) to reduce output. Increase only when needed.
3. Check exit codes instead of parsing stdout when possible.
4. Let the cache persist — don't use --no-cache unless searching throwaway content. First run indexes; subsequent runs are fast.
5. Search the narrowest relevant directory, not the whole filesystem.

References (advanced, usually not needed)#

The information above should be sufficient for normal use. Only load these if you run into problems or need flags not listed above:

• CLI reference — all flags, config file format, grep compatibility
• Examples — more input/output examples for edge cases