curl -fsSL https://raw.githubusercontent.com/jbenshetler/mcp-ragex/refs/heads/main/install.sh | bash

cd your-project
ragex start                    # Index your codebase (1-5 minutes)
ragex register claude | sh     # Connect to Claude Code

ragex search "auth functions"     # Semantic search
ragex search "async def" --regex   # Pattern search

curl -sSL https://raw.githubusercontent.com/jbenshetler/mcp-ragex/main/install.sh | bash

# Enable network access + better model (recommended)
curl -sSL https://raw.githubusercontent.com/jbenshetler/mcp-ragex/main/install.sh | bash -s -- --network --model balanced

# Force CPU version (smaller download)
curl -sSL https://raw.githubusercontent.com/jbenshetler/mcp-ragex/main/install.sh | bash -s -- --cpu --network

# Force CUDA (NVIDIA GPU)
curl -sSL https://raw.githubusercontent.com/jbenshetler/mcp-ragex/main/install.sh | bash -s -- --cuda --model accurate

curl -sSL https://get.ragex.dev -o install.sh
cat install.sh  # Review the script
bash install.sh --network --model balanced

cd your-project
ragex start                    # Index codebase (1-5 minutes)
ragex register claude | sh     # Connect to Claude Code

# Test semantic search
ragex search "auth functions"     # Finds authentication code
ragex search "error handling"     # Finds error handling patterns
ragex search "database queries"   # Finds DB-related code

# Test regex search  
ragex search "async def" --regex   # Find async functions
ragex search "TODO|FIXME" --regex  # Find code comments

You: "Add user authentication to this Express app"
Claude: "I'll create a comprehensive authentication system..."
        [Creates 200 lines of new auth code]
        [Duplicates existing middleware patterns]
        [Ignores your error handling conventions]

You: "Add user authentication to this Express app"
Claude: "I found your existing auth middleware at middleware/auth.js:15
         and your user model at models/User.js:8. Let me extend these
         patterns to add the authentication you need..."
        [Reuses existing patterns]
        [Follows your conventions]
        [Builds on your architecture]

# Work project with accurate model
cd ~/work/api-server
ragex start --model accurate
# → Creates: ragex_1000_a1b2c3d4ef567890

# Personal project with fast model  
cd ~/personal/blog
ragex start --model fast
# → Creates: ragex_1000_f9e8d7c6b5a43210

ragex ls -l
# PROJECT          ID                         MODEL     INDEXED   PATH
# api-server       ragex_1000_a1b2c3d4ef567890 accurate  yes      ~/work/api-server
# blog             ragex_1000_f9e8d7c6b5a43210 fast      yes      ~/personal/blog

# Semantic search (natural language)
ragex search "functions that validate user input"
ragex search "code that handles file uploads"
ragex search "database connection error handling"
ragex search "JWT token verification logic"

# Regex search (exact patterns)
ragex search "async def.*test" --regex    # Async test functions
ragex search "app\.get\(.*api" --regex      # Express API routes
ragex search "interface.*Props" --regex    # TypeScript interfaces

# Search with limits and JSON output
ragex search "auth" --limit 10 --json     # Top 10 results as JSON

# List and inspect projects
ragex ls                         # Show all your projects
ragex ls -l                      # Detailed view with models/status
ragex ls "api-*"                 # Filter projects by pattern
ragex info                       # Current project details

# Clean up old projects
ragex rm "old-project-*"         # Remove projects matching pattern
ragex rm ragex_1000_abc123       # Remove by specific ID

# Configuration
ragex configure                  # Show current config
ragex configure --cpu            # Switch to CPU mode
ragex configure --cuda           # Switch to CUDA mode

# Code Search Guidelines

**IMPORTANT: This project has RAGex MCP enabled for intelligent code search.**

## Search Strategy (Priority Order)

