Find files using plain English. Stop fighting with complex find syntax.
The fastest way to search your codebase without breaking your flow.
We've all been there. You just want to find a specific file, but instead, you end up Googling "how to find files modified in the last 7 days excluding test directories."
The old way:
find . -type f -name "*.py" -mtime -7 -not -path "*/vendor/*" -exec grep -l "TODO" {} +The askfind way:
askfind "python files modified this week containing TODO excluding vendor"Under the hood, askfind uses an LLM to instantly translate your natural language query into an optimized, highly efficient file system traversal plan. It's smart, fast, and incredibly intuitive.
- 🗣️ Zero Learning Curve: If you can type it in English, you can find it. No more regex cheat sheets.
- ⚡ Lightning Fast Execution:
askfindintelligently applies cheap filters (like file extensions and paths) before expensive I/O operations (like reading file contents), minimizing search time. - 🎯 Semantic Re-ranking: Results aren't just listed; they're optionally re-ranked by the LLM so the most relevant files appear exactly where you look first.
- 🔒 Privacy & Security First: Your API keys are locked securely in your OS keychain. Only file paths and your query are sent to the LLM—your file contents stay local.
- 🔌 100% Offline Capable: Working on a plane? No problem. Use
--offlineto instantly skip the LLM and rely on our fast local heuristic parser. - 💻 Interactive REPL: Use
askfind -ifor an interactive terminal session where you can preview, open, and copy files directly.
Make sure you have Python 3.12+ installed.
Once askfind is published to PyPI, install it in an isolated tool environment:
pipx install askfind
askfind --helpIf pipx is installed but askfind is not found on your PATH, run:
pipx ensurepathIf you use uv, you can install the CLI without manually activating a virtual environment:
uv tool install askfind
askfind --helpIf uv warns that its tool bin directory is not on your PATH, run:
uv tool update-shellIf you are working directly from this repository before a PyPI release is available:
git clone https://github.com/wgsim/natural_language_base_file_finder_in_terminal.git
cd natural_language_base_file_finder_in_terminal
pip install -e ".[dev]"Store your preferred LLM provider's API key (e.g., OpenRouter, OpenAI) securely in your system keychain:
askfind config set-key
# Paste your API key when prompted# Basic searches
askfind "large javascript files"
askfind "config files in src excluding tests"
# Combine multiple constraints naturally
askfind "small python files in src modified today containing async"askfind is packed with power-user features:
# Get detailed file info (size, date)
askfind "python files" --verbose
# Output JSON for use in other scripts
askfind "python files" --json
# Limit results and parallelize traversal
askfind "python files" --max 10 --workers 8
# Create a permanent index for massive repositories to speed up future queries
askfind index build --root .Check out our Documentation for more details on caching, index management, and configuration.
askfind is highly customizable via ~/.config/askfind/config.toml:
askfind config set model "gpt-4o-mini"
askfind config set max_results 100
askfind config set parallel_workers 4Want to use a local LLM? Point it to your Ollama server:
askfind config set base_url "http://localhost:11434/v1"
askfind config set model "llama3"- End-user installation should target PyPI via
pipx install askfindas the primary path. uv tool install askfindis a supported alternative for users already onuv.- The source install flow (
pip install -e ".[dev]") is intended for contributors and local development, not for general end users.
We welcome contributions! Please see our Contributing Guide to get started.
- Fork the repository
- Create a feature branch
- Run tests with
pytest - Submit a Pull Request
MIT License - see the LICENSE file for details.
cli, terminal, search, file-search, llm, ai-tools, productivity, python, developer-tools