
colgrep
Semantic code search powered by ColBERT. Drop-in replacement for grep with natural language understanding.
- version
- 1.8.5
- GitHub stars
- 619
Install
/plugin install colgrep@lighton-toolsRun it inside Claude Code after adding the marketplace with /plugin marketplace add lightonai/next-plaid.
Contents
Discovered from sourceSkills 1
Semantic Code Search
This repository has colgrep installed - a semantic code search CLI.
Use colgrep as your PRIMARY search tool instead of Search / Grep / Glob.
Quick Reference
# Basic semantic search
colgrep "<natural language query>" --results 10 # Basic search
colgrep "<query>" -k 25 # Exploration (more results)
colgrep "<query>" ./src/parser # Search in specific folder
colgrep "<query>" ./src/main.rs # Search in specific file
colgrep "<query>" ./src/main.rs ./src/lib.rs # Search in multiple files
colgrep "<query>" ./crate-a ./crate-b # Search multiple directories
# File filtering
colgrep --include="*.rs" "<query>" # Include only .rs files
colgrep --include="src/**/*.rs" "<query>" # Recursive glob pattern
colgrep --include="*.{rs,md}" "<query>" # Multiple file types (brace expansion)
colgrep --exclude="*.test.ts" "<query>" # Exclude test files
colgrep --exclude-dir=vendor "<query>" # Exclude vendor directory
# Pattern-only search (no semantic query needed)
colgrep -e "<pattern>" # Search by pattern only
colgrep -e "async fn" --include="*.rs" # Pattern search with file filter
# Hybrid search (text + semantic)
colgrep -e "<text>" "<semantic query>" # Hybrid: text + semantic
colgrep -e "<regex>" -E "<semantic query>" # Hybrid with extended regex (ERE)
colgrep -e "<literal>" -F "<semantic query>" # Hybrid with fixed string (no regex)
colgrep -e "<word>" -w "<semantic query>" # Hybrid with whole word match
# Output options
colgrep -l "<query>" # List files only
colgrep -c "<query>" # Show full function content (50 lines max)
colgrep -n 10 "<query>" # Show 10 context lines (default: 6)
colgrep --json "<query>" # JSON output
Grep-Compatible Flags
| Flag | Description | Example |
|---|---|---|
-e <PATTERN> | Text pattern pre-filter | colgrep -e "async" "concurrency" |
-E | Extended regex (ERE) for -e | colgrep -e "async|await" -E "concurrency" |
-F | Fixed string (no regex) for -e | colgrep -e "foo[bar]" -F "query" |
-w | Whole word match for -e | colgrep -e "test" -w "testing" |
-k, --results | Number of results to return | colgrep --results 20 "query" |
-l | List files only | colgrep -l "authentication" |
-r | Recursive (default, for compatibility) | colgrep -r "query" |
--include | Include files matching pattern (repeatable) | colgrep --include="*.py" "query" |
--exclude | Exclude files matching pattern | colgrep --exclude="*.min.js" "query" |
--exclude-dir | Exclude directories | colgrep --exclude-dir=node_modules "query" |
Notes:
-Ftakes precedence over-E(like grep)- Default exclusions always apply:
.git,node_modules,target,.venv,__pycache__ - When running from a subdirectory, results are restricted to that subdirectory. To search the full project, specify
.or..as the path - Multiple
--includepatterns use OR logic (matches if file matches any pattern) - Brace expansion is supported:
*.{rs,md,py}expands to match all three types
When to Use What
| Task | Tool |
|---|---|
| Find code by intent/description | colgrep "query" -k 10 |
| Explore/understand a system | colgrep "query" -k 25 (increase k) |
| Search by pattern only | colgrep -e "pattern" (no semantic query) |
| Know text exists, need context | colgrep -e "text" "semantic query" |
| Literal text with special chars | colgrep -e "foo[0]" -F "semantic query" |
| Whole word match | colgrep -e "test" -w "testing utilities" |
| Search in a specific file | colgrep "query" ./src/main.rs |
| Search in multiple files | colgrep "query" ./src/main.rs ./src/lib.rs |
| Search specific file type | colgrep --include="*.ext" "query" |
| Search multiple file types | colgrep --include="*.{rs,md,py}" "query" |
| Exclude test files | colgrep --exclude="*_test.go" "query" |
| Exclude vendor directories | colgrep --exclude-dir=vendor "query" |
| Search in specific directories | colgrep --include="src/**/*.rs" "query" |
| Search multiple directories | colgrep "query" ./src ./lib ./api |
| Search CI/CD configs | colgrep --include="**/.github/**/*" "q" . |
| View full function content | colgrep -c "query" |
| Exact string/regex match only | Built-in Grep tool |
| Find files by name | Built-in Glob tool |
Key Rules
- Default to
colgrepfor any code search - Increase
--results(or-k) when exploring (20-30 results) - Use
-efor hybrid text+semantic filtering - Use
-Ewith-efor extended regex (alternation|, quantifiers+?, grouping()) - Use
-Fwith-ewhen pattern contains regex special characters you want literal - Use
-wwith-eto avoid partial matches (e.g., "test" won't match "testing") - Use
--exclude/--exclude-dirto filter out noise (tests, vendors, generated code) - Use brace expansion for multiple file types (e.g.,
--include="*.{rs,md,py}") - Agents should use
colgrep- when spawning Task/Explore agents, they should also use colgrep instead of Grep
Need Help?
Run colgrep --help for complete documentation on all flags and options.
Hooks 2
Sponsors
Details
- Marketplace
- lightonai/next-plaid
- Source
- .
- Author
- LightOn AI
- Category
- Community