{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/logo.png\" alt=\"FileSift\" width=\"200\">\n</p>\n\n<h1 align=\"center\">FileSift</h1>\n\n<p align=\"center\">\n  <em>A local, open-source utility that helps AI coding agents intelligently search and understand codebases.</em>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://pypi.org/project/filesift/\"><img src=\"https://img.shields.io/pypi/v/filesift\" alt=\"PyPI\"></a>\n  <a href=\"https://pypi.org/project/filesift/\"><img src=\"https://img.shields.io/pypi/pyversions/filesift\" alt=\"Python\"></a>\n</p>\n\n---\n\nFileSift 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.\n\n**Key benefits:**\n- **Smarter search** — hybrid keyword + semantic search finds code by intent, not just string matching\n- **Less context wasted** — agents get pointed to the right files immediately, saving token budget on exploration\n\n## Installation\n\n```bash\npip install filesift\n```\n\n## Usage\n\nThere are three ways to use FileSift, depending on your workflow:\n\n### 1. CLI\n\nThe most straightforward approach. Good for testing queries, managing indexes, and configuring settings.\n\n```bash\n# Index a project\nfilesift index /path/to/your/project\n\n# Search for files by what they do\nfilesift find \"authentication and session handling\"\n\n# Search in a specific directory\nfilesift find \"retry logic for API calls\" --path /path/to/project\n```\n\n### 2. MCP Server\n<!-- mcp-name: io.github.roshunsunder/filesift -->\nInstalling FileSift also provides a `filesift-mcp` command — a lightweight [MCP](https://modelcontextprotocol.io/) server that exposes indexing and search as tools over STDIO. This works with most popular coding agents including Claude Code, Cursor, Copilot, and more.\n\nAdd it to your agent's MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"filesift\": {\n      \"command\": \"filesift-mcp\"\n    }\n  }\n}\n```\n\nThe MCP server exposes four tools:\n- `filesift_search` — search an indexed codebase by natural language query\n- `filesift_find_related` — find files related to a given file via imports and semantic similarity\n- `filesift_index` — index a directory to enable searching\n- `filesift_status` — check indexing status of a directory\n\n### 3. Skills\n\nFileSift 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.\n\n```bash\n# Install for Claude Code (default)\nfilesift skill install\n\n# Install for other agents\nfilesift skill install --agent cursor\nfilesift skill install --agent copilot\nfilesift skill install --agent codex\n```\n\nSupported agents: `claude`, `codex`, `cursor`, `copilot`, `gemini`, `roo`, `windsurf`.\n\n## How It Works\n\nFileSift 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**.\n\n1. **Indexing** — `filesift index` first builds a fast keyword/structural index (completes in seconds), then triggers background semantic indexing that generates embeddings for each file.\n\n2. **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.\n\n3. **Search** — Queries are matched using both keyword (BM25) and semantic (FAISS) search, then combined via [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf) for the best of both approaches.\n\nIndexes are stored in a `.filesift` directory within each indexed project.\n\n## Configuration\n\nFileSift uses a TOML configuration file, manageable via the CLI:\n\n```bash\n# View all settings\nfilesift config list --all\n\n# Set a value\nfilesift config set search.MAX_RESULTS 20\nfilesift config set daemon.INACTIVITY_TIMEOUT 600\n\n# Manage ignore patterns\nfilesift config add-ignore \"node_modules\" \".venv\"\nfilesift config list-ignore\n```\n\nConfiguration sections: `search`, `indexing`, `daemon`, `models`, `paths`.\n\n## Contributing\n\nContributions are welcome! To get started:\n\n```bash\ngit clone https://github.com/roshunsunder/filesift.git\ncd filesift\npip install -e .\n```\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Commit your changes and open a pull request\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE) for details.\n",
  "bytes": 4722,
  "sha": "79694d8483bcb81d5b53a10b85edbb25638f5c6dfca0d34cee0fec24267e4ec9",
  "repo_slug": "roshunsunder/filesift",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_roshunsunder_filesift_10eca9d1/readme"
}