zhongwei/gh-cadrianmae-claude-marketplace-plugins-semantic-search
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:03:17 +08:00
commit df4751ce28
11 changed files with 2308 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,15 @@
{
"name": "semantic-search",
"description": "Natural language semantic search for codebases and notes using odino CLI with BGE embeddings. Commands for indexing and searching with automatic directory traversal.",
"version": "1.0.0",
"author": {
"name": "Mae Capacite",
"email": "cadrianmae@users.noreply.github.com"
},
"skills": [
"./skills"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# semantic-search
Natural language semantic search for codebases and notes using odino CLI with BGE embeddings. Commands for indexing and searching with automatic directory traversal.

235
commands/here.md Normal file
View File

@@ -0,0 +1,235 @@
---
description: Search from current directory upward to find indexed codebase
argument-hint: <query>
allowed-tools: Bash, Read
disable-model-invocation: true
---
# here - Semantic search with directory traversal
Search from current directory upward to find and search the nearest semantic index. Shows where the index was found for transparency.
## Usage
```
/semq:here <query>
```
**Arguments:**
- `query` - Natural language description of what to find (required)
## What It Does
1. Starts from current working directory
2. Traverses up the directory tree looking for `.odino/`
3. Shows where the index was found
4. Runs semantic search from that location
5. Displays results with scores and file paths
**Difference from `/semq:search`:**
- `/semq:search` - Assumes you know where the index is
- `/semq:here` - Explicitly shows index location (useful from subdirectories)
## Examples
**Search from subdirectory:**
```bash
cd src/utils/
/semq:here validation functions
```
**Find authentication from deep directory:**
```bash
cd src/routes/api/v1/
/semq:here authentication logic
```
## Implementation
```bash
# Helper function to find .odino directory with verbose output
find_odino_root_verbose() {
local dir="$PWD"
local depth=0
while [[ "$dir" != "/" ]]; do
if [[ -d "$dir/.odino" ]]; then
echo "FOUND:$dir"
return 0
fi
# Stop at git root as a boundary
if [[ -d "$dir/.git" ]] && [[ ! -d "$dir/.odino" ]]; then
echo "NOTFOUND:git-boundary:$dir"
return 1
fi
dir="$(dirname "$dir")"
depth=$((depth + 1))
# Safety limit
if [[ $depth -gt 20 ]]; then
echo "NOTFOUND:max-depth"
return 1
fi
done
echo "NOTFOUND:filesystem-root"
return 1
}
# Get query from arguments
QUERY="$*"
if [[ -z "$QUERY" ]]; then
echo "Error: Query required"
echo "Usage: /semq:here <query>"
exit 1
fi
# Show current location
echo "Searching from: $PWD"
echo ""
# Find index with verbose output
RESULT=$(find_odino_root_verbose)
EXIT_CODE=$?
if [[ $EXIT_CODE -eq 0 ]]; then
ODINO_ROOT="${RESULT#FOUND:}"
# Show where index was found
if [[ "$ODINO_ROOT" == "$PWD" ]]; then
echo "✓ Index found in current directory"
else
# Calculate relative path for clarity
REL_PATH=$(realpath --relative-to="$PWD" "$ODINO_ROOT")
echo "✓ Index found at: $REL_PATH"
fi
echo " Location: $ODINO_ROOT"
echo ""
# Run search
RESULTS=$(cd "$ODINO_ROOT" && odino query -q "$QUERY" 2>&1)
if [[ $? -eq 0 ]]; then
echo "$RESULTS"
echo ""
echo "💡 Tip: File paths are relative to: $ODINO_ROOT"
else
echo "Search failed:"
echo "$RESULTS"
fi
else
# Parse failure reason
REASON="${RESULT#NOTFOUND:}"
echo "✗ No semantic search index found"
echo ""
case "$REASON" in
git-boundary:*)
GIT_ROOT="${REASON#git-boundary:}"
echo "Searched up to git repository root: $GIT_ROOT"
echo "The repository is not indexed."
;;
filesystem-root)
echo "Searched all the way to filesystem root"
echo "No index found in any parent directory."
;;
max-depth)
echo "Reached maximum search depth (20 levels)"
echo "Index might be higher up or doesn't exist."
;;
esac
echo ""
echo "To create an index, navigate to your project root and run:"
echo " cd <project-root>"
echo " /semq:index"
fi
```
## Output Example
**From subdirectory:**
```
Searching from: /home/user/project/src/utils
✓ Index found at: ../..
Location: /home/user/project
Score: 0.87 | Path: src/utils/validation.js
Score: 0.81 | Path: src/middleware/validate.js
Score: 0.74 | Path: src/schemas/user.js
💡 Tip: File paths are relative to: /home/user/project
```
**No index found:**
```
Searching from: /home/user/project/src/utils
✗ No semantic search index found
Searched up to git repository root: /home/user/project
The repository is not indexed.
To create an index, navigate to your project root and run:
cd <project-root>
/semq:index
```
## When to Use
Use `/semq:here` when:
- Working in a subdirectory
- Want to see where the index is located
- Unsure if directory is indexed
- Want explicit feedback about index location
Use `/semq:search` when:
- Already know the directory is indexed
- Don't need index location info
- Want simpler output
## Behavior
**Traversal stops at:**
1. `.odino/` directory found (success)
2. `.git/` directory without `.odino/` (git repository boundary)
3. Filesystem root `/` (no more parents)
4. 20 levels up (safety limit)
**Why stop at git root?**
- Projects are typically git repositories
- Prevents searching into parent projects
- Makes "not found" more meaningful
## Related Commands
- `/semq:search <query>` - Search without traversal info
- `/semq:status` - Check index status
- `/semq:index` - Create index
## Tips
1. **Use from subdirectories** - That's what this command is for
2. **Check the index location** - Helps understand project structure
3. **Git boundary** - Index should be at git root for best results
4. **Relative paths** - Results show paths relative to index location
## Troubleshooting
**"Searched up to git repository root"**
- The git repository is not indexed
- Solution: Run `/semq:index` from the git root
**"Searched all the way to filesystem root"**
- No index found anywhere in parent directories
- Not in a git repository
- Solution: Create index with `/semq:index`
**"Reached maximum search depth"**
- Very deep directory structure (>20 levels)
- Index might be higher up
- Solution: Navigate closer to project root and try again

253
commands/index.md Normal file
View File

@@ -0,0 +1,253 @@
---
description: Index directory for semantic search
argument-hint: [path] [--force]
allowed-tools: Bash
disable-model-invocation: true
---
# index - Create semantic search index
Index a directory for semantic search using odino with BGE embeddings.
## Usage
```
/semq:index [path] [--force]
```
**Arguments:**
- `path` - Directory to index (optional, defaults to current directory)
- `--force` - Force reindex even if index exists
## What It Does
1. Checks if directory already has an index
2. Runs `odino index` with BGE model (BAAI/bge-small-en-v1.5)
3. Creates `.odino/` directory with:
- `config.json` - Configuration settings
- `chroma_db/` - Vector database with embeddings
4. Shows progress and completion statistics
## Examples
**Index current directory:**
```
/semq:index
```
**Index specific directory:**
```
/semq:index ~/projects/myapp
```
**Force reindex:**
```
/semq:index --force
```
## Implementation
```bash
# Parse arguments
INDEX_PATH="."
FORCE_FLAG=""
for arg in "$@"; do
case "$arg" in
--force)
FORCE_FLAG="--force"
;;
*)
if [[ -d "$arg" ]]; then
INDEX_PATH="$arg"
else
echo "Warning: Directory not found: $arg"
fi
;;
esac
done
# Convert to absolute path
INDEX_PATH="$(cd "$INDEX_PATH" && pwd)"
echo "Indexing directory: $INDEX_PATH"
# Check if already indexed
if [[ -d "$INDEX_PATH/.odino" ]] && [[ -z "$FORCE_FLAG" ]]; then
echo ""
echo "⚠️ Directory is already indexed"
echo ""
echo "To reindex, use: /semq:index --force"
echo "To check status: /semq:status"
exit 0
fi
# Create .odinoignore if it doesn't exist
if [[ ! -f "$INDEX_PATH/.odinoignore" ]]; then
cat > "$INDEX_PATH/.odinoignore" << 'EOF'
# Build artifacts
build/
dist/
*.pyc
__pycache__/
# Dependencies
node_modules/
venv/
.venv/
.virtualenv/
# Config and secrets
.env
.env.local
*.secret
.git/
# IDE
.vscode/
.idea/
*.swp
*.swo
# OS
.DS_Store
Thumbs.db
EOF
echo "Created .odinoignore file"
fi
# Run indexing with BGE model
echo ""
echo "Indexing with BGE model (this may take a moment)..."
echo ""
(cd "$INDEX_PATH" && odino index $FORCE_FLAG --model BAAI/bge-small-en-v1.5)
if [[ $? -eq 0 ]]; then
echo ""
echo "✅ Indexing complete!"
echo ""
echo "You can now search with:"
echo " /semq:search <query>"
else
echo ""
echo "❌ Indexing failed"
echo ""
echo "Troubleshooting:"
echo "- Ensure odino is installed: pipx install odino"
echo "- Check disk space"
echo "- Try again with --force flag"
fi
```
## Output Example
```
Indexing directory: /home/user/project
Created .odinoignore file
Indexing with BGE model (this may take a moment)...
Indexed 63 files
Generated 142 chunks (529.5 KB)
Model: BAAI/bge-small-en-v1.5
✅ Indexing complete!
You can now search with:
/semq:search <query>
```
## When to Use
Use `/semq:index` when:
- Setting up semantic search for a new project
- Major code changes have been made
- Switching to a different embedding model
- Index is corrupted or outdated
## .odinoignore
The command automatically creates `.odinoignore` to exclude:
- Build artifacts (build/, dist/)
- Dependencies (node_modules/, venv/)
- Configuration files (.env, secrets)
- IDE files (.vscode/, .idea/)
- Version control (.git/)
**Customize `.odinoignore`** for your project:
```
# Project-specific ignores
generated/
*.min.js
vendor/
```
## Model Selection
The command uses **BAAI/bge-small-en-v1.5** by default:
- **Size:** 133MB (vs 600MB for default model)
- **Parameters:** 33M (vs 308M)
- **Quality:** ~62-63 MTEB score (vs ~69)
- **Speed:** Much faster indexing
- **Memory:** Lower RAM usage
**Why BGE?**
- 78% smaller download
- 90% fewer parameters
- Faster indexing and search
- Only ~7 point quality drop
- Better for most use cases
## Performance Tips
1. **Use .odinoignore** - Exclude unnecessary files
2. **GPU acceleration** - Indexing is much faster with CUDA
3. **Batch size** - Adjust in `.odino/config.json` (16 for GPU, 8 for CPU)
4. **Reindex periodically** - After major code changes
## Troubleshooting
**"Command not found: odino"**
```bash
pipx install odino
```
**GPU out of memory**
```bash
# Edit .odino/config.json after first index
{
"embedding_batch_size": 8 # or 4
}
# Then reindex
/semq:index --force
```
**Slow indexing**
```bash
# BGE model is already the fastest option
# But you can reduce batch size if needed
# Edit .odino/config.json: "embedding_batch_size": 8
```
## Related Commands
- `/semq:status` - Check index status
- `/semq:search <query>` - Search the index
- `/semq:here <query>` - Search with traversal
## Configuration
After indexing, configuration is stored in `.odino/config.json`:
```json
{
"model_name": "BAAI/bge-small-en-v1.5",
"embedding_batch_size": 16,
"chunk_size": 512,
"chunk_overlap": 50
}
```
Edit this file to change settings, then reindex with `--force`.

205
commands/search.md Normal file
View File

@@ -0,0 +1,205 @@
---
description: Search indexed codebase using natural language semantic search
argument-hint: <query>
allowed-tools: Bash, Read
disable-model-invocation: true
---
# search - Semantic search in current directory
Search the current directory's semantic index using natural language queries.
## Usage
```
/semq:search <query>
```
**Arguments:**
- `query` - Natural language description of what to find (required)
## What It Does
1. Finds `.odino` directory by traversing up from current directory
2. Runs `odino query` from the index location
3. Parses and formats results with scores and file paths
4. Optionally reads top results for context
5. Suggests using code-pointer to open relevant files
## Examples
**Find error handling (conceptual):**
```
User: /semq:search error handling
Claude infers: "error handling exception management try catch validation"
Results:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ File ┃ Score ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ knowledge/Error Handling.md │ 0.876 │
│ → "Error handling is the process of..."
│ → Shows: Key Concepts, Best Practices
│
│ middleware/errorHandler.js │ 0.745 │
│ → Shows: Global error handler implementation
└─────────────────────────────────┴──────────┘
Claude reads top result and summarizes key concepts.
```
**Find database code:**
```
User: /semq:search DB connection code
Claude infers query with Python example:
"database connection pooling setup
import mysql.connector
pool = mysql.connector.pooling.MySQLConnectionPool(
pool_name='mypool',
pool_size=5,
host='localhost'
)
connection = pool.get_connection()"
Results:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ File ┃ Score ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ src/db/connection.js │ 0.924 │
│ → const pool = mysql.createPool({...})
│ → Shows: Connection pooling config with env vars
│ → Includes: Error handling and testing
└─────────────────────────────────┴──────────┘
Claude shows code snippet and explains pooling strategy.
```
**Find algorithms:**
```
User: /semq:search BFS algorithm Python
Claude infers query with code:
"breadth first search BFS graph traversal
def bfs(graph, start):
visited = set()
queue = [start]
while queue:
node = queue.pop(0)
if node not in visited:
visited.add(node)
queue.extend(graph[node])"
Results:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ File ┃ Score ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ knowledge/Search Algorithms.md │ 0.891 │
│ → Types: Uninformed (BFS, DFS) vs Informed (A*, Greedy)
│ → When to use each algorithm
│ → Includes mermaid diagram
└─────────────────────────────────┴──────────┘
Claude reads note and explains algorithm categories.
```
## Implementation
Use the directory traversal helper to find the index, then run the search:
```bash
# Helper function to find .odino directory
find_odino_root() {
local dir="$PWD"
while [[ "$dir" != "/" ]]; do
if [[ -d "$dir/.odino" ]]; then
echo "$dir"
return 0
fi
dir="$(dirname "$dir")"
done
return 1
}
# Get query from arguments
QUERY="$*"
if [[ -z "$QUERY" ]]; then
echo "Error: Query required"
echo "Usage: /semq:search <query>"
exit 1
fi
# Find index and search
if ODINO_ROOT=$(find_odino_root); then
echo "Searching in: $ODINO_ROOT"
echo ""
# Run search
RESULTS=$(cd "$ODINO_ROOT" && odino query -q "$QUERY" 2>&1)
if [[ $? -eq 0 ]]; then
echo "$RESULTS"
echo ""
echo "💡 Tip: Use code-pointer to open files at specific lines"
else
echo "Search failed:"
echo "$RESULTS"
fi
else
echo "No semantic search index found in current path."
echo ""
echo "To create an index, run:"
echo " /semq:index"
echo ""
echo "This will index the current directory for semantic search."
fi
```
## Output Format
Results are shown with similarity scores and file paths:
```
Searching in: /home/user/project
Score: 0.89 | Path: src/auth/middleware.js
Score: 0.82 | Path: src/auth/jwt.js
Score: 0.75 | Path: src/middleware/passport.js
💡 Tip: Use code-pointer to open files at specific lines
```
## Score Interpretation
- **0.85-1.0**: Highly relevant, definitely check this
- **0.70-0.84**: Likely relevant, worth reviewing
- **0.60-0.69**: Possibly relevant, may contain related concepts
- **<0.60**: Weakly related, probably not useful
## When to Use
Use `/semq:search` when:
- You know the directory is indexed
- You want to find code by describing what it does
- You're exploring an unfamiliar codebase
- Grep/glob aren't working (too literal)
Use `/semq:here` instead when:
- You're in a subdirectory and want automatic traversal
- You want to see where the index was found
## Related Commands
- `/semq:here <query>` - Search with directory info
- `/semq:status` - Check if directory is indexed
- `/semq:index` - Create a new index
## Tips
1. **Be conceptual** - Describe what the code does, not exact names
2. **Use natural language** - "authentication logic" not "auth"
3. **Check top 3-5 results** - Sometimes #3 is the best match
4. **Combine with grep** - Use semantic search to find area, grep for specifics
5. **Read files** - Use Read tool on top results for context

131
commands/status.md Normal file
View File

@@ -0,0 +1,131 @@
---
description: Show semantic search index status and statistics
argument-hint: [path]
allowed-tools: Bash
disable-model-invocation: true
---
# status - Check semantic search index status
Show indexing status, statistics, and configuration for current or specified directory.
## Usage
```
/semq:status [path]
```
**Arguments:**
- `path` - Directory to check (optional, defaults to current directory)
## What It Does
1. Finds `.odino` directory by traversing up from specified path
2. Runs `odino status` to show index information
3. Displays:
- Number of indexed files
- Total chunks generated
- Model name
- Index location
- Last modified date
## Examples
**Check current directory:**
```
/semq:status
```
**Check specific directory:**
```
/semq:status ~/projects/myapp
```
## Implementation
```bash
# Helper function to find .odino directory
find_odino_root() {
local start_dir="${1:-.}"
local dir="$(cd "$start_dir" && pwd)"
while [[ "$dir" != "/" ]]; do
if [[ -d "$dir/.odino" ]]; then
echo "$dir"
return 0
fi
dir="$(dirname "$dir")"
done
return 1
}
# Get path argument or use current directory
CHECK_PATH="${1:-.}"
# Find index and show status
if ODINO_ROOT=$(find_odino_root "$CHECK_PATH"); then
echo "Index found at: $ODINO_ROOT"
echo ""
# Run status command
(cd "$ODINO_ROOT" && odino status)
else
echo "No semantic search index found"
if [[ "$CHECK_PATH" != "." ]]; then
echo "Searched from: $CHECK_PATH"
fi
echo ""
echo "To create an index, run:"
echo " /semq:index"
fi
```
## Output Example
```
Index found at: /home/user/project
Indexed files: 63
Total chunks: 142 (529.5 KB)
Model: BAAI/bge-small-en-v1.5
Last updated: 2025-11-15 22:30:45
```
## When to Use
Use `/semq:status` to:
- Check if a directory is indexed
- See how many files are indexed
- Verify which model is being used
- Check when index was last updated
- Troubleshoot search issues
## Related Commands
- `/semq:search <query>` - Search the index
- `/semq:index [path]` - Create or update index
- `/semq:here <query>` - Search with traversal
## Tips
1. **Before searching** - Run status to verify index exists
2. **After major changes** - Check if reindexing is needed
3. **Troubleshooting** - Use status to diagnose search issues
4. **Model verification** - Confirm BGE model is being used
## Configuration
The index configuration is stored in `.odino/config.json`:
```json
{
"model_name": "BAAI/bge-small-en-v1.5",
"embedding_batch_size": 16,
"chunk_size": 512,
"chunk_overlap": 50
}
```
To change configuration:
1. Edit `.odino/config.json` in the indexed directory
2. Reindex with `/semq:index --force`

73
plugin.lock.json Normal file
View File

@@ -0,0 +1,73 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:cadrianmae/claude-marketplace:plugins/semantic-search",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "9d7e9ed0fd0612cf572128722d9bf510b954e0a9",
"treeHash": "a67d2540e959b5c630ee9243e3d111155e87c9791cdd258f20076d07edb9d02c",
"generatedAt": "2025-11-28T10:14:28.300922Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "semantic-search",
"description": "Natural language semantic search for codebases and notes using odino CLI with BGE embeddings. Commands for indexing and searching with automatic directory traversal.",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "ff0b1df3fc9ff92f9d1991f658bdbf10bf489eb1011abfc3a352e63aa8f39ada"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "7f4c290da891fce66cb304167bb7fc0155fa5a2e8f5bd7a1ffe3f97c9bb605d2"
},
{
"path": "commands/here.md",
"sha256": "c65dfef51df2724b9c502d02f977ce5d62b89c48e9240cc2146c01b2f9fac157"
},
{
"path": "commands/search.md",
"sha256": "a18d128c6d7f2bd8cafafa13f31bc6cd658fd072469b23e52fcda521e102db4e"
},
{
"path": "commands/status.md",
"sha256": "bee6d4d8850eac49e30f6e10e9904c8a546a61f808feda6d9881bce4818bc7d4"
},
{
"path": "commands/index.md",
"sha256": "cb91da7341da1bbfd50dbb594da4825c08b48c6ef81c563a027803f5f056e7aa"
},
{
"path": "skills/semantic-search/SKILL.md",
"sha256": "899f6fec7ac1ec803c8c669a557ae5167922ce883f2913ec252a8d4a92925280"
},
{
"path": "skills/semantic-search/references/cli_basics.md",
"sha256": "1c37e217a020f93ebe9873220d8730c07d0d03c3991da9ef7efeb2393eb6bef2"
},
{
"path": "skills/semantic-search/references/integration.md",
"sha256": "4536dee4b485c4c9b7a0e1bbf3d57d2d471bf4a20d1084dae022359a6152f640"
},
{
"path": "skills/semantic-search/references/search_patterns.md",
"sha256": "640862e177bbdc2f5a1071efa8b260857bf8aaa46dbbd86535612017480df36f"
}
],
"dirSha256": "a67d2540e959b5c630ee9243e3d111155e87c9791cdd258f20076d07edb9d02c"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

