DBAdmin/brain/raw/articles/Jak wdrożyć autoresearch_.md at 64944cf004766b20856fbfdc8b7dee45fd84c953

dexter/DBAdmin

Fork 0

Files

T

Paweł Domański 64944cf004 May 17, 2026, 11:40 PM

2026-05-18 06:40:19 +00:00

36 KiB

Raw Blame History

title, source, author, published, created, description, tags

title

source

author

published

created

description

CZĘŚĆ 1: Co to jest i dlaczego powinno cię to obchodzić?

7 marca 2026 roku Andrej Karpathy, jeden z najsłynniejszych badaczy AI (były dyrektor AI w Tesli, współzałożyciel OpenAI), opublikował aktualizację projektu o nazwie autoresearch.

Oto pomysł w najprostszych możliwych słowach:

Wyobraź sobie, że masz małą AI, malutki model językowy, który ledwo potrafi łączyć słowa. Aby było mądrzej, ludzki badacz zwykle siedziałby przy komputerze godzinami: zmieniał ustawienie, przeprowadzał test, sprawdzał, czy pomagał, i powtarzał. Raz za razem. To nużące.

Autoresearch zastępuje ludzkiego badacza agentem AI. Proste instrukcje piszesz prostym angielskim w pliku tekstowym. Następnie agent AI robi to w pętli automatycznie, przez całą noc:

Przeczyta twoje instrukcje
Zmienia kod treningowy (pojedynczy plik zwany train.py)
Uruchamia 5-minutowy test treningowy na GPU twojego komputera (potężny układ obsługujący ciężką matematykę)
Mierzy wynik, czyli wynik zwany val_bpb (niższa liczba = mądrzejszy model)
Jeśli wynik się poprawi, reszta zostaje zapisana. Jeśli nie, to wyrzuca go
Powtarza około 12 eksperymentów na godzinę, około 100 w nocy

Budzisz się z prawdziwym, mierzalnym postępem, nie kiwając palcem.

Karpathy opisuje to jako "częściowo kod, częściowo science fiction i szczyptę psychozy." Każda kropka na jego wykresie postępu to jeden kompletny, pięciominutowy eksperyment, a model stopniowo się poprawia, gdy kropki się kumulują.

Dlaczego to ma znaczenie poza samym eksperymentem: To jest przedsmak tego, dokąd zmierzają badania nad AI. Zamiast ludzi ręcznie dostosowujących ustawienia, agenci AI prowadzą eksperymenty autonomicznie. Nie tylko prowadzisz fajną demonstrację, ale doświadczasz, jak w praktyce wyglądają zautomatyzowane badania AI.

Dobrze, reszta tego artykułu (Część 2,3,4,5,6,7,8,9,10,11,12,13) przedstawi wszystko z dużą ilością szczegółów. Chciałem też przedstawić uproszczoną wersję, którą umieszczę w tym kodzie markdown, który możecie skopiować i wkleić, co przechodzi od razu do sedna. Możesz przewinąć do części 2, ale chciałem dać ci taką opcję tutaj:

# Run Karpathy's Autoresearch Today

### An AI runs experiments on your computer all night while you sleep. Here's how to set it up.

---

## Step 0: Can Your Computer Do This?

**You need one of these:**

- **A Windows or Linux PC with an NVIDIA graphics card** (like an RTX 3060, 4070, or 4090)
- **A Mac with an M1, M2, M3, or M4 chip** (any Mac bought since late 2020)

