srijanshukla18/xray

❌ Without XRAY
AI assistants struggle with codebase understanding. You get:
- ❌ "I can't see your code structure"
- ❌ "I don't know what depends on this function"
- ❌ Generic refactoring advice without impact analysis
- ❌ No understanding of symbol relationships
✅ With XRAY
XRAY gives AI assistants code navigation capabilities. Add use XRAY tools to your prompt:
XRAY provides three focused tools:
- 🗺️ **Map** (explore_repo) - See project structure with symbol skeletons
- 🔍 **Find** (find_symbol) - Locate functions and classes with fuzzy search
- 💥 **Impact** (what_breaks) - Find where a symbol is referenced
🚀 Quick Install
Modern Install with uv (Recommended)
Automated Install with uv
For the quickest setup, this script automates the uv installation process.
Generate Config
Language Support
XRAY uses ast-grep, a tree-sitter powered structural search tool, providing accurate parsing for:
- **Python** - Functions, classes, methods, async functions
- **JavaScript** - Functions, classes, arrow functions, imports
- **TypeScript** - All JavaScript features plus interfaces, type aliases
- **Go** - Functions, structs, interfaces, methods
ast-grep ensures structural accuracy - it understands code syntax, not just text patterns.
The XRAY Workflow - Progressive Discovery
1. Map - Start Simple, Then Zoom In
2. Find - Locate Specific Symbols
3. Impact - See What Would Break
Architecture
**Stateless design** - No database, no persistent index. Each operation runs fresh ast-grep queries for real-time accuracy.
Why ast-grep?
Traditional grep searches text. ast-grep searches code structure:
- **grep**: Finds "authenticate" in function names, variables, comments, strings
- **ast-grep**: Finds only def authenticate() or function authenticate() definitions
This structural approach provides clean, accurate results essential for reliable code intelligence.
Performance Characteristics
- **Startup**: Fast - launches ast-grep subprocess
- **File tree**: Python directory traversal
- **Symbol search**: Runs multiple ast-grep patterns, speed depends on codebase size
- **Impact analysis**: Name-based search across all files
- **Memory**: Minimal - no persistent state
What Makes This Practical
1. **Progressive Discovery** - Start with directories, add symbols only where needed
2. **Smart Caching** - Symbol extraction cached per git commit for instant re-runs
3. **Flexible Focus** - Use focus_dirs to zoom into specific parts of large codebases
4. **Enhanced Symbols** - See function signatures and docstrings, not just names
5. **Based on tree-sitter** - ast-grep provides accurate structural analysis
XRAY helps AI assistants avoid information overload while providing deep code intelligence where needed.
Stateless Design
XRAY performs on-demand structural analysis using ast-grep. There's no database to manage, no index to build, and no state to maintain. Each query runs fresh against your current code.
Getting Started
1. **Install**: See getting_started.md for modern installation
2. **Map the terrain**: explore_repo("/path/to/project")
3. **Find your target**: find_symbol("/path/to/project", "UserService")
4. **Assess impact**: what_breaks(symbol)
The XRAY Philosophy
XRAY bridges the gap between simple text search and complex LSP servers:
- **More than grep** - Matches code syntax patterns, not just text
- **Less than LSP** - No language servers or complex setup
- **Practical for AI** - Provides structured data about code relationships
A simple tool that helps AI assistants navigate codebases more effectively than text search alone.
Architectural Journey & Design Rationale
The current implementation of XRAY is the result of a rigorous evaluation of multiple code analysis methodologies. My journey involved prototyping and assessing several distinct approaches, each with its own set of trade-offs. Below is a summary of the considered architectures and the rationale for my final decision.