1. **FIRST: Use RAGex MCP tools** - Semantic understanding of your codebase
   - `search_code()` with semantic mode for concepts: "auth functions", "error handling"
   - `search_code()` with regex mode for patterns: "async def.*test", "TODO|FIXME"
   - `search_code_simple()` for quick searches with auto-detection

2. **FALLBACK: Use built-in search tools** - Only if RAGex fails or is unavailable
   - `Grep` for text patterns
   - `Glob` for file discovery

## RAGex Search Modes

RAGex automatically detects the best search mode:

- **Semantic Mode**: Natural language queries
  - `"functions that handle user authentication"`
  - `"error handling for database connections"`
  - `"code that validates JWT tokens"`

- **Regex Mode**: Pattern matching (use `--regex` or detected automatically)
  - `"async def.*test"` → finds async test functions
  - `"app\.get\(.*api"` → finds Express API routes
  - `"interface.*Props"` → finds TypeScript interfaces

- **Symbol Mode**: Exact names (detected automatically)
  - `"UserService"` → finds UserService class
  - `"validateInput"` → finds validateInput function

## Effective Query Examples

```bash
# Semantic search (recommended)
search_code("user authentication and session management")
search_code("database connection error handling")
search_code("file upload processing logic")
search_code("JWT token validation functions")

# Regex patterns for exact matching
search_code("async def.*test", mode="regex")
search_code("TODO|FIXME", mode="regex")
search_code("interface.*Props", mode="regex")

# Simple interface (auto-detects everything)
search_code_simple("auth middleware")
search_code_simple("error handlers")

**Why this helps:**
- Prioritizes RAGex MCP tools over built-in search
- Provides concrete examples for different search modes
- Guides Claude toward code reuse and architectural consistency
- Sets clear expectations for search capabilities and workflow

## 📋 Installation Details

<details>
<summary>Click to expand full installation guide from doc/installation-guide.md</summary>

### Quick Start (One-Line Installation)

#### Basic Installation (Auto-Detection)
```bash
curl -fsSL https://raw.githubusercontent.com/jbenshetler/mcp-ragex/refs/heads/main/install.sh | bash

# Install with network access enabled and balanced model as default
curl -fsSL https://raw.githubusercontent.com/jbenshetler/mcp-ragex/refs/heads/main/install.sh | bash -s -- --network --model balanced

# Force CPU version (smaller image) with network access
curl -fsSL https://raw.githubusercontent.com/jbenshetler/mcp-ragex/refs/heads/main/install.sh | bash -s -- --cpu --network --model accurate

# Force CUDA version (requires NVIDIA GPU)
curl -fsSL https://raw.githubusercontent.com/jbenshetler/mcp-ragex/refs/heads/main/install.sh | bash -s -- --cuda --model balanced

curl -fsSL https://raw.githubusercontent.com/jbenshetler/mcp-ragex/refs/heads/main/install.sh | bash

curl -fsSL https://raw.githubusercontent.com/jbenshetler/mcp-ragex/refs/heads/main/install.sh | bash -s -- --network

ragex --help
ragex info

cd your-project
ragex index .          # Index current directory
ragex search "query"   # Search your code

ragex configure        # Show current configuration
ragex ls              # List indexed projects

❌ Docker not found. Please install Docker first.

❌ Docker daemon not running. Please start Docker.

❌ Unsupported architecture: s390x

# Get the registration command
ragex register claude

# Run the output command (example):
claude mcp add ragex ~/.local/bin/ragex-mcp --scope project

# Work on different projects simultaneously
cd ~/work/api-server && ragex start --model accurate
cd ~/personal/blog && ragex start --model fast 
cd ~/opensource/cli-tool && ragex start --model balanced

# Switch between projects automatically
ragex ls                        # See all projects
cd ~/work/api-server           # RAGex automatically uses api-server index
ragex search "authentication"   # Searches only api-server code

