AgenticFileSearch is an intelligent folder exploration tool that uses AI to search and analyze your local directory structures. Unlike traditional keyword search methods, it understands the meaning of your queries - it explores your codebase by reading files, analyzing structure, and reasoning about what's relevant to your question, not just matching text patterns.
All commands are safeguarded with a read-only whitelist, ensuring the agent can only observe your files, never modify them.
Note: currenty using Anthropic Claude on Windows, with other models and OS support coming soon...
# From PyPI
pip install agentic-file-search
# Or install from source (development)
pip install -e .Requires Python 3.9+. You'll need to set your ANTHROPIC_API_KEY environment variable (can be set directly or via a .env file).
ripgrep-all (rga) is strongly recommended for full-text search support across various file formats including PDFs, Word documents, archives, and more. The easiest way to install it is via conda-forge:
conda install -c conda-forge ripgrep-all popplerThe poppler package is needed for PDF support. For other installation methods, see the official rga repository.
Set your ANTHROPIC_API_KEY environment variable or create a .env file:
set ANTHROPIC_API_KEY=sk-ant-...# Basic usage (after pip install)
agentic-file-search "find all Python files" .
# Or use as module
python -m agentic_file_search "find all Python files" .
# Advanced options
agentic-file-search "find classes that adds more than two functions" ./src --max-iterations 20 --model claude-sonnet-4-5
agentic-file-search "find receipts" ~/Downloads --output results.json --quiet
agentic-file-search "find text files" . --no-rga # Disable rga if not installedRun agentic-file-search --help for all options.
from agentic_file_search import main
result = main(
message="Find all README files",
folder_path="C:/Projects",
max_iterations=5,
model="claude-haiku-4-5",
)
print(result["summary"])Here's what running AgenticFileSearch looks like in action:
python -m agentic_file_search "find the python scripts that is relevant for calling external llm" .Click to see the agent's reasoning process and output
Starting agentic search...
Query: find the python scripts that is relevant for calling external llm
Folder: D:\Github\AgenticFileSearch
Model: claude-haiku-4-5
Max iterations: 100
[ITERATION 1/100]
## Assistant
[THINKING] The user wants me to find Python scripts relevant for calling
external LLMs in the directory D:\Github\AgenticSearch. I need to:
1. Start by exploring the directory structure
2. Look for Python scripts (.py files)
3. Identify which ones are relevant to calling external LLMs
4. Provide the findings
Let me start by looking at the directory structure to understand what's in
this project.
Let me begin exploring the directory structure of D:\Github\AgenticFileSearch to
find Python scripts related to external LLM calls.
<command>tree /A D:\Github\AgenticFileSearch</command>
[ITERATION 2/100]
## Assistant
[THINKING] The tree output shows that the main code is likely in the
`src/agentic_file_search` directory. Let me explore the structure more by looking
at what files are in these directories. I need to get a better view of the
actual Python files.
<command>dir D:\Github\AgenticFileSearch\src\agentic_file_search</command>
[ITERATION 3/100]
## Assistant
[THINKING] Great! I found the Python files. I can see:
1. claude.py - This looks like it could be related to calling external LLM
2. conversation.py - This could be related to LLM interactions
3. search_agent.py - This could be an agent that calls external LLM
Now I should examine these files to identify which ones are relevant for
calling external LLMs. Let me start with claude.py since the filename directly
suggests it's for interacting with an external LLM service.
<command>type D:\Github\AgenticFileSearch\src\agentic_file_search\claude.py</command>
[ITERATION 4/100]
## Assistant
[THINKING] Good! I found one relevant script. Now let me check the other
Python files to see if they contain code for calling external LLMs.
<command>type D:\Github\AgenticFileSearch\src\agentic_file_search\conversation.py</command>
[ITERATION 5/100]
## Assistant
[THINKING] The user asked me to find Python scripts relevant for calling
external LLM. Let me examine what I've found so far:
1. **claude.py** - This is clearly the main script for calling Claude
2. **conversation.py** - This manages conversations with the LLM
Let me check the other files to provide a complete answer.
<command>type D:\Github\AgenticFileSearch\src\agentic_file_search\search_agent.py</command>
[ITERATION 6/100]
## Assistant
[THINKING] I should check the __main__.py and __init__.py files to complete
the picture. The most relevant scripts for calling external LLM are:
- **claude.py** - Direct LLM integration (most important)
- **conversation.py** - High-level conversation management with LLM
Let me check the remaining files to provide a complete answer.
<command>type D:\Github\AgenticFileSearch\src\agentic_file_search\__main__.py</command>
[ITERATION 7/100]
## Assistant
[THINKING] I've now examined the key files in the AgenticFileSearch project.
Let me provide a conclusion now.
<conclude>
## Summary of Python Scripts for External LLM Calls
I've explored the D:\Github\AgenticFileSearch repository and identified the Python
scripts relevant for calling external LLM services:
### Primary LLM Integration Scripts:
1. **claude.py** (2,042 bytes)
- **Purpose**: Direct interface to Claude API (Anthropic)
- **Key Functions**:
- `prompt()` - Core function that calls Claude API with support for:
- Streaming responses
- Tool/function calling
- Extended thinking mode with configurable token budgets
- System prompts with cache control
- `list_models()` - Lists available Claude models
- **External Service**: Uses `anthropic` Python library
- **Configuration**: Reads API key from environment variables via `dotenv`
2. **conversation.py** (19,295 bytes)
- **Purpose**: High-level conversation management layer
- **Key Classes/Methods**:
- `Conversation` class - Manages multi-turn conversations with LLM
- `send()` - Sends messages and handles full conversation loop with tools
- `answer_with_tags()` - Sends queries and extracts structured responses
- **Uses**: Leverages `claude.py` for actual API calls
3. **search_agent.py** (26,626 bytes)
- **Purpose**: Autonomous agent that uses Claude for folder exploration
- **Integration**: Uses `Conversation` class from `conversation.py`
### How External LLM is Called:
- **Primary Entry Point**: `claude.py` -> `prompt()` function
- **Flow**: CLI -> `search_agent.py` -> `conversation.py` -> `claude.py` ->
Anthropic API
- **Model Used**: Claude Haiku 4.5 (default), with options for Sonnet and Opus
- **API Provider**: Anthropic's Claude API
</conclude>
================================================================================
EXPLORATION COMPLETE
================================================================================
Status: SUCCESS
Iterations: 7
Time taken: 21.42s
Commands executed:
- tree: 1
- dir: 1
- type: 4
Summary:
--------------------------------------------------------------------------------
I've explored the D:\Github\AgenticFileSearch repository and identified the Python
scripts relevant for calling external LLM services:
Primary LLM Integration Scripts:
1. **claude.py** - Direct interface to Claude API with `prompt()` function
supporting streaming, tool calling, and extended thinking mode
2. **conversation.py** - High-level conversation management with `Conversation`
class handling multi-turn dialogues and structured responses
3. **search_agent.py** - Autonomous agent using the Conversation class
The call flow: CLI -> search_agent.py -> conversation.py -> claude.py ->
Anthropic API
--------------------------------------------------------------------------------
================================================================================