adventofcode

🎄 adventofcode

Your framework for solving Advent Of Code puzzles 🧩 and benchmarking solutions 🚀

• Project scaffolding with uv run adventofcode init.
• Assert and submit your solutions with uv run adventofcode run.
• Benchmark all your solutions with uv run adventofcode benchmark.
• No copy-pasting puzzle inputs or loading inputs from files.
• Submit the answer immediately when your code returns the result. 🏅

---

Table of Contents

• Setup
• Session cookie
• Run and submit your solution
• Benchmark all your solutions
• Using AoC class
• Happy solving 🎄
• Similar projects

Setup

uv init
uv add adventofcode
uv run adventofcode init

This will generate the scripts for each day:

.
├── 01.py
├── 02.py
├── 03.py
├── 04.py
├── 05.py
├── 06.py
├── 07.py
├── 08.py
├── 09.py
├── 10.py
├── 11.py
├── 12.py
├── main.py
├── pyproject.toml
├── README.md
└── uv.lock

1 directory, 16 files

All the generated Python files look like this:

"""🎄 Solution for Day 1 of Advent of Code 2025 🎄

Usage:

uv run adventofcode run 01.py
"""

inp = """your input"""
part1_asserts = [
    (inp, None),
]
part2_asserts = [
    (inp, None),
]


def part1(inp: str) -> str | int | None:
    return None


def part2(inp: str) -> str | int | None:
    return None

Session cookie

Before we can run these files we need to set up your session cookie. You can find the session cookie by going to [adventofcode.com] in your browser. Make sure you are logged in, then open your browser's developer tools and navigate to Application → Storage → Cookies. Look for the cookie named session and copy its value.

Then add the adventofcode.com session cookie value to your .env file:

# Set your Advent of Code session cookie below
# You can find it in your browser's developer tools after logging in to adventofcode.com.
# The name of the cookie is `session`.
AOC_SESSION="YOUR_SESSION_COOKIE_HERE"
AOC_YEAR=2025

or to your environment variables:

export AOC_SESSION="..."

Run and submit your solution

Implement your solution in part1 and part2 functions and run

uv run adventofcode run 01.py

This will:

• Run your day 1, part1 function with the inputs provided in the part1_asserts iterable and compare them with the expected values. If the function's return value doesn't match the expected answer, the command will stop. Hint: Each puzzle usually contains example input and an expected answer—these make for great asserts!
• If all the part1_asserts pass, part1 will be called with your puzzle input fetched from adventofcode.com using your session cookie.
• If part1 returns a non-None value for your puzzle input, that value will be submitted to adventofcode.com as your part 1 answer using your session cookie. All answer submissions are cached, so each unique answer will only be submitted once.
• If your answer was correct the same process repeats for part2.

Benchmark all your solutions

You can benchmark your solutions with

uv run adventofcode benchmark

This will run each day's solution and parse the timing results from the output. The results will be printed to the console as well as added to your README.md.

If you are in a hurry you can also benchmark a single day's solution with

uv run adventofcode benchmark 05.py

Example console output:

Example README:

Legend:

• 🟢 < 100ms
• 🟡 100ms - 1s
• 🔴 > 1s

Using AoC class

Alternatively, you can build your own workflow using the lower level AoC class

from adventofcode import AoC

aoc = AoC()  # defaults to current year and parses the day from the filename (e.g. 01.py will be day 1)

aoc.print_p1()  # prints the first part of the puzzle
inp = aoc.get_input()  # returns the input as a string
# solve the puzzle here
...
aoc.submit_p1("part 1 answer")  # submits the answer to the first part of the puzzle
aoc.print_p2()  # prints the second part of the puzzle
# solve the puzzle here
...
aoc.submit_p2("part 2 answer")  # submits the answer to the second part of the puzzle

Happy solving 🎄

Enjoy and have fun!

Similar projects

• elf