# Customize behavior
export RAGEX_EMBEDDING_MODEL=balanced    # Default model for new projects
export RAGEX_LOG_LEVEL=DEBUG             # Enable debug logging
export RAGEX_DOCKER_IMAGE=custom:tag     # Use custom Docker image

# Log rotation settings
export RAGEX_LOG_MAX_SIZE=100m           # Max log file size
export RAGEX_LOG_MAX_FILES=5             # Number of rotated logs to keep

# View logs
ragex log                       # Current project logs
ragex log -f                    # Follow logs in real-time
ragex log --tail 50            # Last 50 lines

# Status and info
ragex status                    # Check daemon status
ragex info                      # Project details
ragex configure                 # Current configuration

# Development mode
ragex bash                      # Get shell inside container
RAGEX_DEBUG=1 ragex start      # Enable debug output

# Your data is isolated by user ID
docker volume ls | grep ragex_user_$(id -u)

# Project data structure:
# /data/models/                   # Shared embedding models (90MB-1.3GB)
# /data/projects/ragex_1000_*/    # Individual project indexes
#   ├── chroma_db/               # Vector database  
#   └── project_info.json        # Project metadata

# Backup a project
ragex export my-project backup.tar.gz

# Check disk usage
ragex ls -l                     # Shows index sizes

# Clean up old projects
ragex rm "test-*"               # Remove test projects
ragex rm ragex_1000_old123      # Remove specific project

# Complete removal (WARNING: Deletes all indexed data)
# Stop all ragex containers
docker ps -a -f "name=ragex_" -q | xargs -r docker stop
docker ps -a -f "name=ragex_" -q | xargs -r docker rm

# Remove images and volumes
docker images "*ragex*" -q | xargs -r docker rmi
docker volume ls -f "name=ragex_user_" -q | xargs -r docker volume rm

# Remove binaries and config
rm -rf ~/.config/ragex ~/.local/bin/ragex ~/.local/bin/ragex-mcp

# Unregister from Claude Code
claude mcp remove ragex --scope project

# When Claude Code runs:
claude mcp add ragex /home/user/.local/bin/ragex

# It communicates like this:
Claude Code ←→ ragex script ←→ Docker container ←→ MCP Server
           stdin/stdout    stdin/stdout      stdin/stdout

/app/                     # Application code (read-only)
├── src/                  # Source code
├── scripts/              # Utility scripts
├── requirements.txt      # Python dependencies
└── entrypoint.sh        # Container entrypoint

/data/                    # User-specific persistent data (volume)
├── models/              # Shared embedding models (400MB-1.3GB)
└── projects/            # Project-specific data
    ├── ragex_1000_abc123/  # Project 1
    │   ├── chroma_db/      # ChromaDB vector database  
    │   └── project_info.json # Project metadata
    └── ragex_1000_def456/  # Project 2
        ├── chroma_db/
        └── project_info.json

/workspace/              # Your code (volume, read-only)
└── [current project]    # Code to be indexed

# Project identification (automatically set by wrapper)
WORKSPACE_PATH=/path/to/your/project    # Workspace being indexed
PROJECT_NAME=ragex_1000_abc123          # Generated project ID

# Data directories (automatically configured)
RAGEX_PROJECT_DATA_DIR=/data/projects/ragex_1000_abc123  # Project data
RAGEX_CHROMA_PERSIST_DIR=/data/projects/ragex_1000_abc123/chroma_db  # ChromaDB
TRANSFORMERS_CACHE=/data/models         # Shared model cache
SENTENCE_TRANSFORMERS_HOME=/data/models # Sentence transformers cache

# User configuration
RAGEX_EMBEDDING_MODEL=fast              # Model preset (fast/balanced/accurate)
RAGEX_CHROMA_COLLECTION=code_embeddings # Collection name

