Autoresearch is an autonomous research framework developed by Karpathy, designed to accelerate the iterative experimentation process for training Large Language Models (LLMs). The core objective is to design an AI agent capable of generating the fastest research progress with minimal human intervention.

The framework is built upon a simplified, self-contained implementation of the nanochat LLM training core, compressed into approximately 630 lines within a single Python file. This design philosophy emphasizes self-sufficiency, requiring only PyTorch and a few additional packages, with no support for distributed training or complex configurations.

The central mechanism revolves around an AI agent engaging in an autonomous, iterative research loop operating within a git feature branch. The human user initializes the research direction by editing program.md, a lightweight instruction file that guides the agent's objectives.

The agent's workflow is as follows:

1. Code Modification: The AI agent autonomously modifies train.py, a single, comprehensive file containing the entire GPT model definition, optimizer (Muon + AdamW), and the training loop. The agent can alter various aspects within this file, including neural network architecture, optimizers, hyperparameters, and batch sizes.
2. Fixed-Time Execution: After modifying train.py, the agent executes the training process for a precisely fixed duration of 5 minutes. This fixed time budget ensures that experimental results are directly comparable across different runs on the same platform, regardless of the complexity or scale of the modifications.
3. Result Evaluation: Upon completion of the 5-minute training run, the agent evaluates the outcome, specifically targeting a reduction in validation loss.
4. Decision and Iteration: If the experiment yields a lower validation loss, the agent commits the changes to the git repository, accumulating successive improvements. If the validation loss does not improve, the changes are discarded, and the agent proceeds to the next iteration. This loop repeats approximately 12 times per hour, enabling around 100 experiments overnight.

The human role is primarily to define the initial prompt in program.md to steer the agent's research direction and to review the experimental logs and improved models generated by the agent the following morning.

The framework's file structure is intentionally streamlined:

• prepare.py: Contains fixed constants, data preparation utilities (e.g., training BPE tokenizers, downloading data), and runtime utilities (e.g., dataloaders, evaluation functions). This file is *not* modified by the AI agent.
• train.py: This is the sole file that the AI agent modifies. It encapsulates the complete LLM training logic.
• program.md: This Markdown file serves as the agent's primary instruction set, editable by humans to define the research scope and objectives.

Current requirements include a single NVIDIA GPU (H100 tested), Python 3.10+, and the uv package manager. The framework prioritizes self-containment, currently limiting support to NVIDIA GPUs to prevent code bloat, though forks for other platforms exist. An external agent (e.g., Claude, Codex) is integrated by prompting it to read program.md and initiate the experimental loop.