All Versions
3
Latest Version
Avg Release Cycle
3 days
Latest Release
188 days ago

Changelog History

  • v1.1.1 Changes

    December 04, 2025

    🚀 v1.1.1 — Bug Fix Release

    🐛 Bug Fixes

    • 🛠 Fixed an issue where guesses that previously returned a WAIT (throttle) response were incorrectly treated as permanent duplicates after the cooldown TTL expired.
      Now, WAIT responses are ignored during duplicate detection once the throttle window has passed, allowing the guess to be properly evaluated.
      Thanks @tanzimfh for the great catch and contribution!

    • Improved cache semantics so only guesses with real evaluations (TOO_LOW, TOO_HIGH, INCORRECT, CORRECT, COMPLETED) are treated as duplicates.

    Notes

    • No breaking changes.
    • 🚀 This is a pure bug-fix release and is a drop-in upgrade from v1.1.0.
    • ⚡️ If you encountered the “blocked due to repeated guess” issue, updating to v1.1.1 resolves it.

  • v1.1.0 Changes

    December 01, 2025

    elf v1.1.0

    Small improvements and refinements to make elf more reliable and user friendly during Advent of Code.

    👌 Improvements

    👉 User-Agent Handling (thanks @NotTheEconomist 🎅)

    • Cleaned up the internal User-Agent validation logic.
    • Sanitizes newline and whitespace characters before validation.
    • 👉 Improves warnings and error paths when AOC_USER_AGENT is missing or invalid.
    • Ensures elf always sends a correctly formatted, compliant User-Agent header.

    File Input Helpers

    • 👌 Improved read_input():

    📚 Documentation

    • ⚡️ Updated README to show how to save puzzle inputs to files.
    • 👉 Added a new section describing AOC_USER_AGENT and how to configure it.

    Happy coding, and good luck on this year's puzzles! 🎄

  • v1.0.0 Changes

    November 29, 2025

    🚀 🎄 v1.0.0 First Public Release

    What is elf

    elf is a fast and modern CLI and Python helper library for Advent of Code. It provides a clean interface for fetching inputs, submitting answers, viewing leaderboards, and tracking your progress. It includes:

    • Cached puzzle input fetching
    • 🚅 Safe answer submission with guardrails
    • 👍 Private leaderboard support with table, JSON, or Pydantic output
    • Star status and AoC++ badge display
    • Guess history viewer
    • 💻 Quick browser opening for puzzles or inputs
    • Both a CLI (elf) and a Python API (import elf)

    🚀 Why this release

    Advent of Code begins December 1. After years of refining a personal helper tool for my own solving, I am releasing elf publicly so that others can benefit. It is built for casual solvers, automation workflows, leaderboard racers, and those who want a clean and modern Python interface to AoC.

    Highlights

    • Input fetching with automatic caching
    • 🚅 Answer submission guardrails for safety and cooldown awareness
    • Private leaderboard access in table, JSON, or model form
    • Star calendar and status views
    • Guess history tracking
    • 👍 Cross platform support with minimal dependencies

    Installation

    Using uv (recommended):

    uv tool install elf

    Using pip:

    pip install elf

    Requirements

    • Python 3.11 or newer
    • AOC_SESSION environment variable set for most commands

    Quick Start

    # Fetch input for today or first availableelf input# Submit an answer elf answer 2025 1 1 12345# View a private leaderboard elf leaderboard 2025 1234567 --view-key\<VIEW_KEY\># Show your star status elf status# Open today's puzzle in the browser elf open

    Thanks

    Special thanks to Eric Wastl for creating Advent of Code and inspiring a global tradition each December.

    📦 Thank you to @solos for donating the elf package name on PyPI.