# System configuration
RAGEX_LOG_LEVEL=INFO                    # Log level (DEBUG, INFO, WARN, ERROR) - default: INFO
LOG_LEVEL=INFO                          # Fallback log level (RAGEX_LOG_LEVEL takes precedence)
DOCKER_CONTAINER=true                   # Indicates running in container

# Production setup with resource limits
docker compose -f docker-compose.prod.yml up -d

# Check status
docker compose -f docker-compose.prod.yml ps

# View logs
docker compose -f docker-compose.prod.yml logs ragex

cd /path/to/your/project
claude mcp add ragex /path/to/mcp-ragex/ragex --scope project

# Option 1: Using wrapper script
claude mcp add ragex /path/to/mcp-ragex/mcp_ragex.sh --scope project

# Option 2: Direct Python command
claude mcp add ragex uv run /path/to/mcp-ragex/src/server.py --scope project

{
  "mcpServers": {
    "ragex": {
      "command": "/path/to/mcp-ragex/ragex",
      "env": {
        "RAGEX_DATA_DIR": "/path/to/persistent/data"
      }
    }
  }
}

# In Claude Code, use the /mcp command
/mcp

● Let me try a broader semantic search:

● Let me search for admin endpoints:
 ⎿  Interrupted by user

> /exit
 ⎿  (no content)

> Try the ragex semantic search again.

● Task(Search for reindex endpoints)
 ⎿  Done (8 tool uses · 79.3k tokens · 1m 32.2s)

● Based on the search results, I found the department reindexing endpoints. The main force reindex endpoint is:

 POST /admin/reindex/department in /docprocessor/workflows_api.py (line 834)

● I'll search for the function that adds documents to OpenSearch and check the field structure, then verify all 11 documents have extracted text.

● Task(Task: Find OpenSearch indexing function

   Prompt: Search for the function that indexes documents to OpenSearch. Look for:
   1. Functions that create or update documents in OpenSearch
   2. The field names used when indexing, particularly for extracted text
   3. Index operations, PUT or POST requests to OpenSearch
   4. Document structure being sent to OpenSearch

   Use search terms like:
   - opensearch index document
   - _doc PUT POST
   - index_document
   - create_document
   - extracted_text content text)
 ⎿  Search(pattern: "index.*document|create.*document|update.*document", path: "undefined")
      ⎿  Found 55 files
         /home/jeff/clients/search/contextsearch/tests/ui/README.md
         /home/jeff/clients/search/contextsearch/tests/ocr/output_metadata.json
         /home/jeff/clients/search/contextsearch/tests/ocr/output_rmeta_fixed.json
         /home/jeff/clients/search/contextsearch/tests/needs_porting/test_workflow_implementation.py
         /home/jeff/clients/search/contextsearch/tests/obsolete/test_workflow_celery_integration.py
         /home/jeff/clients/search/contextsearch/tests/obsolete/test_workflow_integration.py
         /home/jeff/clients/search/contextsearch/tests/docprocessor/test_workflows_real_files.py
         /home/jeff/clients/search/contextsearch/tests/functional/cache/test_cache_repopulation.py
         /home/jeff/clients/search/contextsearch/tests/functional/cache/test_comprehensive_cache_validation.py
         /home/jeff/clients/search/contextsearch/tests/functional/integration/filesystem_scanner.py
         /home/jeff/clients/search/contextsearch/tests/functional/nlp/test_batch_size_one.py
         /home/jeff/clients/search/contextsearch/tests/functional/search/test_date_filtering.py
         /home/jeff/clients/search/contextsearch/tests/functional/search/test_entity_filtering.py
         /home/jeff/clients/search/contextsearch/tests/functional/search/test_force_reindexing.py
         /home/jeff/clients/search/contextsearch/samples/simulate_tasks.py

# Claude Code automatically detects the best search mode
search_code("DatabaseConnection")              # → symbol mode
search_code("functions that handle auth")      # → semantic mode  
search_code("error.*Exception")                # → regex mode

# Symbol search - when you know exact names
search_code("AuthenticationService")

