Filesift

[FileSift]

FileSift

A local, open-source utility that helps AI coding agents intelligently search and understand codebases.

[PyPI] [Python]

FileSift lets your AI coding agent search across a codebase based on what code does, rather than what it looks like. Instead of sifting through entire files after a grep, your agent can jump straight to the most relevant code using natural language queries like "authentication middleware" or "database connection pooling". Everything runs locally on your machine — your code never leaves your environment.

Key benefits:

• Smarter search — hybrid keyword + semantic search finds code by intent, not just string matching
• Less context wasted — agents get pointed to the right files immediately, saving token budget on exploration

Installation

pip install filesift

Usage

There are three ways to use FileSift, depending on your workflow:

1. CLI

The most straightforward approach. Good for testing queries, managing indexes, and configuring settings.

# Index a projectfilesift index /path/to/your/project
# Search for files by what they dofilesift find "authentication and session handling"
# Search in a specific directoryfilesift find "retry logic for API calls" --path /path/to/project

2. MCP Server

Installing FileSift also provides a filesift-mcp command — a lightweight MCP server that exposes indexing and search as tools over STDIO. This works with most popular coding agents including Claude Code, Cursor, Copilot, and more.

Add it to your agent's MCP configuration:

{  "mcpServers": {    "filesift": {      "command": "filesift-mcp"    }  }}

The MCP server exposes four tools:

• filesift_search — search an indexed codebase by natural language query
• filesift_find_related — find files related to a given file via imports and semantic similarity
• filesift_index — index a directory to enable searching
• filesift_status — check indexing status of a directory

3. Skills

FileSift ships with a search-codebase skill that can be installed directly into your coding agent's skill directory. This lets the agent interact with the FileSift CLI through bash, without requiring MCP support.

# Install for Claude Code (default)filesift skill install
# Install for other agentsfilesift skill install --agent cursorfilesift skill install --agent copilotfilesift skill install --agent codex

Supported agents: claude, codex, cursor, copilot, gemini, roo, windsurf.

How It Works

FileSift uses a daemonized embedding model to keep searches fast. At its core, it generates embeddings from code descriptions and performs searches against small vector stores called indexes.

1. Indexing — filesift index first builds a fast keyword/structural index (completes in seconds), then triggers background semantic indexing that generates embeddings for each file.

2. Daemon — A background daemon loads indexes into memory and automatically shuts down after a configurable period of inactivity. After the first cold-start search, subsequent searches are near-instant.

3. Search — Queries are matched using both keyword (BM25) and semantic (FAISS) search, then combined via Reciprocal Rank Fusion for the best of both approaches.

Indexes are stored in a .filesift directory within each indexed project.

Configuration

FileSift uses a TOML configuration file, manageable via the CLI:

# View all settingsfilesift config list --all
# Set a valuefilesift config set search.MAX_RESULTS 20filesift config set daemon.INACTIVITY_TIMEOUT 600
# Manage ignore patternsfilesift config add-ignore "node_modules" ".venv"filesift config list-ignore

Configuration sections: search, indexing, daemon, models, paths.

Contributing

Contributions are welcome! To get started:

git clone https://github.com/roshunsunder/filesift.gitcd filesiftpip install -e .

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes and open a pull request

License

Apache 2.0 — see LICENSE for details.