{"id":46144769,"url":"https://github.com/reflex-search/reflex","last_synced_at":"2026-03-02T07:03:23.074Z","repository":{"id":321849042,"uuid":"1087387030","full_name":"reflex-search/reflex","owner":"reflex-search","description":"Reflex - The instant, code-aware local search engine.","archived":false,"fork":false,"pushed_at":"2025-11-25T03:02:01.000Z","size":1706,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-29T11:00:21.276Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reflex-search.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-31T20:30:48.000Z","updated_at":"2025-12-11T13:10:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/reflex-search/reflex","commit_stats":null,"previous_names":["therecluse26/reflex","reflex-search/reflex"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/reflex-search/reflex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reflex-search%2Freflex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reflex-search%2Freflex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reflex-search%2Freflex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reflex-search%2Freflex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reflex-search","download_url":"https://codeload.github.com/reflex-search/reflex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reflex-search%2Freflex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29994619,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-02T07:03:13.275Z","updated_at":"2026-03-02T07:03:23.065Z","avatar_url":"https://github.com/reflex-search.png","language":"Rust","funding_links":[],"categories":["Search","Development tools","Files and Directories","Web-Based Tools"],"sub_categories":["Workflow Automation","Search","Codebase Intelligence"],"readme":"# Reflex\n\n**Local-first code search engine with full-text search, symbol extraction, and dependency analysis for AI coding workflows**\n\nReflex is a code search engine designed for developers and AI coding assistants. It combines trigram indexing for full-text search with Tree-sitter parsing for symbol extraction and static analysis for dependency tracking. Unlike symbol-only tools, Reflex finds **every occurrence** of patterns, function calls, variable usage, comments, and more with deterministic, repeatable results.\n\n[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)]()\n[![Tests](https://img.shields.io/badge/tests-347%20passing-brightgreen)]()\n[![License](https://img.shields.io/badge/license-MIT-blue)]()\n\n## ✨ Features\n\n- **🔍 Complete Coverage**: Find every occurrence, not just symbol definitions\n- **⚡ Fast Queries**: Trigram indexing with memory-mapped I/O for efficient search\n- **🎯 Symbol-Aware**: Runtime tree-sitter parsing for precise symbol filtering\n- **🖥️ Interactive Mode**: Live TUI for exploring code with instant search and filters\n- **🔄 Incremental**: Only reindexes changed files (blake3 hashing)\n- **🌍 Multi-Language**: Rust, TypeScript/JavaScript, Vue, Svelte, PHP, Python, Go, Java, C, C++, C#, Ruby, Kotlin, Zig\n- **🤖 AI Query Assistant**: Natural language search with `rfx ask` (OpenAI, Anthropic, Groq)\n- **📡 MCP Support**: Model Context Protocol server for AI assistants\n- **📦 Local-First**: Fully offline, all data stays on your machine\n- **🎨 Regex Support**: Trigram-optimized regex search\n- **🌳 AST Queries**: Structure-aware search with Tree-sitter\n- **🔒 Deterministic**: Same query → same results (no probabilistic ranking)\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Via NPM\nnpm install -g reflex-search\n\n# Or via cargo\ncargo install reflex-search\n```\n\n**Important Setup Notes:**\n- Run `rfx` commands from the root of your project directory\n- Add `.reflex/` to your `.gitignore` file to exclude the search index from version control\n\n### Basic Usage\n\n```bash\n# Index your codebase\nrfx index\n\n# Full-text search (finds all occurrences)\nrfx query \"extract_symbols\"\n\n# Symbol-only search (definitions only)\nrfx query \"extract_symbols\" --symbols\n\n# Filter by language and symbol kind\nrfx query \"parse\" --lang rust --kind function --symbols\n\n# Include dependency information (imports)\nrfx query \"MyStruct\" --dependencies\n\n# Regex search\nrfx query \"fn.*test\" --regex\n\n# Paths-only mode (for piping to other tools)\nvim $(rfx query \"TODO\" --paths)\n\n# Export as JSON for AI agents\nrfx query \"unwrap\" --json --limit 10\n```\n\n## 🤖 AI Query Assistant\n\nDon't want to remember search syntax? Use `rfx ask` to translate natural language questions into `rfx query` commands.\n\n### Setup\n\nFirst-time setup requires configuring an AI provider (OpenAI, Anthropic, or Groq):\n\n```bash\n# Interactive configuration wizard (recommended)\nrfx ask --configure\n```\n\nThis will guide you through:\n- Selecting an AI provider\n- Entering your API key\n- Choosing a model (optional)\n\nConfiguration is saved to `~/.reflex/config.toml`:\n\n```toml\n[semantic]\nprovider = \"openai\"  # or anthropic, groq\n\n[credentials]\nopenai_api_key = \"sk-...\"\nopenai_model = \"gpt-4o-mini\"  # optional\n```\n\n### Usage\n\nThere are two ways to use `rfx ask`: \n\n1) Interactive mode\n\nInteractive chat mode with conversation history. This mode uses `--agentic` and `--answer` under the hood.\n\n```bash\nrfx ask\n```\n\n2) CLI-only mode\n\nOne-shot, non-conversational commands that return results directly via CLI.\n\n```bash\n# Ask a question (generates and executes rfx query commands, only returns query results)\nrfx ask \"Find all TODOs in Rust files\"\n\n# Use a specific provider\nrfx ask \"Show me error handling code\" --provider groq\n\n# Agentic mode (multi-step reasoning with automatic context gathering)\nrfx ask \"How does authentication work?\" --agentic\n\n# Get a conversational answer based on search results\nrfx ask \"What does the indexer module do?\" --answer\n```\n\n**How it works:**\n1. Your natural language question is sent to an LLM\n2. The LLM generates one or more `rfx query` commands\n3. You review and confirm (or use `--execute` to auto-run)\n4. Results are displayed as normal search output\n\n**Agentic mode** (`--agentic`) enables multi-step reasoning where the LLM can:\n- Gather context by running multiple searches\n- Refine queries based on initial results\n- Iteratively explore the codebase\n- Generate comprehensive answers with `--answer`\n\n## 📋 Command Reference\n\n### `rfx index`\n\nBuild or update the search index.\n\n```bash\nrfx index [OPTIONS]\n\nOptions:\n  --force              Force full reindex (ignore incremental)\n  --languages \u003cLANGS\u003e  Limit to specific languages (comma-separated)\n\nSubcommands:\n  status               Show background symbol indexing status\n  compact              Compact cache (remove deleted files, reclaim space)\n```\n\n### `rfx query`\n\nSearch the codebase with CLI or interactive TUI mode.\n\n**Interactive Mode (TUI):**\n```bash\n# Launch interactive mode (no pattern required)\nrfx query\n\n# Features:\n# - Live search with instant results\n# - Toggle filters: symbols-only, regex, language\n# - Navigate results with keyboard (j/k, arrows)\n# - Open files in $EDITOR (press 'o')\n# - Query history with Ctrl+P/Ctrl+N\n# - Press '?' for help, 'q' to quit\n```\n\n**CLI Mode:**\n\nRun `rfx query --help` for full options.\n\n**Key Options:**\n- `--symbols, -s` - Symbol-only search (definitions, not usage)\n- `--regex, -r` - Treat pattern as regex\n- `--lang \u003cLANG\u003e` - Filter by language\n- `--kind \u003cKIND\u003e` - Filter by symbol kind (function, class, struct, etc.)\n- `--dependencies` - Include dependency information (supports: Rust, TypeScript, JavaScript, Python, Go, Java, C, C++, C#, PHP, Ruby, Kotlin)\n- `--paths, -p` - Return only file paths (no content)\n- `--json` - Output as JSON\n- `--limit \u003cN\u003e` - Limit number of results\n- `--timeout \u003cSECS\u003e` - Query timeout (default: 30s)\n\n**Examples:**\n```bash\n# Find function definitions named \"parse\"\nrfx query \"parse\" --symbols --kind function\n\n# Find test functions using regex\nrfx query \"fn test_\\w+\" --regex\n\n# Search Rust files only\nrfx query \"unwrap\" --lang rust\n\n# Get paths of files with TODOs\nrfx query \"TODO\" --paths\n\n# Include import information\nrfx query \"Config\" --symbols --dependencies\n```\n\n### `rfx mcp`\n\nStart as an MCP (Model Context Protocol) server for AI coding assistants.\n\n```json\n{\n  \"mcpServers\": {\n    \"reflex\": {\n      \"command\": \"rfx\",\n      \"args\": [\"mcp\"],\n      \"env\": {},\n      \"disabled\": false\n    }\n  }\n}\n```\n\n**Error Handling:**\n\nIf any MCP tool returns an error about a missing or stale index (e.g., \"Index not found. Run 'rfx index' to build the cache first.\"), the AI agent should:\n\n1. Call `index_project` to rebuild the index\n2. Wait for indexing to complete\n3. Retry the previously failed operation\n\nThis pattern ensures that queries always run against an up-to-date index.\n\n**Available MCP Tools:**\n1. **`list_locations`** - Fast location discovery (file + line only, minimal tokens)\n2. **`count_occurrences`** - Quick statistics (total count + file count)\n3. **`search_code`** - Full-text or symbol search with detailed results\n4. **`search_regex`** - Regex pattern matching\n5. **`search_ast`** - AST pattern matching (structure-aware, slow)\n6. **`index_project`** - Trigger reindexing\n7. **`get_dependencies`** - Get all dependencies of a specific file\n8. **`get_dependents`** - Get all files that depend on a file (reverse lookup)\n9. **`get_transitive_deps`** - Get transitive dependencies up to a specified depth\n10. **`find_hotspots`** - Find most-imported files (with pagination)\n11. **`find_circular`** - Detect circular dependencies (with pagination)\n12. **`find_unused`** - Find files with no incoming dependencies (with pagination)\n13. **`find_islands`** - Find disconnected components (with pagination)\n14. **`analyze_summary`** - Get dependency analysis summary (counts only)\n\n### `rfx analyze`\n\nAnalyze codebase structure and dependencies. By default shows a summary; use specific flags for detailed results.\n\n**Subcommands:**\n- `--circular` - Detect circular dependencies (A → B → C → A)\n- `--hotspots` - Find most-imported files\n- `--unused` - Find files with no incoming dependencies\n- `--islands` - Find disconnected components\n\n**Pagination (default: 200 results per page):**\n- Use `--limit N` to specify results per page\n- Use `--offset N` to skip first N results\n- Use `--all` to return unlimited results\n\n**Examples:**\n```bash\n# Show summary of all analyses\nrfx analyze\n\n# Find circular dependencies\nrfx analyze --circular\n\n# Find hotspots (most-imported files)\nrfx analyze --hotspots --min-dependents 5\n\n# Find unused files\nrfx analyze --unused\n\n# Find disconnected components (islands)\nrfx analyze --islands --min-island-size 3\n\n# Get JSON summary of all analyses\nrfx analyze --json\n\n# Get pretty-printed JSON summary\nrfx analyze --json --pretty\n\n# Paginate results\nrfx analyze --hotspots --limit 50 --offset 0  # First 50\nrfx analyze --hotspots --limit 50 --offset 50 # Next 50\n\n# Export as JSON with pagination metadata\nrfx analyze --circular --json\n```\n\n**JSON Output Format (specific analyses with pagination):**\n```json\n{\n  \"pagination\": {\n    \"total\": 347,\n    \"count\": 200,\n    \"offset\": 0,\n    \"limit\": 200,\n    \"has_more\": true\n  },\n  \"results\": [...]\n}\n```\n\n**Summary JSON Output Format (bare `rfx analyze --json`):**\n```json\n{\n  \"circular_dependencies\": 17,\n  \"hotspots\": 10,\n  \"unused_files\": 82,\n  \"islands\": 81,\n  \"min_dependents\": 2\n}\n```\n\n### `rfx deps`\n\nAnalyze dependencies for a specific file. Shows what a file imports (dependencies) or what imports it (dependents).\n\n**Key Options:**\n- `--reverse` - Show files that depend on this file (reverse lookup)\n- `--depth N` - Traverse N levels deep for transitive dependencies (default: 1)\n- `--format` - Output format: tree, table, json (default: tree)\n- `--json` - Output as JSON\n- `--pretty` - Pretty-print JSON output\n\n**Examples:**\n```bash\n# Show direct dependencies\nrfx deps src/main.rs\n\n# Show files that import this file (reverse lookup)\nrfx deps src/config.rs --reverse\n\n# Show transitive dependencies (depth 3)\nrfx deps src/api.rs --depth 3\n\n# JSON output\nrfx deps src/main.rs --json\n\n# Pretty-printed JSON\nrfx deps src/main.rs --json --pretty\n\n# Table format\nrfx deps src/main.rs --format table\n```\n\n**Supported Languages:** Rust, TypeScript, JavaScript, Python, Go, Java, C, C++, C#, PHP, Ruby, Kotlin\n\n**Note:** Only static imports (string literals) are tracked. Dynamic imports are filtered by design.\n\n### `rfx context`\n\nGenerate codebase context for AI prompts. Useful with `rfx ask --additional-context`.\n\n**Key Options:**\n- `--structure` - Show directory structure\n- `--file-types` - Show file type distribution\n- `--project-type` - Detect project type (CLI/library/webapp/monorepo)\n- `--framework` - Detect frameworks and conventions\n- `--entry-points` - Show entry point files\n- `--test-layout` - Show test organization pattern\n- `--config-files` - List important configuration files\n- `--path \u003cPATH\u003e` - Focus on specific directory\n- `--depth \u003cN\u003e` - Tree depth for structure (default: 1)\n\nBy default (no flags), all context types are shown. Use individual flags to show specific types only.\n\n**Examples:**\n```bash\n# Full context (all types - default behavior)\nrfx context\n\n# Full context for monorepo subdirectory\nrfx context --path services/backend\n\n# Specific context types only\nrfx context --framework --entry-points\n\n# Use with semantic queries\nrfx ask \"find auth code\" --additional-context \"$(rfx context --framework)\"\n```\n\n### Other Commands\n\n- `rfx stats` - Display index statistics\n- `rfx clear` - Clear the search index\n- `rfx list-files` - List all indexed files\n- `rfx watch` - Watch for file changes and auto-reindex\n\nRun `rfx \u003ccommand\u003e --help` for detailed options.\n\n## 🌳 AST Pattern Matching\n\nReflex supports **structure-aware code search** using Tree-sitter AST queries.\n\n**⚠️ WARNING:** AST queries are **SLOW** and scan the entire codebase. **Use `--symbols` instead for 95% of cases** (much faster).\n\n**When to use AST queries:**\n- You need to match code structure, not just text\n- `--symbols` search is insufficient for your use case\n- You have a very specific structural pattern\n\n**Basic usage:**\n```bash\nrfx query \u003cPATTERN\u003e --ast \u003cAST_PATTERN\u003e --lang \u003cLANGUAGE\u003e\n\n# Example: Find all Rust functions\nrfx query \"fn\" --ast \"(function_item) @fn\" --lang rust\n\n# Example: Find all TypeScript classes\nrfx query \"class\" --ast \"(class_declaration) @class\" --lang typescript\n```\n\n**Supported languages:** Rust, TypeScript, JavaScript, Python, Go, Java, C, C++, C#, PHP, Ruby, Kotlin, Zig\n\nFor detailed AST query syntax and examples, see the [Tree-sitter documentation](https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries).\n\n## 🌐 Supported Languages/Dialects\n\n| Language | Extensions | Symbol Extraction |\n|----------|------------|-------------------|\n| **Rust** | `.rs` | Functions, structs, enums, traits, impls, modules, methods |\n| **TypeScript** | `.ts`, `.tsx`, `.mts`, `.cts` | Functions, classes, interfaces, types, enums, React components |\n| **JavaScript** | `.js`, `.jsx`, `.mjs`, `.cjs` | Functions, classes, constants, methods, React components |\n| **Vue** | `.vue` | Functions, constants, methods from `\u003cscript\u003e` blocks |\n| **Svelte** | `.svelte` | Functions, variables, reactive declarations |\n| **PHP** | `.php` | Functions, classes, interfaces, traits, methods, namespaces, enums |\n| **Python** | `.py` | Functions, classes, methods, decorators, lambdas |\n| **Go** | `.go` | Functions, types, interfaces, methods, constants |\n| **Java** | `.java` | Classes, interfaces, enums, methods, fields, constructors |\n| **C** | `.c`, `.h` | Functions, structs, enums, unions, typedefs |\n| **C++** | `.cpp`, `.hpp`, `.cxx` | Functions, classes, namespaces, templates, methods |\n| **C#** | `.cs` | Classes, interfaces, structs, enums, methods, properties |\n| **Ruby** | `.rb`, `.rake`, `.gemspec` | Classes, modules, methods, constants, variables |\n| **Kotlin** | `.kt`, `.kts` | Classes, functions, interfaces, objects, properties |\n| **Zig** | `.zig` | Functions, structs, enums, constants, variables |\n\n**Note:** Full-text search works on **all file types** regardless of parser support. Symbol filtering requires a language parser.\n\n## 🏗️ Architecture\n\nReflex uses a **trigram-based inverted index** combined with **runtime symbol detection**:\n\n### Indexing Phase\n1. Extract trigrams (3-character substrings) from all files\n2. Build inverted index: `trigram → [file_id, line_no]`\n3. Store full file contents in memory-mapped `content.bin`\n4. Start background symbol indexing (caches symbols for faster queries)\n\n### Query Phase\n1. **Full-text queries**: Intersect trigram posting lists → verify matches\n2. **Symbol queries**: Trigrams narrow to ~10-100 candidates → parse with tree-sitter → filter symbols\n3. Memory-mapped I/O for instant cache access\n\n### Cache Structure (`.reflex/`)\n```\n.reflex/\n  meta.db          # SQLite: file metadata, stats, config, hashes\n  trigrams.bin     # Inverted index (memory-mapped)\n  content.bin      # Full file contents (memory-mapped)\n  config.toml      # Index settings\n  indexing.status  # Background symbol indexer status\n```\n\n## ⚡ Performance\n\nReflex is designed for speed at every level:\n\n**Query Performance:**\n- **Full-text \u0026 Regex**: Efficient queries via trigram indexing\n- **Symbol queries**: Slower due to runtime tree-sitter parsing, but still efficient\n- **Cached queries**: Repeated searches benefit from memory-mapped cache\n- Scales well from small projects to large codebases (10k+ files)\n\n**Indexing Performance:**\n- **Initial indexing**: Parallel processing using 80% of CPU cores\n- **Incremental updates**: Only reindexes changed files via blake3 hashing\n- **Memory-mapped I/O**: Zero-copy access for cache reads\n\n## 🔧 Configuration\n\nReflex respects `.gitignore` files automatically. Additional configuration via `.reflex/config.toml`:\n\n```toml\n[index]\nlanguages = []  # Empty = all supported languages\nmax_file_size = 10485760  # 10 MB\nfollow_symlinks = false\n\n[search]\ndefault_limit = 100\n\n[performance]\nparallel_threads = 0  # 0 = auto (80% of available cores)\n```\n\n## 🤖 AI Integration\n\nReflex provides clean JSON output for AI coding assistants and automation:\n\n```bash\nrfx query \"parse_tree\" --json --symbols\n```\n\nOutput includes file paths, line numbers, symbol types, and code previews with pagination metadata.\n\n## 🔍 Use Cases\n\n- **Code Navigation**: Find all usages of functions, classes, and variables\n- **Refactoring**: Identify all call sites before making changes\n- **AI Assistants**: Retrieve relevant code snippets and context for LLMs\n- **Debugging**: Locate where variables and functions are used\n- **Documentation**: Find examples of API usage across the codebase\n- **Security**: Search for potential vulnerabilities or anti-patterns\n\n## 🧪 Testing\n\nReflex has comprehensive test coverage including core modules, real-world code samples across all supported languages, and end-to-end workflows.\n\n```bash\ncargo test                    # Run all tests\ncargo test -- --nocapture     # Run with output\ncargo test indexer::tests     # Run specific module\n```\n\n## 🤝 Contributing\n\nContributions welcome! Reflex is built to be:\n- **Fast**: Efficient search using trigram indexing and memory-mapped I/O\n- **Accurate**: Complete coverage with deterministic results\n- **Extensible**: Easy to add new language parsers\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🙏 Acknowledgments\n\nBuilt with:\n- [tree-sitter](https://tree-sitter.github.io/tree-sitter/) - Incremental parsing\n- [rkyv](https://rkyv.org/) - Zero-copy deserialization\n- [memmap2](https://github.com/RazrFalcon/memmap2-rs) - Memory-mapped I/O\n- [rusqlite](https://github.com/rusqlite/rusqlite) - SQLite bindings\n- [blake3](https://github.com/BLAKE3-team/BLAKE3) - Fast hashing\n- [ignore](https://github.com/BurntSushi/ripgrep/tree/master/crates/ignore) - gitignore support\n\nInspired by:\n- [Zoekt](https://github.com/sourcegraph/zoekt) - Trigram-based code search\n- [Sourcegraph](https://sourcegraph.com/) - Code search for teams\n- [ripgrep](https://github.com/BurntSushi/ripgrep) - Fast text search\n\n---\n\n**Made with ❤️ for developers and AI coding assistants**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freflex-search%2Freflex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freflex-search%2Freflex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freflex-search%2Freflex/lists"}