Agentic AI Coding Agent

A minimal, hackable AI coding agent that can inspect, read, write, and run code inside a sandboxed directory. Supports local models via LM Studio and Google Gemini.

Documentation

The docs/ folder contains detailed interactive documentation.

Read the full documentation online here

Note for Contributors: The docs are built with Mr Markdown. To preview changes locally, run bunx mr-md dev docs.

Document	Contents
docs/01-theory.md	Intro to agentic AI, the ReAct loop, and how tools work
docs/02-architecture.md	Codebase structure, provider abstraction, tool schemas
docs/03-safety.md	Sandbox constraints, risks, and operational best practices
docs/04-roadmap.md	Planned features and changelog

---

Setup

Install dependencies:

uv sync

Copy the environment file:

cp .env.example .env

Configure a provider (choose one):

# Local — LM Studio
LLM_PROVIDER=lmstudio
LMSTUDIO_BASE_URL=http://localhost:1234/v1
LMSTUDIO_MODEL=your-loaded-model

# Optional tuning
LMSTUDIO_TEMPERATURE=0
LMSTUDIO_MAX_TOKENS=800

# Cloud — Google Gemini
LLM_PROVIDER=gemini
GEMINI_API_KEY=your_gemini_api_key
GEMINI_MODEL=gemini-2.5-flash

---

Usage

# Basic prompt
uv run python main.py "explain how the calculator renders expressions"

# Verbose mode — logs every tool call and result
uv run python main.py "fix the bug in the calculator" --verbose

The agent operates inside the calculator/ sandbox directory and stops after MAX_ITERS iterations (set in config.py).

---

Tools Available to the Agent

Tool	Description
get_dir_info	List files and directories
get_file_content	Read file contents
write_file	Create or overwrite a file
run_python_file	Run a Python file with optional args
search_files	Search for text across files