AI Code Agent

An autonomous Python agent powered by Google Gemini that can explore, analyze, read, write, and execute code in a local codebase — using function calling. A mini mini Claude you can assume, that can work with your prompts and fiddle with your code.{For thr best or worst that thought i leave for you 👽}

This project showcases how to build a capable code-understanding agent with iterative reasoning, tool usage, and self-correction loops.

Features

• Function-calling agent — the LLM can decide which tools to use
• Available tools (expandable):
  • List files & directories (with size & type)
  • Read file contents
  • Execute Python scripts (with optional arguments)
  • Write / overwrite files
• Agent loop with multiple reasoning ↔ tool call cycles
• Verbose mode for seeing every intermediate step & function call
• Clean separation of concerns (schemas, function dispatch, config)
• Easy to extend with new tools

Project Structure

AI-Code-Agent/
├── main.py               # CLI entry point & agent loop
├── config.py             # Model, system prompt, constants
├── schemas.py            # Function declarations for Gemini
├── call_function.py      # Dispatcher: name → actual Python function
├── pkg/                  # Example codebase the agent can explore , /calculator in this case
│   └── render.py
├── .env                  # GEMINI_API_KEY=...
├── requirements.txt
└── README.md

Quick Start

1. Clone and enter directory

git clone https://github.com/YOUR_USERNAME/AI-Code-Agent.git
cd AI-Code-Agent

2. Create virtual environment & install dependencies

Install uv if you don't have it yet

curl -LsSf https://astral.sh/uv/install.sh | sh

uv sync # creates .venv + installs everything from pyproject.toml + uv.lock

or

uv venv # just create virtualenv uv pip install -e . # editable install + dependencies

source .venv/bin/activate      # Linux/macOS
# or .venv\Scripts\activate    # Windows

uv run main.py "List files in the current directory" --verbose

### 3. Add your Gemini API key

Create `.env` file:

```bash
GEMINI_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. Run examples

# Basic usage
uv run main.py "List all files in the root directory"

# With verbose output (recommended when debugging)
uv run main.py "How does the calculator in pkg/render.py print results?" --verbose

# Multi-step reasoning example
uv run main.py "Read pkg/render.py and tell me what colors are used" --verbose

Example Outputs

Command:

uv run main.py "list files in the root folder" --verbose

Typical output:

→ Calling: get_files_info(path=".")
Final answer:
The root directory contains:

• main.py                (1.2 KB)
• config.py              (847 B)
• schemas.py             (2.1 KB)
• call_function.py       (1.4 KB)
• pkg/                   (directory)
• .env                   (ignored)
• requirements.txt       (128 B)

Command:

uv run main.py "explain how results are rendered to console in pkg/"

Typical output:

→ Calling: get_files_info(path="pkg")
→ Calling: get_file_content(path="pkg/render.py")
→ Final answer:

The `pkg/render.py` module renders calculator-style results using:

1. `format_json_output(result)` → converts result to JSON
2. `print(json_string)`        → outputs directly to console

No colors or rich formatting are currently used.

How It Works (Core Loop)

1. User gives a natural language prompt
2. Gemini receives system prompt + available tools + conversation history
3. Model decides to either:
   • call one or more functions, or
   • give the final answer
4. Agent executes the requested function(s)
5. Results are fed back to the model
6. Repeat until the model outputs a final_response

Adding New Tools

1. Define the function schema in schemas.py

FUNCTIONS.append({
    "name": "search_code",
    "description": "Search for text/pattern across the codebase",
    ...
})

2. Implement the actual function in call_function.py

def search_code(pattern: str, case_sensitive: bool = False) -> str:
    ...

3. Add it to the FUNCTION_MAP

FUNCTION_MAP = {
    "get_files_info": get_files_info,
    "search_code": search_code,
    # ...
}

4. (Optional) Mention the new capability in the system prompt

That's it — the agent can now use your new tool.

Requirements

• Python 3.10 – 3.13
• google-generativeai
• python-dotenv
• uv (optional – recommended runner)

# requirements.txt
google-generativeai>=0.8.0
python-dotenv>=1.0.0

⚠️ Security Notice

This agent can write and execute arbitrary Python code.

→ Never run it on an untrusted codebase or with important files nearby.

Consider using it inside Docker / a sandbox / with limited filesystem access.

License

MIT

Enjoy building & exploring!

This version:

- Uses clearer hierarchy and modern markdown style
- Adds safety warning (very important for agents that can write/execute)
- Makes setup steps more foolproof
- Shows realistic output examples
- Improves readability with emoji section breaks
- Uses better command formatting
- Explains the loop more clearly
- Makes extensibility concrete with steps + code snippets

Feel free to adjust tone, license, or add badges if desired. Good luck with the project! 🚀