\r \r

clawgrep\r

\r 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.\r \r

Check availability\r

\r

clawgrep --version\r
```\r
\r
If not found, install from the [open-source repository](https://github.com/Schonhoffer/clawgrep) using any of these methods (only one needed):\r
\r
```bash\r
cargo install clawgrep        # Rust (recommended)\r
npm install -g clawgrep        # Node.js\r
pip install clawgrep           # Python\r
```\r
\r
## Basic usage\r
\r
```bash\r
clawgrep --no-color "query" \x3Cpath>\r
```\r
\r
Always pass `--no-color` when parsing output programmatically.\r
\r
### Search a workspace\r
\r
```bash\r
clawgrep --no-color "previous discussion about auth flow" ./memory\r
```\r
\r
### Output format\r
\r
Grep-compatible, one result per line, ranked by relevance (best first):\r
\r
```\r
$ clawgrep --no-color "previous discussion about auth flow" ./memory\r
memory/2025-06-12-auth-design.md:8:Decided to use OAuth2 with PKCE for all client auth.\r
memory/2025-06-12-auth-design.md:14:Token refresh should be transparent to the user.\r
memory/2025-06-10-planning.md:3:Auth flow is the top priority for the sprint.\r
memory/archive/2025-05-session-notes.md:42:Discussed moving auth to a separate service.\r
memory/archive/2025-05-session-notes.md:87:Need to revisit token expiry policy.\r
```\r
\r
Each line is `file:line:text`. Context lines (from `-C`) use `-` as the\r
separator instead: `file-line-text`.\r
\r
### Exit codes\r
\r
| Code | Meaning |\r
|------|---------|\r
| `0`  | Match found |\r
| `1`  | No match |\r
| `2`  | Error |\r
\r
Same as grep. Use `-q` for existence checks without output.\r
\r
## Choosing search mode\r
\r
Default weights: 70% semantic, 30% keyword.\r
\r
**Concept search** (don't know exact wording):\r
\r
```bash\r
clawgrep --no-color "decision about migration strategy" ./memory\r
```\r
\r
**Exact identifier search** (note IDs, tags, serial numbers):\r
\r
```bash\r
clawgrep --no-color --keyword-weight 0.8 --semantic-weight 0.2 "PROJ-1042" ./memory\r
```\r
\r
## Key flags\r
\r
| Flag | Purpose |\r
|------|---------|\r
| `-k N` | Number of results (default: 5) |\r
| `-C N` | Context lines before and after |\r
| `-l` | Print only matching filenames |\r
| `-q` | Quiet; just set exit code |\r
| `--show-score` | Append relevance score |\r
| `--path-boost N` | Boost filename matches (>1.0 = higher) |\r
| `--min-score N` | Filter low-relevance results (0.0–1.0) |\r
\r
See [CLI reference](references/cli-reference.md) for all flags.\r
\r
## Best practices\r
\r
1. Use `--no-color` always when parsing output.\r
2. Keep `-k` small (3–5) to reduce output. Increase only when needed.\r
3. Check exit codes instead of parsing stdout when possible.\r
4. Let the cache persist — don't use `--no-cache` unless searching throwaway\r
   content. First run indexes; subsequent runs are fast.\r
5. Search the narrowest relevant directory, not the whole filesystem.\r
\r
## References (advanced, usually not needed)\r
\r
The information above should be sufficient for normal use. Only load these if\r
you run into problems or need flags not listed above:\r
\r
- [CLI reference](references/cli-reference.md) — all flags, config file format, grep compatibility\r
- [Examples](references/examples.md) — more input/output examples for edge cases\r