Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.arcprize.org/llms.txt

Use this file to discover all available pages before exploring further.

The ARC-AGI-3 Kaggle Starter is a local dev kit for the ARC Prize 2026 - ARC-AGI-3 Kaggle competition. You edit one Python file on your laptop, see it play the real game environments locally, and push it to Kaggle as a submission with a single command. Repository: github.com/arcprize/ARC-AGI-3-Kaggle-Starter

​
Prerequisites

  • Python 3.12 (the competition’s arc-agi package requires it)
    • macOS: brew install python@3.12
    • Ubuntu: sudo apt install python3.12 python3.12-venv
    • Windows: install from python.org
  • A Kaggle account with the competition rules accepted (accept here).
  • A Kaggle API token created at Kaggle Settings → Create New Token. You’ll drop it into the project (no ~/.kaggle/kaggle.json required).
No GPU is required for the starter agent.

​
Quick start

# 1. Clone the starter
git clone https://github.com/arcprize/ARC-AGI-3-Kaggle-Starter.git
cd ARC-AGI-3-Kaggle-Starter

# 2. Drop your Kaggle API token into the project-local .kaggle/ folder
#    (NOT your home directory)
mkdir -p .kaggle && echo "KGAT_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" > .kaggle/access_token
chmod 600 .kaggle/access_token

# 3. One-time setup: venv, dependencies, framework
make setup

# 4. Edit agent/my_agent.py. This is the only file you change.

# 5. Run it locally against every game (seconds)
make play-local

# 6. Push it to Kaggle as a submission notebook
make submit

# 7. Watch the run
make status
When make status shows complete, open the notebook on kaggle.com, find your kernel, click Submit to Competition in the top right, and pick submission.parquet from the Output File dropdown. Steps 4-7 are the iteration loop; clicking Submit to Competition is the deliberate moment you spend a daily submission.

​
The one file you edit: agent/my_agent.py

This is the only file you normally touch. It defines a MyAgent class with two methods: 
class MyAgent(Agent):
    def is_done(self, frames, latest_frame) -> bool:
        """Return True when your agent wants to stop playing."""
        ...

    def choose_action(self, frames, latest_frame) -> GameAction:
        """Look at the game state and return the next action."""
        ...
The starter picks random actions, a baseline that proves your pipeline works end-to-end. Replace the body of choose_action with your strategy. Kaggle plumbing, submission file format, and game orchestration are all handled for you.

​
What happens when you run make submit

The competition is a code competition: you submit a notebook, Kaggle runs it twice.
  1. Phase A: Save & Run All. Kaggle runs your notebook in their real environment and validates that the code executes without errors. make status will report complete.
  2. Phase B: Competition Rerun. Triggered when you click Submit to Competition on the kernel page. Your agent plays the hidden game set and your leaderboard score appears.
Before your first make submit, open notebooks/kernel-metadata.json and replace REPLACE_WITH_YOUR_USERNAME with your Kaggle handle. The Makefile will refuse to push until you do.

​
Choosing an accelerator

The notebook is generated with a T4 GPU by default (matches Kaggle’s sample submission). To change it, open scripts/build_notebook.py and edit one line near the top: 
ACCELERATOR = "t4"     # one of: cpu, t4, p100, rtx6000
Re-run make submit. Both the notebook metadata and notebooks/kernel-metadata.json get updated automatically.
ValueHardwareWhen to use
"cpu"No GPUThe random starter, or any non-ML agent
"t4"Nvidia T4 ×2Default. Small models, fast iteration
"p100"Nvidia P100Single big-memory GPU
"rtx6000"Nvidia RTX 6000 (g4-standard-48)Heavy ML; ARC-AGI-3 exclusive, burns GPU quota faster
RTX 6000 is reserved for ARC-AGI-3 notebooks. Don’t use it for early iteration. All accelerated Kaggle sessions have internet disabled, which is already the default in this kit.

​
All the commands

CommandWhat it does
make setupOne-time install: Python venv, arc-agi, kaggle CLI, clones the framework
make play-localRuns your agent against every game in the dataset, locally
make play-local GAME=ls20Same, but only one game (faster while debugging)
make verify-local30-second smoke test on two games
make list-gamesPrint every game id available
make pull-sampleDownload the official sample agent for reference
make notebookBuild the Kaggle notebook from your agent (no push)
make submitBuild the notebook and push it to Kaggle
make statusCheck the status of your most recent Kaggle run
make cleanRemove the venv, downloads, and generated notebook

​
Why this setup instead of editing in the Kaggle notebook?

  1. Iteration speed. Editing in your IDE then running make play-local gives you a real-game-engine feedback loop in seconds. Kaggle’s editor loop is minutes per change.
  2. No environment surprises. The local arc-agi PyPI package hosts the same game engine the Kaggle gateway runs. If it works locally, it works on Kaggle.
  3. Your code stays in git. Notebooks are awful for diffs and code review. Your real work lives in agent/my_agent.py; the notebook is an auto-generated deployment artifact.

​
Project layout

.
├── agent/
│   └── my_agent.py             ★ The file you edit
├── scripts/
│   ├── play_local.py           Runs your agent against real games
│   ├── build_notebook.py       Packages your agent into a Kaggle notebook
│   └── slim_framework.py       Trims framework deps so install is light
├── notebooks/
│   ├── kernel-metadata.json    Edit once: your Kaggle username
│   └── submission.ipynb        Auto-generated, never edit by hand
├── vendor/                     Cloned framework (gitignored)
├── .venv/                      Python 3.12 venv (gitignored)
├── .kaggle/                    Your project-local Kaggle token (gitignored)
└── Makefile

​
Troubleshooting

make setup fails: python3.12: command not found. Install Python 3.12; the arc-agi package requires it. macOS: brew install python@3.12. make submit says “edit kernel-metadata.json”. You haven’t replaced REPLACE_WITH_YOUR_USERNAME in notebooks/kernel-metadata.json yet. make submit says 401 Unauthorized. Your Kaggle token is missing or invalid. Generate a fresh one from your Kaggle Settings page and overwrite .kaggle/access_token. make play-local says “Could not create environment”. Your machine couldn’t reach the ARC-AGI API to download the game source on first run. Check your internet, then try again. Once downloaded, games are cached in environment_files/ and you’re fully offline. My local score is 0.0. That’s expected for the random starter agent. Your job is to make it non-zero.

​
Where to go next

  • Read the rest of the ARC-AGI-3 docs to understand the benchmark.
  • Run make pull-sample to study Kaggle’s reference agent.
  • Join the competition’s discussion forum for community Q&A.