**To check on Windows:** Press the Windows key, type "Command Prompt", open it, type \`nvidia-smi\`, press Enter. If you see your GPU name, you're good.

**To check on Mac:** Click the Apple menu → About This Mac. Look for "Chip." If it says M1, M2, M3, or M4 (or any variant like M2 Pro, M3 Max), you're good. If it says Intel, this won't work.

**If you don't have either of these, stop here** — this project requires a powerful GPU to run.

---

## Step 1: Open Your Terminal

This is a text window where you type commands. Every computer has one.

- **Mac:** Press \`Cmd + Space\`, type **Terminal**, press Enter
- **Windows:** Press the Windows key, type **PowerShell**, press Enter
- **Linux:** Press \`Ctrl + Alt + T\`

You'll use this window for every step below.

---

## Step 2: Install Two Small Tools

**Install uv** (this handles Python and all dependencies automatically):

Mac/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

**Install Claude Code** (the AI agent that runs experiments for you — requires a Claude Pro or Max subscription at $20–100/month):

Mac/Linux:

curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell):

irm https://claude.ai/install.ps1 | iex

**Now close your Terminal and open a fresh one.** This is essential — skip it and the next steps will fail.

> **Don't want to pay for Claude Code?** Download Cursor for free from cursor.com instead. It does the same job but with a visual interface rather than the Terminal. The rest of this guide still applies — you'll just use Cursor's chat panel instead of Claude Code.

---

## Step 3: Install Git (If You Don't Have It)

Git tracks all the experiments. Check if you already have it:

git --version

If you see a version number, skip ahead. If not:

- **Mac:** It will prompt you to install Xcode Command Line Tools — click Install
- **Windows:** Download from https://git-scm.com/download/win and run the installer (accept all defaults)
- **Linux:** \`sudo apt install git\`

---

## Step 4: Download the Project

**Mac users** — you need the Mac-compatible version:

cd ~/Desktop
git clone https://github.com/miolini/autoresearch-macos.git
cd autoresearch-macos

**Windows/Linux users** — you need the original:

cd ~/Desktop
git clone https://github.com/karpathy/autoresearch.git
cd autoresearch

> On Windows, replace \`~/Desktop\` with \`%USERPROFILE%\Desktop\`

---

## Step 5: Set Everything Up

Run these three commands one at a time:

uv sync

*(Installs Python and all packages. Takes a few minutes the first time.)*

uv run prepare.py

*(Downloads training data. Takes about 2 minutes. Only needed once.)*

uv run train.py

*(Runs one 5-minute test. If it finishes and shows a number next to "val_bpb" — you're ready.)*

**If you get a red error:** Copy the entire error message, paste it into claude.ai, and ask "What does this mean and how do I fix it?" You'll get a direct answer.

---

## Step 6: Let the AI Run All Night

Make sure you're in the project folder, then launch Claude Code:

claude

It will ask you to log in the first time — follow the browser prompt.

Once you see the Claude Code prompt, type this:

Hi have a look at program.md and let's kick off a new experiment! Let's do the setup first.

**That's it.** Claude will start reading the project, modifying the training code, running 5-minute experiments, keeping what works, discarding what doesn't, and repeating. Minimise the window and go to sleep.

You'll wake up to dozens of successful experiments and a smarter model than you started with.

> **Using Cursor instead?** Open the project folder in Cursor (File → Open Folder), then type the same message into Cursor's AI chat panel on the right side.

---

## Quick Answers

**What is val_bpb?** A score measuring how smart the model is. Lower = better.

**What is train.py?** The single file containing all the AI training code. The AI agent modifies this file during experiments.

**What is program.md?** Your instruction file for the AI agent. This is the only file you ever need to edit — it tells the agent what to try.

**Is the Mac version safe?** Yes. Karpathy links to it from his own project page. The developer (Artem Andreenko) has 167 public projects on GitHub and a years-long public track record. The fork announcement got 70,000+ views on X. The entire codebase is about 630 lines — you can read the whole thing in 20 minutes.

**How many experiments will it run overnight?** About 100 (roughly 12 per hour).

**Do most experiments succeed?** No. Most fail. That's normal. The agent automatically keeps the wins and throws away the losses. Out of 100 experiments, maybe 10–20 will be improvements.

**What does it cost?** The code is free. Claude Code requires Claude Pro ($20/month) or Max ($100/month). Cursor has a free tier if you run experiments manually.

---

## If Something Goes Wrong

| Problem | Fix |
|---|---|
| \`command not found: uv\` | Close Terminal, open a new one |
| \`command not found: git\` | Install git (see Step 3) |
| CUDA / GPU error (Windows/Linux) | Search YouTube: "install CUDA toolkit [your GPU]" |
| MPS / Metal error (Mac) | Make sure you downloaded the Mac fork, not the original |
| Out of memory | Your GPU needs more VRAM. The agent usually adapts automatically |
| Claude Code won't authenticate | You need a paid Claude subscription ($20/month minimum) |

---

**Links:**
Original (Windows/Linux): https://github.com/karpathy/autoresearch
Mac version: https://github.com/miolini/autoresearch-macos
Cursor: https://cursor.com
Claude Code: https://code.claude.com

---

*Total setup time: about 30 minutes. Then it runs by itself.*

CZĘŚĆ 2: Czy masz odpowiedni komputer?

To jest najważniejsza część. Jeśli Twój komputer nie spełnia tych wymagań, projekt nie będzie działał. Przeczytaj to uważnie przed instalacją czegokolwiek.

Użytkownicy Windows lub Linux

Potrzebujesz:

Karta graficzna NVIDIA (GPU): przykłady: RTX 3060, RTX 3070, RTX 4070, RTX 4090 lub dowolna karta NVIDIA z ostatnich kilku lat
Co najmniej 10–20 GB wolnej przestrzeni na dysku
Połączenie internetowe
Windows 10 lub 11 albo dystrybucję Linuksa, jak Ubuntu

Jak sprawdzić, czy masz kartę graficzną NVIDIA (Windows):

Naciśnij klawisz Windows na klawiaturze
Wpisz Command Prompt i otwórz go (to czarne okno, w którym wpisujesz tekst)
Wpisz dokładnie to i naciśnij Enter: nvidia-smi
Jeśli pokazuje nazwę GPU i wersję sterownika, wszystko w porządku, kontynuuj
Jeśli pojawi się komunikat "polecenie nie znalezione" lub pojawi się błąd, to albo nie masz karty graficznej NVIDIA, albo musisz najpierw zainstalować sterowniki NVIDIA

Brak karty graficznej NVIDIA? Oryginalny projekt autoresearch nie zadziałał dla ciebie na Windows/Linux. Ale jeśli masz Maca, przeczytaj następną część.

Użytkownicy Maca

Oryginalny kod Karpathy obsługuje tylko karty graficzne NVIDIA, których Maci nie posiadają. Jednak deweloper o imieniu Artem Andreenko stworzył wersję kompatybilną z Maciem, która działa z własnymi układami Apple.

Potrzebujesz:

Apple Silicon Mac, każdy Mac z układem M1, M2, M3 lub M4
Minimum 16 GB pamięci (32 GB lub więcej to lepsze dla większych eksperymentów)
Co najmniej 10–20 GB wolnej przestrzeni na dysku
Połączenie internetowe

Jak sprawdzić chip w Macu:

Kliknij menu Apple (ikona Apple w lewym górnym rogu ekranu)
Kliknij O tym Macu
Szukaj "Chip", powinno być tam M1, M2, M3, M4 lub jakiś wariant jak M2 Pro, M3 Max itd.
Jeśli zamiast tego pojawi się "Intel", niestety ten projekt nie będzie dla ciebie dobrze działał

Każdy MacBook Air, MacBook Pro, Mac Mini, iMac, Mac Studio i Mac Pro sprzedawany od końca 2020 roku posiada układ Apple Silicon. Jeśli kupiłeś Maca w ciągu ostatnich 5 lat, prawie na pewno wszystko jest w porządku.

Ważne: Na Macu pobierasz z innego linku (fork macOS) zamiast oryginalnego Karpathy. Polecenia konfiguracyjne są niemal identyczne, zmienia się tylko źródło pobierania.

Tabela szybkiego dostępu

CZĘŚĆ 3: "Czy wersja na Maca jest bezpieczna?"

Mądre pytanie. Zawsze warto dwa razy się zastanowić, zanim uruchomisz kod z internetu. Oto, co sprawdziłem:

Sam Karpathy do niego odwołuje linki. Jego własna strona autoresearch README bezpośrednio wspomina fork macOS (miolini/autoresearch-macos) w sekcji platform. Zaprosił społeczność do stworzenia forków dla innych platform i podlinkował tę platformę. To najbliższe oficjalnemu rekomendacji, jakie można dostać.

To prawdziwy fork GitHuba. GitHub publicznie oznacza to jako "rozgałęzione z karpathy/autoresearch." Każda zmiana wprowadzona przez dewelopera względem oryginału jest widoczna i łatwa do śledzenia. Nic nie jest ukryte.

Deweloper to prawdziwa, ugruntowana osoba. Artem Andreenko (nazwa użytkownika: miolini) ma 167 publicznych projektów na GitHub, siedzi w San Diego i prowadzi firmę o nazwie SentientWave. Ma wieloletnie doświadczenie w programowaniu publicznym, narzędziach Go, rozszerzeniach do przeglądarek, testach sieciowych. To nie jest anonimowe ani jednorazowe konto.

Ogłoszenie forku było bardzo publiczne. Jego ogłoszenie na X (Twitter) było bezpośrednią odpowiedzią na oryginalny post Karpathy'ego i zdobyło około 70 000 wyświetleń, 58 retweetów i 781 polubień. Tysiące programistów zobaczyło i dokładnie przeanalizowało kod.

Zmiany są niewielkie i dobrze zrozumiane. Fork zastępuje bibliotekę wyłącznie dla NVIDIA (FlashAttention-3) na wbudowaną wersję PyTorch oraz dodaje specyficzne dla Apple Metal poprawki pamięci i kompilacji. To standardowe, nudne adaptacje, nie egzotyczne czy podejrzane.

Cały kod jest malutki. Plik treningowy ma około 630 linii Pythona. Możesz przeczytać wszystko w 20 minut. Nie ma gdzie ukryć się złośliwy kod.

Dodatkowy krok bezpieczeństwa: Po pobraniu otwórz folder w Claude Code i zapytaj: "Przeczytaj każdy plik w tym repozytorium. Czy jest coś podejrzanego, jakieś ukryte wywołania sieciowe, zbieranie danych lub kod, który robi coś więcej niż tylko trenowanie modelu językowego?" W tak małym projekcie audyt trwa około 30 sekund.

Podsumowując: To legalny, popierany przez społeczność fork powiązany z Karpathy przez prawdziwego dewelopera z publiczną historią. To tak bezpieczne, jak można znaleźć oprogramowanie open source dla czegoś tak nowego.

CZĘŚĆ 4: Żargonowy łamacz (Przeczytaj to)

Zanim cokolwiek zainstalujesz, oto słownik w prostym języku, żeby nic cię nie zaskoczyło:

Terminal: Okno tekstowe, w którym wpisujesz polecenia zamiast klikać przyciski. Każdy komputer ma taki wbudowany. Na Macu nazywa się to "Terminal". Na Windows nazywa się to "Wiersz poleceń" lub "PowerShell". Pomyśl o tym jak o pisaniu SMS-a do komputera, a on odpisuje.

GPU: Jednostka przetwarzania grafiki. Potężny układ scalony w twoim komputerze, który obsługuje ciężką matematykę. Trening AI w dużej mierze opiera się na GPU. Twój zwykły procesor (CPU) to mózg; GPU to siła napędowa.

CUDA: Oprogramowanie NVIDIA pozwalające programom korzystać z kart NVIDIA do matematyki. Potrzebujesz tego na Windows/Linux. Pomyśl o tym jak o tłumaczu między kodem treningowym a sprzętem NVIDIA.

Metal / MPS: Wersja CUDA od Apple. Jest wbudowany w każdego Maca z Apple Silicon. Nie musisz nic instalować, po prostu działa.

Git: System śledzenia zmian w plikach w czasie. Pomyśl o tym jak o "punktach zapisu" w grze wideo. Za każdym razem, gdy agent AI znajduje poprawę, tworzy punkt zapisu. Jeśli kolejny eksperyment się nie powiedzie, można wrócić do ostatniego dobrego zapisu.

uv: Małe, darmowe narzędzie, które automatycznie instaluje Pythona (język programowania używany w tym projekcie) oraz całe inne oprogramowanie potrzebne przez projekt. To znacznie ułatwia przygotowanie. Bez UV trzeba by zainstalować kilka rzeczy osobno.

val_bpb: "Bity walidacyjne na bajt." Jeden wynik, który mierzy, jak inteligentny jest model AI. Niższe liczby = mądrzejszy model. To jest liczba, którą agent AI próbuje obniżyć z dnia na dzień.

train.py: Pojedynczy plik Pythona, który zawiera cały kod treningowy AI. To jedyny plik, który agent AI modyfikuje podczas eksperymentów. Zawiera architekturę modelu, ustawienia optymalizatorów, pętlę treningową, wszystko.

program.md: Plik instrukcji, który piszesz dla agenta AI. To jedyny plik, który ty (człowiek) musisz kiedykolwiek edytować. Mówi agentowi, jakie eksperymenty ma wypróbować, co priorytetowo traktować i jak się zachowywać. Pomyśl o tym jak o odprawie misji, którą przekazujesz swojemu niestrudzonemu asystentowi laboratoryjnemu przed snem.

Repozytorium / Repozytorium: Folder projektów na GitHubie. Kiedy ludzie mówią "pobierz repozytorium", mają na myśli "pobierz folder projektu".

Fork: A copy of someone else's project that you can modify independently. The Mac version is a "fork" of Karpathy's original, same foundation, adapted for different hardware.

Clone: Downloading a copy of a project from GitHub to your computer using a Terminal command.

PART 5: What You Need to Install

You need exactly three free tools plus one AI tool (which requires a paid subscription). Here's each one and how to get it.

Tool 1: Terminal (You Already Have This)

Every computer comes with a Terminal built in. You just need to open it.

Mac: Press Cmd + Space (this opens Spotlight search), type Terminal, press Enter. A window with a blinking text cursor will appear
Windows: Press the Windows key, type Command Prompt or PowerShell, press Enter. A window (usually black or blue) with a blinking text cursor will appear
Linux: Press Ctrl + Alt + T. A terminal window will appear

This is where you'll type all the commands in this guide. When this guide says "open Terminal," it means open this window.

Tool 2: Git

Git is the save-point system that tracks every experiment. You need it installed.

Mac: Git usually comes pre-installed. To check, open Terminal and type:

git --version

If you see a version number like git version 2.39.0, you're done. If macOS asks you to install "Xcode Command Line Tools," click Install and wait a few minutes. That will install git for you.

Windows:

Go to https://git-scm.com/download/win in your web browser
Download the installer
Run it and accept all the default settings (just click Next, Next, Next, Install)
When it's done, close and reopen Command Prompt
Type git --version to confirm it worked

Linux (Ubuntu/Debian): Open Terminal and type:

sudo apt install git

Enter your password when asked.

Tool 3: uv (The Automatic Installer)

This tiny tool will install Python and every package the project needs, automatically. You do not need to install Python separately. uv handles everything.

Mac or Linux: Open Terminal and paste this exact command, then press Enter:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows: Open PowerShell (not Command Prompt) and paste:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Critical step after installing uv: Close your Terminal/PowerShell window completely. Then open a brand new one. This is essential, the new window will recognise the uv command. If you skip this step, your computer won't know uv exists yet.

To verify it worked, type in the new window:

uv --version

You should see a version number.

Tool 4: Your AI Agent (The Brain That Runs the Experiments)

The AI agent is the intelligence that actually reads your instructions, modifies the code, runs experiments, and decides what to keep or discard. You need one of the following options:

Option A: Claude Code, Best for Full Autopilot

What it is: A command-line tool made by Anthropic (the company behind Claude). It runs directly in your Terminal, can read and write files, run commands, and use git, exactly what autoresearch needs for the fully autonomous loop.

What it costs: Requires a paid subscription, Claude Pro ($20/month) or Claude Max ($100 or $200/month). A free Claude account will not work with Claude Code.

How to install (Mac or Linux):

curl -fsSL https://claude.ai/install.sh | bash

How to install (Windows or PowerShell):

irm https://claude.ai/install.ps1 | iex

After installing, close and reopen your Terminal. Then type:

claude --version

If you see a version number, the installation worked.

First time you run it: When you type claude for the first time, it will open your web browser and ask you to log in to your Anthropic account. Follow the prompts to authenticate. This only happens once.

Option B: Cursor, Best for Visual Learners

What it is: A free AI-powered code editor. It looks like a normal text editor but has an AI chat panel built into the right side. Under the hood, it uses Claude or other AI models.

What it costs: Has a free tier with limited AI usage. Pro plan is $20/month for heavier use.

How to install:

Go to https://cursor.com in your web browser
Download the installer for your operating system
Install it like any other app (drag to Applications on Mac, run the installer on Windows)

Cursor is easier if you like seeing files visually and chatting with the AI in a sidebar. However, the fully autonomous overnight loop works more smoothly with Claude Code.

Option C: Claude.ai Chat, Manual Only (What You're Reading This In)

You can use the Claude.ai chat interface to troubleshoot errors, get explanations, or ask for code change suggestions. But you cannot automate the loop, you'd have to copy-paste code and results back and forth manually. This works for learning, but it's not what the project was designed for.

Can you use Claude with autoresearch? Yes, Karpathy says so himself. His README explicitly says: "Simply spin up your Claude/Codex or whatever you want in this repo."

This bit is up to you, you can use Claude Code, Codex, Cursor etc. The choice is yours here.

PART 6: Step-by-Step Setup

Pick your operating system below and follow every command exactly. Copy-paste is your friend, don't try to type these from memory.

Setup for Mac (Apple Silicon)

Step 1: Open Terminal

Press Cmd + Space, type Terminal, press Enter.

Step 2: Download the Mac version of autoresearch

Type these commands one at a time, pressing Enter after each:

cd ~/Desktop
git clone https://github.com/miolini/autoresearch-macos.git
cd autoresearch-macos

What this does: Goes to your Desktop, downloads the Mac-compatible version of the project, and enters the project folder.

If you'd rather not use git: Go to https://github.com/miolini/autoresearch-macos in your web browser, click the green Codebutton, click Download ZIP, unzip it to your Desktop. Then in Terminal type:

cd ~/Desktop/autoresearch-macos-master

Step 3: Install all the software the project needs

uv sync

This downloads and installs Python, PyTorch, and everything else automatically. The first time takes a few minutes, you'll see progress bars. Be patient.

Step 4: Download the training data

uv run prepare.py

This downloads the text data the model will learn from and builds a tokenizer (a tool that chops text into small pieces the model can process). Takes about 2 minutes. You only ever need to do this once.

Step 5: Run one test training to make sure everything works

uv run train.py

This runs a single 5-minute training session on your Mac's GPU using Metal. You should see:

Numbers scrolling by (this is normal, it's showing training progress)
After about 5–7 minutes (including startup time), it finishes
It displays a val_bpb score at the end

If it finishes without big red error messages, your setup is complete. You're ready for the fun part.

If you see errors: Copy the entire red error text, paste it into Claude.ai (this chat), and ask: "What does this error mean and how do I fix it on a Mac?" You'll get a direct answer.

Setup for Windows (NVIDIA GPU)

Step 1: Open Command Prompt or PowerShell

Press the Windows key, type Command Prompt, press Enter.

Step 2: Download autoresearch

cd %USERPROFILE%\Desktop
git clone https://github.com/karpathy/autoresearch.git
cd autoresearch

If you'd rather not use git: Go to https://github.com/karpathy/autoresearch in your browser, click the green Code button, click Download ZIP, unzip to your Desktop, then:

cd %USERPROFILE%\Desktop\autoresearch-master

Step 3: Install all the software the project needs

uv sync

Step 4: Download the training data

uv run prepare.py

Step 5: Run one test training

uv run train.py

If it finishes after about 5 minutes and shows a val_bpb score, you're good.

If you get a CUDA error or GPU error: This means your NVIDIA drivers or CUDA toolkit aren't set up correctly. Search YouTube for "install NVIDIA CUDA toolkit [your GPU model] Windows" and follow a video tutorial. This is a one-time setup, and there are excellent step-by-step videos available.

Setup for Linux (NVIDIA GPU)

Step 1: Open Terminal

Press Ctrl + Alt + T.

Step 2: Download autoresearch

cd ~/Desktop
git clone https://github.com/karpathy/autoresearch.git
cd autoresearch

Step 3–5: Same as Windows

uv sync
uv run prepare.py
uv run train.py

If it finishes and shows a val_bpb score, your setup is complete.

PART 7: Let the AI Do the Research

You've confirmed the test training works. Now it's time to hand the keys to the AI agent and let it run all night.

Full Autopilot with Claude Code (Recommended)

Step 1: Open Terminal and go to your project folder:

Mac:

cd ~/Desktop/autoresearch-macos

Windows:

cd %USERPROFILE%\Desktop\autoresearch

Linux:

cd ~/Desktop/autoresearch

Step 2: Launch Claude Code:

The first time, it will ask you to authenticate in your browser. Follow the prompts and log in to your Anthropic account. Once you see the Claude Code prompt (a cursor waiting for your input), type this exact message:

Hi have a look at program.md and let's kick off a new experiment! Let's do the setup first.

Step 3: Claude Code will now automatically:

Read the program.md instruction file
Read all the project files to understand the codebase
Create a git branch (a separate save-point track) for the experiment run
Start modifying train.py with its first experimental idea
Run the 5-minute training
Check the val_bpb score
If the score improved, save the change with git. If not, discard it
Move on to the next experiment and repeat

Step 4: Minimise the window and go to bed. Or go cook dinner. Or watch a film. The AI agent will keep running experiments all night without you.

Pro tip: To make it fully autonomous without pausing to ask you questions, you can tell it at the start: "Run fully autonomously. Don't ask for confirmation between experiments. Keep going until I come back."

Semi-Manual with Cursor (Good for Learning)

Step 1: Open Cursor. Click File → Open Folder and navigate to your autoresearch folder on the Desktop.

Step 2: In the file list on the left, click on program.md to open it. Read through it, it's written in plain English.

Step 3: In Cursor's AI chat panel (usually on the right side), type:

Hi have a look at program.md and let's kick off a new experiment! Let's do the setup first.

Step 4: The AI will suggest changes to train.py. Click the accept/apply button to make the changes.

Step 5: Open Terminal, navigate to your project folder, and run:

uv run train.py

Step 6: When it finishes (about 5 minutes), tell the AI in Cursor's chat what the val_bpb score was. It will decide whether to keep or discard the change, then suggest the next experiment.

Step 7: Repeat. As you get comfortable, Cursor's AI can handle more of the loop automatically.

Fully Manual with Claude.ai Chat

If you don't have Claude Code or Cursor:

Run uv run train.py in your Terminal
Copy the output (especially the val_bpb score) and paste it into Claude.ai
Ask Claude to suggest the next experiment, what to change in train.py and why
Make the change in a text editor (any text editor works, TextEdit on Mac, Notepad on Windows)
Run uv run train.py again
Repeat

This is the slowest option but works perfectly for understanding how the process works.

PART 8: What You'll See When You Wake Up

After a night of autonomous experiments, here's what you'll find in your project folder:

A git history full of commits. Each commit is one successful experiment where the agent found an improvement. View it by opening Terminal, navigating to your project folder, and typing:

git log --oneline

A lower val_bpb score. The model has genuinely gotten smarter compared to where it started. The starting baseline is around 0.9979, anything lower means progress.

A heavily modified train.py. The agent will have changed the training code in ways that improve performance, architecture tweaks, different optimiser settings, adjusted hyperparameters, modified batch sizes, and more.

A results.tsv file. This is a spreadsheet-style log of every experiment with its score, memory usage, and whether it was kept or discarded.

An analysis.ipynb notebook. You can open this in Cursor or Jupyter Notebook to see graphs showing how the score improved over time, each dot is one experiment.

Part 9: Understanding What's Happening (Optional but Interesting)

You don't need to understand any of this to use autoresearch. But if you're curious:

What does the agent actually change? Everything inside train.py is fair game. The agent might change the model's architecture (how the neural network is shaped), the optimiser (how the model learns from mistakes), the learning rate (how big the adjustments are), the batch size (how much data it looks at per step), and more.

Why 5 minutes? A fixed time budget means every experiment is directly comparable. Whether the agent tries a huge model or a tiny one, it always gets exactly 5 minutes. This forces the agent to find the most efficient configuration for your specific hardware.

Why is val_bpb the metric? Bits per byte is a vocabulary-independent measure of how well the model predicts text. Unlike some other metrics, it works fairly even when the agent changes the tokeniser vocabulary size, making it ideal for comparing wildly different configurations.

What's program.md doing? It's the "meta-prompt", the instructions that tell the AI agent how to behave. Improving this file is your job as the human. Better instructions lead to faster research progress. Karpathy's insight is that the human is now programming the research organisation, not running individual experiments.

PART 10: Tips for Getting the Best Results

Start simple. Get one manual run working first (uv run train.py). If that doesn't work, the autonomous loop won't either. Fix the basics before going autopilot.

Your one job is to improve program.md. This is the leverage point. Add instructions like: "Try small improvements first. Focus on making val_bpb go down. Think step by step and explain every change before making it. If an experiment direction hasn't worked after 3 attempts, try something completely different."

Don't panic when experiments fail. Most experiments will not improve the score. Out of 100 overnight experiments, maybe 10–20 will be keepers. This is completely normal, it's how research works. The agent discards failures and keeps successes automatically.

Check in periodically at first. Before trusting the full overnight run, watch the first 3–4 experiments to make sure the loop is working. If the agent is stuck or confused, adjust your program.md instructions and restart.

More memory helps. If you have a Mac with 32 GB or 64 GB of unified memory, or a GPU with lots of VRAM (like the RTX 4090 with 24 GB), the agent can explore larger models and more complex architectures within each 5-minute window.

PART 11: Troubleshooting

"command not found: uv" Close your Terminal window completely and open a fresh one. After installing uv, you must start a new Terminal session for it to be recognised.

"command not found: git" You need to install git first. See Part 5, Tool 2.

"CUDA error" or "no CUDA-capable device" (Windows/Linux) Your NVIDIA drivers or CUDA toolkit aren't installed or configured. Search YouTube for "install CUDA toolkit [your GPU model]" and follow a step-by-step video. This is a one-time setup.

"MPS error" or Metal-related error (Mac) Make sure you downloaded the macOS fork (miolini/autoresearch-macos), not Karpathy's original repo. The original does not support Mac.

"Out of memory" or "OOM" Your GPU doesn't have enough memory for the model size the agent is trying. The agent should handle this automatically by trying smaller configurations, but if it keeps happening, you may need a GPU with more VRAM or more unified memory on Mac.

"uv sync" is very slow or seems stuck This is normal on the first run. It's downloading PyTorch, which is a large package (several gigabytes). Make sure your internet connection is stable and just wait.

Claude Code says "authentication required" or won't start You need a paid Claude subscription. Claude Pro is $20/month and is the minimum required. Free accounts do not work with Claude Code.

The test training works but Claude Code doesn't start the experiment loop Make sure you're in the right folder when you launch claude. Use cd to navigate to your autoresearch folder first. If Claude Code seems confused, try being more explicit: "Read the file program.md in this directory, then follow its instructions to set up and run autonomous experiments on train.py."

"Permission denied" errors On Mac/Linux, you might need to make files executable. Try: chmod +x train.py prepare.py. On Windows, make sure you're running PowerShell or Command Prompt normally (not as Administrator unless specifically needed).