agentic-file-search 0.1.0
Autonomous folder exploration agent powered by Anthropic Claude
License: MIT
Requires Python: >=3.9
Keywords: agent, anthropic, search, automation

# AgenticFileSearch

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...

## Installation

```bash
# 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).

### Installing ripgrep-all (Strongly Recommended)

`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:

```bash
conda install -c conda-forge ripgrep-all poppler
```

The `poppler` package is needed for PDF support. For other installation methods, see the [official rga repository](https://github.com/phiresky/ripgrep-all).

## Configuration

Set your `ANTHROPIC_API_KEY` environment variable or create a `.env` file:

```bash
set ANTHROPIC_API_KEY=sk-ant-...
```

## Usage

### Command Line Interface

```bash
# 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 installed
```

Run `agentic-file-search --help` for all options.

### Python API

```python
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"])
```

## Example

Here's what running AgenticFileSearch looks like in action:

```bash
python -m agentic_file_search "find the python scripts that is relevant for calling external llm" .
```

<details>
<summary>Click to see the agent's reasoning process and output</summary>

```
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
--------------------------------------------------------------------------------
================================================================================
```

</details>