Initial commit

2025-11-29 18:03:17 +08:00
commit df4751ce28
11 changed files with 2308 additions and 0 deletions
--- a/commands/here.md
+++ b/commands/here.md
@@ -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
--- a/commands/index.md
+++ b/commands/index.md
@@ -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`.
--- a/commands/search.md
+++ b/commands/search.md
@@ -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
--- a/commands/status.md
+++ b/commands/status.md
@@ -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`