Overview
File search enables Sphinx to search, list, and read files in your workspace. The agent uses file search to explore codebases, find relevant data files, and understand project structure—all from within your notebook.
Capabilities
When file search is enabled, Sphinx can:
- Search by content — Find files containing specific patterns using regex
- List files — Explore directory structure and discover available files
- Read files — Access file contents for analysis or reference
- Filter by glob — Target specific file types (e.g.,
*.csv, *.py)
Settings
File search is controlled by two settings in your IDE:
| Setting | Default | Description |
|---|
sphinx.file-search | true | Enable or disable file search capabilities |
sphinx.ripgrep-installation | true | Allow Sphinx to install ripgrep for faster search |
Ripgrep (recommended)
When the sphinx.ripgrep-installation setting is enabled, Sphinx uses ripgrep—a fast, modern search tool—for file operations. Ripgrep provides 10-100x faster search performance compared to traditional methods.
Sphinx handles ripgrep setup automatically:
- First checks if ripgrep is already available on your system (via the
rg command)
- If not found, installs a pre-compiled binary to
~/.sphinx/bin/rg
- Supports macOS (Intel and Apple Silicon), Linux (x64 and ARM64), and Windows (x64 and ARM64)
If you already have ripgrep installed on your system, Sphinx will use it automatically without installing a separate copy.
Python fallback
When ripgrep installation is disabled or unavailable, Sphinx falls back to a pure Python implementation using standard library functions. This fallback:
- Works on any system with Python installed
- Requires no additional binaries
- Is slower for large workspaces but fully functional
Disable ripgrep installation if you prefer not to have additional binaries installed, or if your environment restricts binary execution.
Search limits
To ensure responsive performance, file search enforces the following limits:
| Limit | Value | Description |
|---|
| Max results | 50 | Maximum number of matches returned per search |
| Max chars per match | 500 | Long lines are truncated |
| Max lines per read | 100 | Files are read in chunks |
| Max file size | 50 KB | Large files are skipped |
Ignored directories
File search automatically skips common directories that typically contain generated or vendored code:
.git, .vscode, .ideanode_modules, venv, .venv__pycache__, .pytest_cache, .mypy_cachedist, build, site-packages.ipynb_checkpoints
Example usage
Ask Sphinx to search your workspace naturally:
- “Find all CSV files in the data folder”
- “Search for files that import pandas”
- “List the Python files in this project”
- “Read the contents of config.yaml”
Sphinx will use the appropriate file search tools and return relevant results directly in your notebook conversation.