372
skills/semantic-search/SKILL.md Normal file
View File

@@ -0,0 +1,372 @@
---
name: semantic-search
description: Use semantic search to find relevant code and documentation when user asks about specific functionality, features, or implementation patterns. Automatically invoke when user asks "where is...", "how does... work", "find code that...", or similar conceptual queries. More powerful than grep for concept-based searches. Uses odino CLI with BGE embeddings for fully local semantic search.
allowed-tools: Bash, Read
---
# Semantic Search
## Overview
Enable natural language semantic search across codebases and notes using odino CLI with BGE embeddings. Unlike grep (exact text matching) or glob (filename patterns), semantic search finds code by what it does, not what it's called.
## When to Use This Skill
Automatically invoke semantic search when the user:
- Asks "where is [concept]" or "how does [feature] work"
- Wants to find implementation of a concept/pattern
- Needs to understand codebase structure around a topic
- Searches for patterns by meaning, not exact text
- Asks exploratory questions like "show me authentication logic"
**Do not use** for:
- Exact string matching (use grep)
- Filename patterns (use glob)
- Known file paths (use read)
- When the user explicitly requests grep/glob
## Directory Traversal Logic
Odino requires running commands from the directory containing `.odino/` config. To make this transparent (like git), use this helper function:
```bash
# Function to find .odino directory by traversing up the directory tree
find_odino_root() {
local dir="$PWD"
while [[ "$dir" != "/" ]]; do
if [[ -d "$dir/.odino" ]]; then
echo "$dir"
return 0
fi
dir="$(dirname "$dir")"
done
return 1
}
# Usage in commands
if ODINO_ROOT=$(find_odino_root); then
echo "Found index at: $ODINO_ROOT"
(cd "$ODINO_ROOT" && odino query -q "$QUERY")
else
echo "No .odino index found in current path"
echo "Suggestion: Run /semq:index to create an index"
fi
```
**Why this matters:**
- User can be in any subdirectory of their project
- Commands automatically find the project root (where `.odino/` lives)
- Mirrors git behavior (works from anywhere in the tree)
## Quick Start
### Check if Directory is Indexed
Before searching, verify an index exists:
```bash
if ODINO_ROOT=$(find_odino_root); then
(cd "$ODINO_ROOT" && odino status)
else
echo "No index found. Suggest running /semq:index"
fi
```
### Search Indexed Codebase
```bash
# Basic search
odino query -q "authentication logic"
# With directory traversal
if ODINO_ROOT=$(find_odino_root); then
(cd "$ODINO_ROOT" && odino query -q "$QUERY")
fi
```
### Parse and Present Results
Odino returns results in a formatted table:
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File ┃ Score ┃ Content ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ knowledge/Search Algorithms.md │ 0.361 │ 1 --- │
│ │ │ 2 tags: [todo/stub] │
│ │ │ 3 module: CMPU 4010 │
│ │ │ ... │
│ │ │ 7 # Search Algorithms in AI │
│ │ │ ... │
└─────────────────────────────────┴──────────┴─────────────────────────────────┘
Found 2 results
```
**Enhanced workflow:**
1. Parse table to extract file paths, scores, and content previews
2. Read top 2-3 results (score > 0.3) for full context
3. Summarize findings with explanations
4. Use code-pointer to open most relevant file
5. Suggest follow-up queries or related concepts
## Query Inference
Transform user requests into better semantic queries with realistic output examples.
### Example 1: Conceptual Query
**User asks:** "error handling"
**Inferred query:** `error handling exception management try catch validation`
**Sample odino output:**
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File ┃ Score ┃ Content ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ knowledge/Error Handling.md │ 0.876 │ 1 --- │
│ │ │ 2 tags: [software-eng, best- │
│ │ │ 3 --- │
│ │ │ 4 # Error Handling │
│ │ │ 5 │
│ │ │ 6 Error handling is the proc │
│ │ │ 7 runtime errors gracefully │
│ │ │ 8 system stability. │
│ │ │ 9 │
│ │ │ 10 ## Key Concepts │
│ │ │ 11 - Try-catch blocks for syn │
│ │ │ 12 - Promise rejection handli │
│ │ │ 13 - Input validation to prev │
│ │ │ 14 - Logging errors for debug │
│ │ │ 15 - User-friendly error mess │
│ │ │ 16 │
│ │ │ 17 ## Best Practices │
│ │ │ 18 1. Fail fast - validate ea │
│ │ │ 19 2. Log with context - incl │
│ │ │ 20 3. Don't swallow errors - │
└─────────────────────────────────┴──────────┴─────────────────────────────────┘
```
### Example 2: Code Query
**User asks:** "DB connection code"
**Inferred query:**
```
database connection pooling setup
import mysql.connector
pool = mysql.connector.pooling.MySQLConnectionPool(
pool_name="mypool",
pool_size=5,
host="localhost",
database="mydb"
)
connection = pool.get_connection()
```
**Sample odino output:**
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File ┃ Score ┃ Content ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ src/db/connection.js │ 0.924 │ 1 const mysql = require('mys │
│ │ │ 2 │
│ │ │ 3 // Create connection pool │
│ │ │ 4 const pool = mysql.createP │
│ │ │ 5 host: process.env.DB_HOS │
│ │ │ 6 user: process.env.DB_USE │
│ │ │ 7 password: process.env.DB │
│ │ │ 8 database: process.env.DB │
│ │ │ 9 waitForConnections: true │
│ │ │ 10 connectionLimit: 10, │
│ │ │ 11 queueLimit: 0 │
│ │ │ 12 }); │
│ │ │ 13 │
│ │ │ 14 // Test connection │
│ │ │ 15 pool.getConnection((err, c │
│ │ │ 16 if (err) { │
│ │ │ 17 console.error('DB conn │
│ │ │ 18 process.exit(1); │
│ │ │ 19 } │
│ │ │ 20 console.log('Connected t │
└─────────────────────────────────┴──────────┴─────────────────────────────────┘
```
### Example 3: Algorithm Query (with code)
**User asks:** "BFS algorithm in Python"
**Inferred query:**
```
breadth first search BFS graph traversal queue
def bfs(graph, start):
visited = set()
queue = [start]
while queue:
node = queue.pop(0)
if node not in visited:
visited.add(node)
queue.extend(graph[node])
return visited
```
**Sample odino output:**
```
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File ┃ Score ┃ Content ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ knowledge/Search Algorithms.md │ 0.891 │ 1 --- │
│ │ │ 2 tags: [ai, algorithms] │
│ │ │ 3 module: CMPU 4010 AI │
│ │ │ 4 --- │
│ │ │ 5 # Search Algorithms in AI │
│ │ │ 6 │
│ │ │ 7 Algorithms for finding sol │
│ │ │ 8 problem spaces. Used in pa │
│ │ │ 9 game AI, and optimization. │
│ │ │ 10 │
│ │ │ 11 ## Types │
│ │ │ 12 │
│ │ │ 13 ### Uninformed Search │
│ │ │ 14 - **BFS**: Explores level │
│ │ │ 15 - **DFS**: Explores deeply │
│ │ │ 16 - **Uniform Cost**: Expand │
│ │ │ 17 │
│ │ │ 18 ### Informed Search │
│ │ │ 19 - **A***: Uses heuristic + │
│ │ │ 20 - **Greedy**: Only conside │
│ │ │ 21 - **Hill Climbing**: Local │
└─────────────────────────────────┴──────────┴─────────────────────────────────┘
```
### Inference Patterns
- **Expand abbreviations:** DB → database, auth → authentication
- **Code queries include sample code:** User asks "connection pooling" → Query includes Python example with `pool.get_connection()`
- **Use specified language:** User mentions "JavaScript" → Use JavaScript syntax in query
- **Default to Python:** No language specified → Use Python code examples
- **Add related concepts:** "search" → include BFS, DFS, A* terminology
- **Add context words:** "handling", "management", "setup", "configuration"
## Core Capabilities
### 1. Semantic Search
Find code by describing what it does, not exact text:
**User asks:** "Where is the database connection handling?"
**Workflow:**
1. Check if directory is indexed (use `find_odino_root`)
2. Run `odino query -q "database connection handling"`
3. Parse results and rank by score
4. Read top 2-3 results for context
5. Summarize findings with file paths
6. Suggest using code-pointer to open specific files
**Example:**
```bash
if ODINO_ROOT=$(find_odino_root); then
RESULTS=$(cd "$ODINO_ROOT" && odino query -q "database connection handling")
# Parse results, read top files, summarize
else
echo "No index found. Would you like me to index this directory?"
fi
```
### 2. Index Status Check
Verify indexing status before operations:
```bash
if ODINO_ROOT=$(find_odino_root); then
(cd "$ODINO_ROOT" && odino status)
# Shows: indexed files, model, last update
else
echo "No .odino index found"
fi
```
### 3. Integration with Other Tools
**Semantic search → code-pointer:**
```bash
# After finding relevant file
echo "Found authentication logic in src/auth/middleware.js:42"
echo "Opening file..."
code -g src/auth/middleware.js:42
```
**Semantic search → grep refinement:**
```bash
# Use semantic search to find the area
odino query -q "API endpoint handlers"
# Then use grep for exact matches in those files
grep -n "app.get\|app.post" src/routes/*.js
```
### 4. Handling Edge Cases
**No index found:**
```bash
if ! ODINO_ROOT=$(find_odino_root); then
echo "No semantic search index found in current path."
echo ""
echo "To create an index, run:"
echo " /semq:index"
echo ""
echo "This will index the current directory for semantic search."
fi
```
**Empty results:**
```bash
if [[ -z "$RESULTS" ]]; then
echo "No results found for query: $QUERY"
echo ""
echo "Suggestions:"
echo "- Try a different query (more general or specific)"
echo "- Verify the index is up to date (/semq:status)"
echo "- Consider using grep for exact text matching"
fi
```
## Slash Commands
This skill provides several slash commands for explicit control:
- **`/semq:search <query>`** - Search indexed codebase
- **`/semq:here <query>`** - Search with automatic directory traversal
- **`/semq:index [path]`** - Index directory for semantic search
- **`/semq:status [path]`** - Show indexing status and stats
## Best Practices
1. **Always check for index first** - Use `find_odino_root` before search operations
2. **Parse results clearly** - Show scores, file paths, and context
3. **Combine with other tools** - Use code-pointer for opening files, grep for exact matches
4. **Handle failures gracefully** - Suggest solutions when no index or no results
5. **Read top results** - Provide context by reading the most relevant files
6. **Use directory traversal** - Don't assume user is in project root
## Effective Query Patterns
Good queries are conceptual, not literal:
- ❌ "config.js" → Use glob instead
- ✅ "configuration loading logic"
- ❌ "validateEmail" → Use grep instead
- ✅ "email validation functions"
- ❌ "class AuthService" → Use grep instead
- ✅ "authentication service implementation"
## Technical Details
**Model:** BAAI/bge-small-en-v1.5 (33M params, ~133MB)
**Vector DB:** ChromaDB (stored in `.odino/chroma_db/`)
**Index location:** `.odino/` directory in project root
**Embedding batch size:** 16 (GPU) or 8 (CPU)
## Reference Documentation
For detailed information, see:
- **`references/cli_basics.md`** - Odino CLI syntax, commands, and options
- **`references/search_patterns.md`** - Effective query examples and tips
- **`references/integration.md`** - Workflows with code-pointer, grep, glob
Load these references as needed for deeper technical details or complex use cases.

226
skills/semantic-search/references/cli_basics.md Normal file
View File

@@ -0,0 +1,226 @@
# Odino CLI Basics
Reference guide for odino CLI syntax, commands, and options.
## Installation
```bash
# Install via pipx (recommended)
pipx install odino
# Verify installation
odino --version
```
## Core Commands
### `odino index`
Index a directory for semantic search.
```bash
# Index current directory
odino index
# Index specific directory
odino index /path/to/project
# Specify model (recommended: BGE for efficiency)
odino index --model BAAI/bge-small-en-v1.5
# Force reindex (ignores existing index)
odino index --force
```
**Configuration:**
- Creates `.odino/` directory in indexed location
- Stores config in `.odino/config.json`
- Stores embeddings in `.odino/chroma_db/`
**Default model:** EmmanuelEA/eea-embedding-gemma (600MB)
**Recommended model:** BAAI/bge-small-en-v1.5 (133MB, faster)
### `odino query`
Search indexed directory using natural language.
```bash
# Basic search
odino query -q "authentication logic"
# Search with custom number of results
odino query -q "database connections" -n 10
# Search specific path
odino query -q "error handling" -p /path/to/indexed/dir
```
**Options:**
- `-q, --query <QUERY>` - Natural language search query (required)
- `-n, --num-results <N>` - Number of results to return (default: 5)
- `-p, --path <PATH>` - Path to indexed directory (default: current dir)
**Output format:**
```
Score: 0.85 | Path: src/auth/middleware.js
Score: 0.78 | Path: src/auth/tokens.js
Score: 0.72 | Path: src/utils/validation.js
```
### `odino status`
Show indexing status and statistics.
```bash
# Status for current directory
odino status
# Status for specific path
odino status -p /path/to/project
```
**Output includes:**
- Number of indexed files
- Total chunks generated
- Model name
- Index location
- Last modified date
## Configuration File
Location: `.odino/config.json` in indexed directory
```json
{
"model_name": "BAAI/bge-small-en-v1.5",
"embedding_batch_size": 16,
"chunk_size": 512,
"chunk_overlap": 50
}
```
**Key settings:**
- `model_name` - Embedding model to use
- `embedding_batch_size` - Batch size for GPU/CPU (16 for GPU, 8 for CPU)
- `chunk_size` - Token length for text chunks
- `chunk_overlap` - Overlap between chunks
## .odinoignore File
Create `.odinoignore` in project root to exclude files/directories (gitignore syntax):
```
# Build artifacts
build/
dist/
*.pyc
__pycache__/
# Dependencies
node_modules/
venv/
.venv/
# Config files
.env
.env.local
*.secret
```
## Model Comparison
| Model | Size | Params | MTEB Score | Speed |
|-------|------|--------|------------|-------|
| eea-embedding-gemma | 600MB | 308M | 69.67 | Slower |
| bge-small-en-v1.5 | 133MB | 33M | ~62-63 | Faster |
**Recommendation:** Use BGE for most cases (smaller, faster, good quality)
## Common CLI Patterns
**Index with BGE model:**
```bash
odino index --model BAAI/bge-small-en-v1.5
```
**Search from subdirectory:**
```bash
# Requires finding .odino directory first (see SKILL.md)
cd project/src/utils
odino query -q "validation" -p ../..
```
**Reindex after code changes:**
```bash
odino index --force
```
**Check if directory is indexed:**
```bash
if [[ -d .odino ]]; then
echo "Directory is indexed"
odino status
else
echo "Directory is not indexed"
fi
```
## Performance Tips
1. **Use BGE model** - 78% smaller, 90% fewer parameters, only ~7 point MTEB drop
2. **Adjust batch size** - Use 16 for GPU, 8 for CPU
3. **Use .odinoignore** - Exclude build artifacts, dependencies, config files
4. **GPU acceleration** - Much faster indexing if CUDA available
5. **Chunking strategy** - Default 512 tokens works well for most code
## Troubleshooting
**"Command not found: odino"**
```bash
# Ensure pipx bin directory is in PATH
export PATH="$HOME/.local/bin:$PATH"
# Or reinstall
pipx install odino
```
**"No index found"**
```bash
# Check for .odino directory
ls -la .odino
# If missing, index first
odino index --model BAAI/bge-small-en-v1.5
```
**GPU out of memory**
```bash
# Reduce batch size in .odino/config.json
{
"embedding_batch_size": 8 # or even 4
}
# Then reindex
odino index --force
```
**Slow indexing**
```bash
# Use smaller model
odino index --model BAAI/bge-small-en-v1.5
# Reduce batch size if GPU memory limited
# Edit .odino/config.json: "embedding_batch_size": 8
```
## Exit Codes
- `0` - Success
- `1` - General error (no index, invalid path, etc.)
- `2` - Invalid arguments
## Environment Variables
Odino respects standard environment variables:
- `CUDA_VISIBLE_DEVICES` - GPU selection
- `HF_HOME` - Hugging Face cache directory (for model downloads)

449
skills/semantic-search/references/integration.md Normal file
View File

@@ -0,0 +1,449 @@
# Integration with Other Tools
Guide to combining semantic search with other Claude Code tools for powerful workflows.
## Tool Integration Matrix
| Tool | Purpose | When to Use After Semantic Search |
|------|---------|-----------------------------------|
| **code-pointer** | Open files at specific lines | When you want to view/edit found code |
| **grep** | Exact text matching | To find specific strings in sem-search results |
| **glob** | File pattern matching | To filter results by file type/location |
| **read** | Read file contents | To examine top semantic search results |
## Semantic Search → Code-Pointer
**Use case:** Open relevant files in VSCode after semantic search
### Basic Pattern
```bash
# 1. Find relevant code with semantic search
RESULTS=$(odino query -q "authentication middleware")
# Example output:
# Score: 0.89 | Path: src/middleware/auth.js
# Score: 0.82 | Path: src/middleware/jwt.js
# 2. Open top result in VSCode
code -g src/middleware/auth.js
```
### With Line Numbers
When you know the specific section:
```bash
# Find the file
odino query -q "JWT token generation"
# → src/auth/jwt.js
# Read the file to find exact line
grep -n "generateToken" src/auth/jwt.js
# → 42:function generateToken(user) {
# Open at specific line
code -g src/auth/jwt.js:42
```
### Automated Workflow
```bash
# Parse top result and open automatically
TOP_FILE=$(odino query -q "password hashing" | head -1 | cut -d'|' -f2 | xargs)
code -g "$TOP_FILE"
```
## Semantic Search → Grep
**Use case:** Find exact text in files discovered by semantic search
### Two-Stage Search
```bash
# Stage 1: Find relevant area with semantic search
odino query -q "database connection handling"
# → Found: src/db/connection.js, src/db/pool.js
# Stage 2: Find exact string in those files
grep -n "createConnection\|getConnection" src/db/*.js
```
### Narrowing Results
```bash
# Broad semantic search
odino query -q "API endpoints"
# → Returns 20+ files
# Narrow to specific endpoint with grep
grep -r "app.post('/users')" .
```
### Finding Patterns
```bash
# Find error handling code
odino query -q "error handling patterns"
# → src/middleware/error.js, src/utils/errors.js
# Find specific error types
grep -r "try.*catch\|throw new" src/middleware/error.js src/utils/errors.js
```
## Semantic Search → Glob
**Use case:** Filter semantic search results by file patterns
### File Type Filtering
```bash
# Find configuration code
odino query -q "application configuration"
# → Might return .js, .json, .yaml files
# Focus on just config files
find . -name "*.config.js" -o -name "config.json"
```
### Directory-Specific Search
```bash
# Find test files related to authentication
odino query -q "authentication testing"
# Then narrow to test directory
ls tests/**/*auth*.test.js
```
## Semantic Search → Read
**Use case:** Examine top results to understand context
### Standard Workflow
```bash
# 1. Semantic search
odino query -q "user registration logic"
# → Top 3 results:
# Score: 0.91 | Path: src/routes/auth.js
# Score: 0.85 | Path: src/services/user.js
# Score: 0.79 | Path: src/validators/user.js
# 2. Read top result
cat src/routes/auth.js
# 3. Read related files for full context
cat src/services/user.js
cat src/validators/user.js
```
### With Summary
```bash
# Find relevant code
odino query -q "payment processing"
# Read top results and summarize
echo "## Payment Processing Implementation"
echo ""
echo "### Main handler:"
head -20 src/routes/payment.js
echo ""
echo "### Service layer:"
head -20 src/services/payment.js
```
## Complete Workflow Examples
### Example 1: Debugging a Feature
**Goal:** Fix bug in user login
```bash
# 1. Find login code with semantic search
odino query -q "user login authentication"
# → src/routes/auth.js (0.92)
# → src/services/auth.js (0.88)
# → src/middleware/passport.js (0.81)
# 2. Read main login handler
cat src/routes/auth.js | grep -A 20 "post.*login"
# 3. Find error handling in that file
grep -n "catch\|error" src/routes/auth.js
# 4. Open at error handling line
code -g src/routes/auth.js:67
```
### Example 2: Understanding a Feature
**Goal:** Understand how caching works
```bash
# 1. Find caching implementation
odino query -q "caching implementation and configuration"
# → src/cache/redis.js (0.94)
# → src/config/cache.js (0.87)
# → src/middleware/cache.js (0.79)
# 2. Read configuration first
cat src/config/cache.js
# 3. Then read main implementation
cat src/cache/redis.js
# 4. Find usage examples
grep -r "cache.get\|cache.set" src/ | head -10
# 5. Open implementation in editor
code -g src/cache/redis.js
```
### Example 3: Refactoring
**Goal:** Replace all database connection code
```bash
# 1. Find all database connection code
odino query -q "database connection creation and management"
# → Returns 5 files
# 2. Find exact connection creation calls
grep -rn "createConnection\|mysql.connect\|pg.Pool" src/
# 3. Check each file with semantic context
odino query -q "connection pooling"
odino query -q "database transaction handling"
# 4. Open files for editing
code -g src/db/connection.js src/db/pool.js src/db/transaction.js
```
### Example 4: Code Review
**Goal:** Review all authentication changes
```bash
# 1. Find authentication code
odino query -q "authentication and authorization logic"
# 2. Find recent changes (combine with git)
git diff main -- src/auth/ src/middleware/auth.js
# 3. Semantic search for related security code
odino query -q "security validation and sanitization"
# 4. Check for vulnerabilities
grep -r "eval\|exec\|innerHTML" src/auth/
```
## Advanced Integration Patterns
### Cascading Search
Start broad, narrow progressively:
```bash
# Level 1: Semantic search (broad)
odino query -q "user management"
# → 15 files
# Level 2: File pattern (medium)
find src/ -path "*/users/*" -name "*.js"
# → 8 files
# Level 3: Grep (narrow)
grep -l "updateUser\|deleteUser" src/users/*.js
# → 3 files
# Level 4: Open specific files
code -g src/users/controller.js src/users/service.js
```
### Context Building
Build understanding layer by layer:
```bash
# 1. High-level architecture
odino query -q "application architecture and structure"
# 2. Specific subsystem
odino query -q "data access layer implementation"
# 3. Specific functionality
odino query -q "CRUD operations for users"
# 4. Exact implementation
grep -A 30 "function createUser" src/data/users.js
```
### Verification Workflow
Verify semantic search results:
```bash
# 1. Semantic search
odino query -q "input validation"
# → src/validators/user.js (0.87)
# 2. Verify by reading
cat src/validators/user.js | head -50
# 3. Find all validation usage
grep -r "import.*validator" src/
# 4. Cross-reference with tests
odino query -q "validation testing"
```
## When to Use Each Tool
### Use semantic search when:
- Exploring unfamiliar codebase
- Finding conceptual implementations
- Locating cross-cutting concerns
- Understanding feature architecture
### Use grep when:
- Searching for exact strings
- Finding variable/function usages
- Locating error messages
- Searching for TODOs/FIXMEs
### Use glob when:
- Finding files by name pattern
- Filtering by file type
- Working with specific directories
- Batch operations on matching files
### Use code-pointer when:
- Need to view/edit specific code
- Opening files at exact lines
- Navigating to definitions
- Debugging specific sections
### Use read when:
- Examining file contents
- Understanding context
- Checking configuration
- Reviewing small files
## Tool Selection Decision Tree
```
Need to find code?
├─ Know exact string? → Use grep
├─ Know filename pattern? → Use glob
├─ Know file path? → Use read
└─ Know concept only? → Use semantic search
└─ Got results? → Use code-pointer to open
└─ Need exact line? → Use grep in file
```
## Best Practices
1. **Start semantic, end specific**
- Semantic search → Find area
- Grep → Find exact code
- Code-pointer → Open for editing
2. **Read before editing**
- Semantic search → Find files
- Read → Understand context
- Code-pointer → Open in editor
3. **Verify with multiple tools**
- Semantic search → Find candidates
- Grep → Verify it's the right code
- Read → Confirm implementation
4. **Build context progressively**
- Semantic search → High-level structure
- Semantic search → Specific subsystem
- Read/Grep → Detailed implementation
5. **Combine for complex tasks**
- Semantic search → Find authentication
- Grep → Find specific function
- Code-pointer → Open file
- Read → Check related files
## Performance Tips
1. **Cache semantic results**
- Run semantic search once
- Use results for multiple grep/read operations
2. **Narrow scope early**
- Use semantic search to identify directory
- Then use grep/glob only in that directory
3. **Batch file operations**
- Collect file paths from semantic search
- Read multiple files in one pass
4. **Use appropriate tool**
- Don't use semantic search for exact strings
- Don't use grep for conceptual searches
## Common Mistakes to Avoid
**❌ Using semantic search for exact matches:**
```bash
# Wrong
odino query -q "function validateEmail"
# Right
grep -r "function validateEmail" .
```
**❌ Using grep for concepts:**
```bash
# Wrong (might miss variations)
grep -r "auth" .
# Right
odino query -q "authentication implementation"
```
**❌ Not reading semantic results:**
```bash
# Wrong (blindly trusting results)
odino query -q "payment" | head -1 | cut -d'|' -f2
# Right (verify first)
odino query -q "payment"
cat [top-result] # Verify it's actually payment code
```
**❌ Opening too many files:**
```bash
# Wrong
odino query -q "validation" | while read line; do
code -g "$(echo $line | cut -d'|' -f2)"
done # Opens 20+ files
# Right
odino query -q "validation" | head -3
# Review, then open specific files
code -g src/validators/user.js
```
## Summary
**Effective integration means:**
- Using the right tool for each task
- Starting broad (semantic) and narrowing (grep)
- Verifying results before acting
- Building context progressively
- Combining tools for complex workflows
**Remember:**
- Semantic search → Finding concepts
- Grep → Finding exact text
- Glob → Finding files
- Read → Understanding context
- Code-pointer → Editing code

346
skills/semantic-search/references/search_patterns.md Normal file
View File

@@ -0,0 +1,346 @@
# Effective Semantic Search Patterns
Guide to crafting effective semantic search queries and interpreting results.
## Query Design Principles
### Be Conceptual, Not Literal
Semantic search works best with conceptual queries that describe **what the code does**, not what it's named.
**❌ Poor queries (too literal):**
- "validateEmail" → Use grep instead
- "config.js" → Use glob instead
- "class AuthService" → Use grep instead
- "TODO" → Use grep instead
**✅ Good queries (conceptual):**
- "email validation logic"
- "configuration loading and parsing"
- "authentication service implementation"
- "incomplete features or pending work"
### Use Natural Language
Write queries as you would explain the concept to a colleague.
**❌ Keyword stuffing:**
- "db connect pool config"
**✅ Natural language:**
- "database connection pooling configuration"
### Be Specific When Needed
Balance specificity with generality based on what you're looking for.
**Too general:**
- "functions" → Will match everything
- "code" → Will match everything
**Too specific:**
- "JWT token validation using bcrypt with salt rounds set to 10" → Too narrow
**Just right:**
- "JWT token validation"
- "password hashing and verification"
## Common Query Patterns
### Finding Implementation
**Pattern:** "[concept] implementation" or "how [feature] works"
```bash
odino query -q "authentication implementation"
odino query -q "how caching works"
odino query -q "error handling implementation"
```
### Finding Configuration
**Pattern:** "[system/feature] configuration" or "[thing] setup"
```bash
odino query -q "database configuration"
odino query -q "API endpoint setup"
odino query -q "logging configuration"
```
### Finding Patterns
**Pattern:** "[pattern/technique] usage" or "examples of [pattern]"
```bash
odino query -q "middleware usage patterns"
odino query -q "dependency injection examples"
odino query -q "async/await error handling"
```
### Finding by Purpose
**Pattern:** "code that [does something]" or "[action] logic"
```bash
odino query -q "code that validates user input"
odino query -q "file upload logic"
odino query -q "payment processing"
```
### Finding Documentation
**Pattern:** "[topic] documentation" or "how to [task]"
```bash
odino query -q "API documentation"
odino query -q "how to deploy the application"
odino query -q "setup instructions"
```
## Result Interpretation
### Understanding Scores
Odino returns results with similarity scores (0.0 to 1.0):
- **0.85-1.0**: Highly relevant, almost certainly what you're looking for
- **0.70-0.84**: Likely relevant, worth checking
- **0.60-0.69**: Possibly relevant, may contain related concepts
- **<0.60**: Weakly related, probably not useful
**Example output:**
```
Score: 0.92 | Path: src/auth/jwt.js # Definitely check this
Score: 0.78 | Path: src/middleware/auth.js # Likely relevant
Score: 0.64 | Path: src/utils/crypto.js # Maybe related
Score: 0.51 | Path: src/config/index.js # Probably not it
```
### When to Read Files
**Always read:** Top 1-2 results (score > 0.80)
**Sometimes read:** Next 2-3 results (score 0.65-0.80) for context
**Rarely read:** Results with score < 0.65
### Combining Results
Often the answer spans multiple files:
```bash
odino query -q "user authentication flow"
# Results might include:
# - Login endpoint (score: 0.89)
# - JWT generation (score: 0.85)
# - Password verification (score: 0.82)
# - Session management (score: 0.76)
```
Read top results to understand the complete picture.
## Refinement Strategies
### Too Many Results
Make query more specific:
```bash
# Too broad
odino query -q "validation"
# Better
odino query -q "email format validation"
```
### Too Few Results
Make query more general:
```bash
# Too narrow
odino query -q "SHA256 password hashing with bcrypt"
# Better
odino query -q "password hashing"
```
### Wrong Results
Try different phrasing:
```bash
# If "API endpoint handlers" doesn't work well
odino query -q "route definitions"
odino query -q "HTTP request handlers"
odino query -q "REST API implementation"
```
## Advanced Patterns
### Multi-Concept Queries
Combine related concepts for broader coverage:
```bash
odino query -q "authentication and authorization logic"
odino query -q "database queries and ORM usage"
odino query -q "error handling and logging"
```
### Feature-Specific Queries
Target specific features or subsystems:
```bash
odino query -q "user registration feature"
odino query -q "shopping cart functionality"
odino query -q "notification system"
```
### Cross-Cutting Concerns
Find patterns that span the codebase:
```bash
odino query -q "error handling patterns"
odino query -q "input validation across endpoints"
odino query -q "database transaction usage"
```
## Query Examples by Use Case
### Code Exploration
"I'm new to this codebase, where do I start?"
```bash
odino query -q "main application entry point"
odino query -q "core business logic"
odino query -q "primary data models"
```
### Bug Hunting
"There's a bug in feature X, where's the code?"
```bash
odino query -q "user login functionality"
odino query -q "payment processing logic"
odino query -q "email sending implementation"
```
### Refactoring
"I need to change how we do X across the codebase"
```bash
odino query -q "database connection creation"
odino query -q "API key validation"
odino query -q "date formatting and parsing"
```
### Learning Patterns
"How does this codebase handle X?"
```bash
odino query -q "dependency injection patterns"
odino query -q "testing approach and examples"
odino query -q "configuration management"
```
## When Semantic Search Doesn't Help
Use other tools when:
1. **Exact string needed** - Use `grep`
```bash
grep -r "validateEmail" .
```
2. **Filename patterns** - Use `glob` or `find`
```bash
find . -name "*config*.js"
```
3. **Known file location** - Use `read` directly
```bash
# Just read the file
cat src/config/database.js
```
4. **Symbol definitions** - Use language-specific tools
```bash
# For Python
grep -r "class AuthService" .
# For JavaScript
grep -r "export.*AuthService" .
```
## Combining Tools Workflow
**Best practice:** Start semantic, narrow with grep/glob
```bash
# 1. Find the general area with semantic search
odino query -q "database migrations"
# → Found: migrations/2024-01-15-add-users.sql
# 2. Narrow to specific files/patterns
find migrations/ -name "*users*"
# 3. Search for exact strings in those files
grep -n "CREATE TABLE" migrations/*users*.sql
```
## Tips for Better Results
1. **Use verbs and nouns** - "validates user input" not just "validation"
2. **Include context** - "email validation in registration" not just "email"
3. **Think about purpose** - What does the code **do**, not what it's **called**
4. **Try synonyms** - "authentication" vs "login" vs "sign in"
5. **Be patient** - Try 2-3 query variations if first doesn't work
6. **Check top 3-5 results** - Sometimes #3 is the best match
7. **Combine with file reading** - Read top results to confirm relevance
## Anti-Patterns to Avoid
**❌ Searching for variable names:**
```bash
odino query -q "userEmail" # Use grep instead
```
**❌ Searching for exact error messages:**
```bash
odino query -q "Error: Connection refused" # Use grep instead
```
**❌ Searching for file paths:**
```bash
odino query -q "src/utils/validation.js" # Use find/glob instead
```
**❌ Searching for TODOs/comments:**
```bash
odino query -q "TODO fix this" # Use grep instead
```
**❌ Overly generic queries:**
```bash
odino query -q "code" # Way too broad
```
## Summary
**Good semantic queries are:**
- Conceptual, not literal
- Natural language, not keywords
- Focused on purpose/behavior
- Appropriately specific
**After getting results:**
- Check scores (> 0.70 is good)
- Read top 2-3 files for context
- Combine with grep/glob for precision
- Iterate query if needed