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

clawgrep --version

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

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

Basic usage

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

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

Search a workspace

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

Output format

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

$ 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

| Code | Meaning |

|------|---------|

| 0 | Match found |

| 1 | No match |

| 2 | Error |

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):

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

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

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

Key flags

| Flag | Purpose |

|------|---------|

| -k N | Number of results (default: 5) |

| -C N | Context lines before and after |

| -l | Print only matching filenames |

| -q | Quiet; just set exit code |

| --show-score | Append relevance score |

| --path-boost N | Boost filename matches (>1.0 = higher) |

| --min-score N | Filter 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.

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