AI Coding Agent

A command-line AI coding assistant built with Python, the OpenAI Python SDK, and OpenRouter. This project demonstrates how modern AI agents such as Claude Code and Cursor work under the hood by combining large language models with secure tool calling.

The agent can inspect project files, read source code, modify files, execute Python programs, and iteratively solve coding tasks while operating within a restricted working directory for safety.

---

Features

• 🤖 AI-powered command-line coding assistant
• 📂 List files and directories
• 📖 Read file contents safely
• ✍️ Create and overwrite project files
• ▶️ Execute Python programs with optional arguments
• 🔒 Secure sandboxed file operations
• 🧠 Multi-step reasoning using iterative tool calls
• 📝 Verbose mode for debugging and development
• 🔑 Environment-based API key management

---

Tech Stack

• Python 3.10+
• OpenAI Python SDK
• OpenRouter API
• python-dotenv
• argparse
• JSON Schema (Tool Definitions)
• subprocess
• uv (Python package manager)

---

Project Structure

ai_agent/
├── calculator
│   ├── lorem.txt
│   ├── main.py
│   ├── pkg
│   │   ├── calculator.py
│   │   ├── morelorem.txt
│   │   ├── __pycache__
│   │   │   ├── calculator.cpython-313.pyc
│   │   │   └── render.cpython-313.pyc
│   │   └── render.py
│   ├── README.md
│   └── tests.py
├── call_function.py
├── config.py
├── functions
│   ├── get_file_content.py
│   ├── get_files_info.py
│   ├── __pycache__
│   │   ├── get_file_content.cpython-313.pyc
│   │   ├── get_files_info.cpython-313.pyc
│   │   ├── run_python_file.cpython-313.pyc
│   │   └── write_file.cpython-313.pyc
│   ├── run_python_file.py
│   └── write_file.py
├── LICENSE
├── main.py
├── prompts.py
├── __pycache__
│   ├── call_function.cpython-313.pyc
│   ├── config.cpython-313.pyc
│   └── prompts.cpython-313.pyc
├── pyproject.toml
├── README.md
├── test_get_file_content.py
├── test_get_files_info.py
├── test_run_python_file.py
├── test_write_file.py
└── uv.lock

7 directories, 32 files

---

How It Works

The agent follows an iterative workflow:

1. Receives a coding request from the user.
2. Sends the request to an LLM through OpenRouter.
3. The model decides which tool(s) to use.
4. The application securely executes the requested function.
5. The function result is returned to the model.
6. The process repeats until the model produces a final answer.

This tool-calling loop enables the agent to inspect code, modify files, execute programs, and verify fixes before responding.

---

Available Tools

List Files

Displays the contents of directories inside the working directory.

get_files_info()

---

Read Files

Reads the contents of project files with a configurable maximum character limit.

get_file_content()

---

Write Files

Creates or overwrites files while preventing writes outside the allowed project directory.

write_file()

---

Execute Python Files

Runs Python scripts with optional command-line arguments and captures both standard output and error output.

run_python_file()

---

Installation

Clone the repository.

git clone https://github.com/ikwukao/ai_agent.git
cd ai_agent

Create a virtual environment.

uv venv

Activate it.

Linux/macOS

source .venv/bin/activate

Windows

.venv\Scripts\activate

Install the dependencies.

uv sync

---

Environment Variables

Create a .env file in the project root.

OPENROUTER_API_KEY="your_api_key_here"

Never commit this file to version control.

---

Usage

Run the agent with a prompt.

uv run main.py "Explain how the calculator renders results."

Enable verbose mode.

uv run main.py "Run the calculator tests." --verbose

Example requests:

List all files in the project.

Read calculator/main.py.

Run the calculator tests.

Create a README file.

Fix the bug where 3 + 7 * 2 returns 20.

---

Safety

The agent is intentionally sandboxed.

It cannot:

• Read files outside the configured working directory.
• Write files outside the project.
• Execute non-Python files.
• Access arbitrary locations on the host system through tool calls.

These safeguards reduce the risk of accidental or malicious file access while allowing the LLM to operate effectively within the project.

---

Learning Outcomes

This project demonstrates practical experience with:

• Large Language Model integration
• Function (tool) calling
• OpenAI-compatible APIs
• Prompt engineering
• Secure filesystem operations
• Python subprocess management
• Multi-module Python applications
• Command-line application development
• Environment variable management
• Iterative AI agent workflows

---

Future Improvements

• Conversation memory
• Streaming responses
• Additional developer tools
• Git integration
• Shell command execution
• Unit and integration testing
• Syntax-aware code editing
• Support for multiple LLM providers
• Conversation logging

---

Acknowledgements

This project was built as part of the Boot.dev Backend Developer learning path and is inspired by modern AI coding assistants such as Claude Code, Cursor, and GitHub Copilot.

---

License

This project is intended for educational and portfolio purposes.

---

🎥 Demo

Watch the AI Coding Agent in action:

ai_agent_demo.mp4

---