Miniature AI Agent

Hello there :D
I present to you a toy version of Claude Code, or much rather a command line codding agent built from scratch on top of a pre-trained LLM.

Diclaimer: This project does not train or build an LLM. It uses a free model via OpenRouter (through the OpenAI Python SDK) as the reasoning engine, and wraps it in an agent loop: the model is given a coding task, a set of tools, and the autonomy to call those tools repeatedly until the task is done.

What it does

Give the agent a task to perform in plain English and it will:

1. Accept the task as a prompt (e.g. "fix my calculator app, it's not working correctly")
2. Reason about which four of it's tools to call next
3. Call that tool, read the result and decide the next step
4. Repeat (upto 20 iterations) until it produces a final result

The agent never touches your file system directly. Every tool call is confined to the sandbox/ directory, and each tool call checks that the resolved path stays inside it before doing anything.

Tools available to the agent

Tool	What it does
get_files_info	Lists files/directories in a given path, with size and directory status
get_file_content	Reads a file's contents (truncated at MAX_CHARS, 10,000 chars)
write_file	Creates or overwrites a file
run_python_file	Executes a Python file, with optional CLI args, and returns its output

How it works

• main.py — entry point: loads env vars, builds the OpenRouter client, parses CLI args, kicks off the loop
• agent.py — the loop itself (agent_loop), capped at MAX_ITERATIONS (20)
• client.py — builds the OpenAI-SDK client pointed at OpenRouter's API
• prompts.py — the system prompt defining the agent's rules and available tools
• config.py — MAX_ITERATIONS and MAX_CHARS
• tools/ — the 4 tool implementations + their function-calling schemas
• sandbox/ — the only directory the agent is allowed to read, write, or execute inside (includes a sample buggy calculator app to test the agent on)

Prerequisites

• Python 3.10+
• uv — Python project/package manager (install docs)
• A Unix-like shell (bash/zsh); Windows users need WSL 2
• An OpenRouter account (free tier works: ~50 requests/day)

Setup

git clone https://github.com/RichieBuilds/ai-agent.git
cd ai-agent
uv sync
 
cp .env.example .env
# then edit .env and add your OPENROUTER_API_KEY

Usage

uv run main.py "<describe the task you want the agent to do>"
 
# with verbose output (prints each function call + token usage totals)
uv run main.py "<task>" -v