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-tools

Run it inside Claude Code after adding the marketplace with /plugin marketplace add lightonai/next-plaid.

Contents

Discovered from source

Skills 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

FlagDescriptionExample
-e <PATTERN>Text pattern pre-filtercolgrep -e "async" "concurrency"
-EExtended regex (ERE) for -ecolgrep -e "async|await" -E "concurrency"
-FFixed string (no regex) for -ecolgrep -e "foo[bar]" -F "query"
-wWhole word match for -ecolgrep -e "test" -w "testing"
-k, --resultsNumber of results to returncolgrep --results 20 "query"
-lList files onlycolgrep -l "authentication"
-rRecursive (default, for compatibility)colgrep -r "query"
--includeInclude files matching pattern (repeatable)colgrep --include="*.py" "query"
--excludeExclude files matching patterncolgrep --exclude="*.min.js" "query"
--exclude-dirExclude directoriescolgrep --exclude-dir=node_modules "query"

Notes:

  • -F takes 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 --include patterns 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

TaskTool
Find code by intent/descriptioncolgrep "query" -k 10
Explore/understand a systemcolgrep "query" -k 25 (increase k)
Search by pattern onlycolgrep -e "pattern" (no semantic query)
Know text exists, need contextcolgrep -e "text" "semantic query"
Literal text with special charscolgrep -e "foo[0]" -F "semantic query"
Whole word matchcolgrep -e "test" -w "testing utilities"
Search in a specific filecolgrep "query" ./src/main.rs
Search in multiple filescolgrep "query" ./src/main.rs ./src/lib.rs
Search specific file typecolgrep --include="*.ext" "query"
Search multiple file typescolgrep --include="*.{rs,md,py}" "query"
Exclude test filescolgrep --exclude="*_test.go" "query"
Exclude vendor directoriescolgrep --exclude-dir=vendor "query"
Search in specific directoriescolgrep --include="src/**/*.rs" "query"
Search multiple directoriescolgrep "query" ./src ./lib ./api
Search CI/CD configscolgrep --include="**/.github/**/*" "q" .
View full function contentcolgrep -c "query"
Exact string/regex match onlyBuilt-in Grep tool
Find files by nameBuilt-in Glob tool

Key Rules

  1. Default to colgrep for any code search
  2. Increase --results (or -k) when exploring (20-30 results)
  3. Use -e for hybrid text+semantic filtering
  4. Use -E with -e for extended regex (alternation |, quantifiers +?, grouping ())
  5. Use -F with -e when pattern contains regex special characters you want literal
  6. Use -w with -e to avoid partial matches (e.g., "test" won't match "testing")
  7. Use --exclude/--exclude-dir to filter out noise (tests, vendors, generated code)
  8. Use brace expansion for multiple file types (e.g., --include="*.{rs,md,py}")
  9. 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.

Sponsors

Details

Marketplace
lightonai/next-plaid
Source
.
Author
LightOn AI
Category
Community