450 lines
10 KiB
Markdown
450 lines
10 KiB
Markdown
# 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
|