Ck search

ck search

This skill explains how to use the ck tool to do semantic, hybrid, or classic lexical searches across a project repository. ck combines three complementary modes:

• Lexical: fast pattern/regex matching (like grep / rg).
• Semantic: embeddings-based retrieval to find code "by meaning" even when terminology differs.
• Hybrid: combines semantic relevance with keyword constraints (reciprocal rank fusion) to get precise results.

ck is a drop-in replacement for grep/rg for everyday pattern searches, and it adds powerful semantic and hybrid modes once you index the repo.

Very short: Use when grep misses related code or you want to find code by meaning (semantic) or combine keywords with concept-level matches (hybrid).

When to use

Use semantic to search by code meaning, not just keywords. Semantic search understands concepts and finds related code even when exact terms don’t match.

Use hybrid when:

• You need both concept AND keywords present
• Semantic search returns too many false positives
• Keyword search misses related code
• You want balanced precision and recall

Grep Replacement

# Pattern search
ck "pattern" file.txt
ck "pattern" *.rs
ck "TODO|FIXME" src/

# Case-insensitive
ck -i "warning" src/

# Whole word match
ck -w "test" src/

# Invert match
ck -v "exclude" src/
Output Control

# Line numbers
ck -n "pattern" file.txt

# Only filenames with matches
ck -l "pattern" src/

# Only filenames without matches
ck -L "pattern" src/

# Hide filenames
ck --no-filename "pattern" file1 file2

# Count matches
ck -c "pattern" src/
Context Display

# N lines after match
ck -A 3 "error" src/

# N lines before match
ck -B 2 "error" src/

# N lines before and after
ck -C 2 "error" src/

# Context with line numbers
ck -n -C 3 "error" src/
Recursive Search

# Recursive
ck -R "pattern" .

# Alternative
ck -r "pattern" .

# With exclusions
ck -R --exclude "*.test.js" "pattern" src/
File Filtering

# Specific file types
ck "pattern" **/*.rs
ck "pattern" **/*.{js,ts}

# Exclude patterns
ck --exclude "*.test.js" "pattern" src/
ck --exclude "node_modules" "pattern" .

# Multiple exclusions
ck --exclude "dist" --exclude "build" "pattern" .

Semantic

Find code by meaning, not just keywords. Semantic search understands concepts and finds related code even when exact terms don’t match.

Examples:

# Find error handling patterns
ck --sem "error handling" src/

# Find authentication code
ck --sem "user authentication" src/

# Find database operations
ck --sem "SQL queries" src/

With relevance scores:

# Show how relevant each match is
ck --sem --scores "caching" src/

# Output:
# [0.847] ./cache_manager.rs: LRU cache implementation
# [0.732] ./http_client.rs: Response caching with TTL
# [0.651] ./config.rs: Configuration caching

Scores range from 0.0 to 1.0, with higher scores indicating stronger semantic similarity.

Hybrid Search

Use hybrid when:

• You need both concept AND keywords present
• Semantic search returns too many false positives
• Keyword search misses related code
• You want balanced precision and recall

Hybrid search merges semantic and keyword search results to give you the best of both worlds:

• Semantic – Finds conceptually related code
• Keyword – Ensures query terms are present
• Fusion – Ranks results by combined relevance

Simple Examples:

# Simple hybrid search
ck --hybrid "connection timeout" src/

# With relevance scores
ck --hybrid --scores "cache invalidation" src/

# Filter by confidence (note: RRF scores are typically 0.01-0.05)
ck --hybrid --threshold 0.02 "auth" src/

Due to Reciprocal Rank Fusion (RRF) mathematics, hybrid scores typically range from 0.01 to 0.05, not 0.0 to 1.0 like semantic search. This is a known counterintuitive aspect of RRF scoring.

Threshold Filtering Examples:

# High confidence only (RRF scale)
ck --hybrid --threshold 0.025 "pattern" src/

# Exploratory (lower confidence, more results)
ck --hybrid --threshold 0.015 "pattern" src/

# Very strict (only top matches)
ck --hybrid --threshold 0.03 "pattern" src/

Choosing the Right Threshold:

Start with --threshold 0.02 for hybrid search. If you get too many results, increase to 0.025 or 0.03. If too few, decrease to 0.015. Use --scores to see actual RRF values and calibrate your threshold accordingly.

Result limiting example:

# Top 10 results
ck --hybrid --topk 10 "pattern" src/

# With threshold
ck --hybrid --topk 20 --threshold 0.02 "pattern" src/