aiagent

A small command-line AI coding agent, built by following a boot.dev guided project.

You give it a request in plain English. It asks a model on OpenRouter what to do, runs the tool the model requests, sends the result back, and repeats until the model answers in plain text instead of calling a tool.

All file and Python access is confined to the bundled calculator/ sample project, so the agent can experiment without touching the rest of your machine.

What it can do

The agent can call four tools:

Tool	Purpose
get_files_info	List a directory with file sizes and directory flags
get_file_content	Read a file, truncated at 10,000 characters
write_file	Create or overwrite a file
run_python_file	Run a .py file with optional arguments (30 s timeout)

Paths that escape calculator/ are rejected. At most 20 model requests are made per run.

Requirements

• Python >= 3.13
• uv
• An OpenRouter API key

Run it

git clone <your-repo-url>
cd aiagent
uv sync
cp .env.example .env

Open .env and replace the placeholder value with your real OpenRouter key. The file is git-ignored; never commit it.

Then pass your request as one quoted argument:

uv run main.py "list the files in the calculator directory"
uv run main.py "add a docstring to calculator/pkg/calculator.py"

Add --verbose to print token usage and the response:

uv run main.py "what is wrong with calculator/pkg/calculator.py?" --verbose

The final answer goes to stdout and the process exits 0. If the agent still wants tools after 20 requests, it prints a message and exits 1.

Caution

The agent writes and executes Python with your user privileges, limited to calculator/. Run it against a checkout whose contents you can afford to lose.