# Semantic search - when you know the concept
search_code("functions that validate user input", mode="semantic")

# Regex search - when you know the pattern
search_code("handleError.*Exception", mode="regex")

# Find authentication-related code
search_code("functions that handle user authentication")

# Find error handling patterns
search_code("error handling for database connections")

# Find file processing code
search_code("code that processes uploaded files")

# Find validation logic
search_code("functions that validate user input")

# Find specific classes
search_code("UserService")

# Find specific functions
search_code("validateInput")

# Find methods
search_code("submitToQueue")

# Find async functions
search_code("async def", mode="regex")

# Find TODO comments
search_code("TODO|FIXME", mode="regex")

# Find error handling blocks
search_code("try.*except", mode="regex")

# Check available search modes
get_search_capabilities()

# Just search - auto-detects everything
search_code_simple("database connection error")

search_code("submit_file", format="raw")

# Search only Python files
search_code("class.*User", file_types=["py"])

# Search specific directories
search_code("test_", paths=["tests", "src/tests"])

# Combine filters
search_code("async def", file_types=["py"], paths=["src"])

# Set log level before starting daemon
export RAGEX_LOG_LEVEL=DEBUG
ragex start

# Or set for a single command
RAGEX_LOG_LEVEL=DEBUG ragex start

# For very verbose debugging (generates lots of output)
RAGEX_LOG_LEVEL=TRACE ragex start

# To change log level after daemon is running:
ragex stop
RAGEX_LOG_LEVEL=DEBUG ragex start

# View daemon logs for current project
ragex log

# Follow logs in real-time
ragex log -f

# View last 50 lines
ragex log --tail 50

# View logs for specific project
ragex log project-name

# View MCP server logs (when using with Claude)
tail -f /tmp/ragex-mcp.log

# Set custom log rotation limits
export RAGEX_LOG_MAX_SIZE=100m      # Maximum size per log file
export RAGEX_LOG_MAX_FILES=5        # Maximum number of log files to keep

# Apply settings when starting daemon
ragex stop
ragex start

# View current log rotation settings
ragex configure

graph TD
    A[Claude Code] -->|MCP Protocol| B[RAGex Server]
    B --> C[Query Router]
    C -->|Semantic Queries| D[Vector Search]
    C -->|Regex Patterns| E[Ripgrep Search]
    C -->|Symbol Names| F[Tree-sitter Search]
    
    D --> G[ChromaDB]
    D --> H[Sentence Transformers]
    E --> I[ripgrep]
    F --> J[Tree-sitter AST]
    
    K[Docker Container] --> L[Project Isolation]
    L --> M[User Volume]
    M --> N[Project 1 Index]
    M --> O[Project 2 Index]
    M --> P[Shared Models]

flowchart LR
    A[User Query] --> B{Query Analysis}
    B -->|"auth login"| C[Semantic Mode]
    B -->|"async def.*"| D[Regex Mode] 
    B -->|"handleSubmit"| E[Symbol Mode]
    
    C --> F[Vector Similarity]
    D --> G[Pattern Matching]
    E --> H[AST Analysis]
    
    F --> I{Results Found?}
    G --> I
    H --> I
    
    I -->|Yes| J[Return Results]
    I -->|No| K[Try Fallback Mode]
    K --> J

# Dependencies
node_modules/, .venv/, __pycache__/, vendor/

# Build artifacts  
build/, dist/, target/, .next/, .nuxt/

# IDE files
.vscode/, .idea/, *.swp, .DS_Store

# Logs and temp
*.log, .tmp/, .cache/

# Media files
*.jpg, *.png, *.mp4, *.zip, *.pdf

# Get the code
git clone https://github.com/jbenshetler/mcp-ragex.git
cd mcp-ragex

# Local development setup
make install-cpu && ragex start

# Run tests
uv run tests/test_server.py
pytest tests/

# Build documentation
make docs