gh-cadrianmae-claude-marketplace-plugins-semantic-search/skills/semantic-search/references/integration.md

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

# 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:

# 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

# 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

# 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

# Broad semantic search
odino query -q "API endpoints"
# → Returns 20+ files

# Narrow to specific endpoint with grep
grep -r "app.post('/users')" .

Finding Patterns

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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:

# 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:

# 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:

# 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:

# Wrong
odino query -q "function validateEmail"

# Right
grep -r "function validateEmail" .

❌ Using grep for concepts:

# Wrong (might miss variations)
grep -r "auth" .

# Right
odino query -q "authentication implementation"

❌ Not reading semantic results:

# 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:

# 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