Semantic Search
Use the mcp__claude-context__search_code tool for conceptual, exploratory,
and description-based code search. It searches against an indexed embedding
store built from the codebase, so it finds code by meaning rather than
exact text matching.
When to Use
- Conceptual queries: "how does shard allocation work", "where is the gossip protocol implemented"
- Exploring unfamiliar code: understanding architecture, finding entry points, tracing data flow
- Finding by description: "retry logic with exponential backoff", "error handling for network failures"
- Cross-cutting concerns: "all places that validate shard boundaries", "code related to claim lifecycle"
- Pattern discovery: "builder pattern usage", "state machine implementations"
- Architecture understanding: "how do boundaries interact", "what coordinates shard splits"
When NOT to Use
- Exact identifiers — use Grep:
Grep(pattern="ShardRecord", type="rust")
- File names or paths — use Glob:
Glob(pattern="**/coordination/**/*.rs")
- Simple string literals — use Grep:
Grep(pattern="SHARD_LIMIT")
- Broad exploration of directory structure — use Task with
subagent_type=Explore
Decision Matrix
| Signal in query |
Tool |
Example |
| Exact function/struct/const name |
Grep |
"find PreallocShardBuilder" |
| File name or glob pattern |
Glob |
"find all test files in coordination/" |
| "How does X work" |
Semantic search |
"how does shard checkpoint restoration work" |
| "Find code that does Y" |
Semantic search |
"find code that validates range boundaries" |
| "Where is the Z pattern" |
Semantic search |
"where is the builder pattern for bulk operations" |
| Known regex pattern |
Grep |
fn acquire.*restore |
| Concept or behavior |
Semantic search |
"claim expiry and reclamation logic" |
Usage
mcp__claude-context__search_code(
path="/Users/ahrav/Projects/Gossip-rs",
query="<descriptive natural language query>",
limit=10
)
Parameters:
path — Must be absolute. Use /Users/ahrav/Projects/Gossip-rs.query — Natural language description of what you are looking for. Be specific.limit — Number of results (default 10, max 50). Start with 10, increase if needed.extensionFilter — Optional file extension filter, e.g. [".rs"] for Rust only.
Writing Good Queries
| Weak query |
Strong query |
| "shard" |
"shard allocation and registration in the coordination engine" |
| "error" |
"error handling for resource exhaustion during shard registration" |
| "test" |
"simulation test invariant checking for shard consistency" |
| "split" |
"split planning and range boundary calculation for bulk operations" |
| "pool" |
"byte slab pool allocation and slot lifecycle management" |
Use domain language from the project: shards, claims, cursors, checkpoints,
boundaries, coordination, gossip, lineage, manifests, splits, epoch, quorum.
Combining Tools
For thorough investigation, chain tools:
- Semantic search to find the right area of the codebase
- Read the top results to understand context
- Grep to find all exact references to specific identifiers discovered in step 2
- Glob to map out related files in the same module
Re-indexing
If the index is stale or search returns no results for queries that should match:
mcp__claude-context__index_codebase(
path="/Users/ahrav/Projects/Gossip-rs",
force=true
)
Check indexing status with mcp__claude-context__get_indexing_status.
DO
- Write queries as natural language descriptions of behavior or architecture
- Use project domain terms (shard, claim, cursor, checkpoint, epoch, etc.)
- Start with semantic search for exploratory work, then narrow with Grep
- Filter by extension when you know the file type
DON'T
- Use semantic search for exact identifier lookup (Grep is faster and precise)
- Write single-word queries — always provide context
- Forget the absolute path requirement
- Use semantic search when you already know the file — just Read it
1---2name: semantic-search-23description: Use when exploring the codebase conceptually — semantic search via claude-context MCP for queries like "how does X work", "find implementation of Y pattern", "where is the architecture for Z", understanding unfamiliar code, finding code by description rather than exact identifier4---5
6# Semantic Search
7
8Use the `mcp__claude-context__search_code` tool for conceptual, exploratory,
9and description-based code search. It searches against an indexed embedding
10store built from the codebase, so it finds code by **meaning** rather than
11exact text matching.
12
13## When to Use
14
15- **Conceptual queries**: "how does shard allocation work", "where is the gossip protocol implemented"
16- **Exploring unfamiliar code**: understanding architecture, finding entry points, tracing data flow
17- **Finding by description**: "retry logic with exponential backoff", "error handling for network failures"
18- **Cross-cutting concerns**: "all places that validate shard boundaries", "code related to claim lifecycle"
19- **Pattern discovery**: "builder pattern usage", "state machine implementations"
20- **Architecture understanding**: "how do boundaries interact", "what coordinates shard splits"
21
22## When NOT to Use
23
24- **Exact identifiers** — use Grep: `Grep(pattern="ShardRecord", type="rust")`
25- **File names or paths** — use Glob: `Glob(pattern="**/coordination/**/*.rs")`
26- **Simple string literals** — use Grep: `Grep(pattern="SHARD_LIMIT")`
27- **Broad exploration of directory structure** — use Task with `subagent_type=Explore`
28
29## Decision Matrix
30
31| Signal in query | Tool | Example |
32|-----------------|------|---------|
33| Exact function/struct/const name | **Grep** | "find `PreallocShardBuilder`" |
34| File name or glob pattern | **Glob** | "find all test files in coordination/" |
35| "How does X work" | **Semantic search** | "how does shard checkpoint restoration work" |
36| "Find code that does Y" | **Semantic search** | "find code that validates range boundaries" |
37| "Where is the Z pattern" | **Semantic search** | "where is the builder pattern for bulk operations" |
38| Known regex pattern | **Grep** | `fn acquire.*restore` |
39| Concept or behavior | **Semantic search** | "claim expiry and reclamation logic" |
40
41## Usage
42
43```
44mcp__claude-context__search_code(
45 path="/Users/ahrav/Projects/Gossip-rs",
46 query="<descriptive natural language query>",
47 limit=10
48)
49```
50
51**Parameters:**
52- `path` — **Must be absolute.** Use `/Users/ahrav/Projects/Gossip-rs`.
53- `query` — Natural language description of what you are looking for. Be specific.
54- `limit` — Number of results (default 10, max 50). Start with 10, increase if needed.
55- `extensionFilter` — Optional file extension filter, e.g. `[".rs"]` for Rust only.
56
57## Writing Good Queries
58
59| Weak query | Strong query |
60|------------|-------------|
61| "shard" | "shard allocation and registration in the coordination engine" |
62| "error" | "error handling for resource exhaustion during shard registration" |
63| "test" | "simulation test invariant checking for shard consistency" |
64| "split" | "split planning and range boundary calculation for bulk operations" |
65| "pool" | "byte slab pool allocation and slot lifecycle management" |
66
67Use **domain language** from the project: shards, claims, cursors, checkpoints,
68boundaries, coordination, gossip, lineage, manifests, splits, epoch, quorum.
69
70## Combining Tools
71
72For thorough investigation, chain tools:
73
741. **Semantic search** to find the right area of the codebase
752. **Read** the top results to understand context
763. **Grep** to find all exact references to specific identifiers discovered in step 2
774. **Glob** to map out related files in the same module
78
79## Re-indexing
80
81If the index is stale or search returns no results for queries that should match:
82
83```
84mcp__claude-context__index_codebase(
85 path="/Users/ahrav/Projects/Gossip-rs",
86 force=true
87)
88```
89
90Check indexing status with `mcp__claude-context__get_indexing_status`.
91
92## DO
93
94- Write queries as natural language descriptions of behavior or architecture
95- Use project domain terms (shard, claim, cursor, checkpoint, epoch, etc.)
96- Start with semantic search for exploratory work, then narrow with Grep
97- Filter by extension when you know the file type
98
99## DON'T
100
101- Use semantic search for exact identifier lookup (Grep is faster and precise)
102- Write single-word queries — always provide context
103- Forget the absolute path requirement
104- Use semantic search when you already know the file — just Read it
majiayu000