📂 Gemini Directory Manager Agent

An intelligent, autonomous file system management agent powered by the Google GenAI SDK (gemini-3.6-flash). The agent uses native function calling (tools) to search, create, modify, copy, move, archive, and delete files and directories via a natural language CLI.

---

🎯 Design Philosophy: Zero-Overhead Portability

This project is intentionally designed as a single, self-contained Python script (dir_manager_agent.py). There are no complex dependencies, multi-file modular frameworks, or heavy directory setups. The goal is pure portability—you can drop this single file into any directory, repository, or remote server, run it, and instantly have a fully capable AI file manager at your disposal.

---

⚡ Features

• File Operations: Read, write, append, copy, rename, move, and get detailed metadata.
• Directory Operations: Create nested directories, list contents recursively with sorting and file-type filtering.
• Batch Processing: Dedicated tools for bulk deletion, copying, and moving files in a single turn.
• Archiving: Compress directories into .zip, .tar, or .gztar archives and extract them.
• Pattern & Content Search: Wildcard filename search (*.py) and text query matching within file contents.
• Robust CLI Execution: Built-in tool handling loop that gracefully displays function execution turns and final summaries.

---

🚀 Quick Start

1. Prerequisites

• Python 3.10 or higher
• A Gemini API Key from Google AI Studio

2. Installation

1. Install required packages (system-wide installation is recommended if you want to run dir_manager_agent.py anywhere as a global assistant):

   pip install google-genai python-dotenv

3. Environment Configuration

You can configure your API key in one of two ways:

• Local / Portable Usage (Recommended for single-file setup): If you only intend to run this tool locally and NEVER push your copy to a public repository, open dir_manager_agent.py and hardcode your key directly near the top of the file:

  API_KEY = "your_actual_gemini_api_key_here"

• Remote / Git Hosted Usage: If you plan to publish or share your agent, store your key in a local .env file (or export API_KEY in your environment) so your credentials remain private:

  API_KEY="your_gemini_api_key_here"

4. Running the Agent

Start the interactive CLI:

python dir_manager_agent.py

---

💡 Example Prompts

• "Find all .log files in ./logs modified recently and move them to ./archive/logs."
• "Create a folder structure for a Python web app with src, tests, and docs directories."
• "Search for any files containing the text 'TODO' and list their paths."
• "Zip the entire project_docs directory into docs_backup.zip."
• "Create 5 dummy text files, inspect their info, and then clean them up using bulk delete."

---

🛠️ Available Agent Tools

Tool Name	Parameters	Description
read_file	path, max_bytes, encoding	Reads file text up to a byte limit.
write_file	path, content, mode, encoding	Writes or appends text to a file.
make_directory	path	Creates a directory and parent directories.
delete_item	path, recursive	Deletes a file or directory.
search_files	path, pattern, text_query	Searches by wildcard pattern and text content.
copy_item	source, destination	Copies a file or folder.
rename_or_move_item	source, destination	Moves or renames files/folders.
get_file_info	path	Returns metadata (size, dates, absolute path).
get_directory_files	path, recursive, extension, sort_by	Lists items with filtering and sorting.
create_archive	source, destination_archive, format	Compresses target into zip, tar, or gztar.
extract_archive	archive_path, destination	Extracts compressed archives.
bulk_delete	paths, recursive	Deletes multiple paths in one operation.
bulk_move_or_copy	sources, destination_dir, operation	Batch moves or copies items into a target dir.

---

---

⚠️ Security Notice

This agent has read, write, and deletion capabilities on your host machine. Always review prompts before asking the agent to delete or overwrite directory structures.

---

📄 License

This project is licensed under the MIT License.