Advent of Code Plugin

A comprehensive OpenCode plugin for solving Advent of Code puzzles with AI assistance. Fetch puzzles, submit answers, track progress, and get help for programming challenges.

Setup

1. Get Session Token

1. Log into adventofcode.com
2. Open browser developer tools (F12)
3. Go to Application > Cookies
4. Copy the session cookie value

2. Configure Environment

Create a .env file:

AOC_SESSION_TOKEN=your_session_token_here
AOC_YEAR=2025  # Optional, defaults to current year
AOC_LEADERBOARD_ID=your_leaderboard_id  # Optional

3. Test Connection

npm run quickstart
# or
opencode run "test adventofcode connection"

Available Tools

Core Functions

• adventofcode-test-connection - Test plugin configuration and connectivity
• adventofcode-get-puzzle - Get puzzle description for a specific day
• adventofcode-get-input - Get puzzle input data
• adventofcode-submit-answer - Submit answers to puzzles
• adventofcode-list-puzzles - List all puzzles with completion status

Progress Tracking

• adventofcode-get-user-stats - Get your completion statistics
• adventofcode-get-leaderboard - View private leaderboard standings

Usage Examples

Daily Workflow

# Get today's puzzle
opencode run "get today's puzzle"

# Get puzzle input
opencode run "get puzzle input for day 5"

# Submit answer
opencode run "submit answer for day 5 part 1: 42"

Catch Up on Previous Days

# List unsolved puzzles
opencode run "list puzzles for 2025"

# Get specific puzzle
opencode run "get puzzle for day 3 2025"

# Check your stats
opencode run "get my user stats"

Leaderboard

# View leaderboard
opencode run "get my leaderboard"

# With specific ID
opencode run "get leaderboard 123456"

Example Queries

• "Get today's puzzle description"
• "What is the input for day 7?"
• "Submit 12345 as answer for day 2 part 1"
• "Show my progress for this year"
• "List all puzzles I haven't solved yet"
• "Get puzzle for day 15 from 2023"

Environment Variables

Required

• AOC_SESSION_TOKEN - Your Advent of Code session cookie

Optional

• AOC_YEAR - Default year (defaults to current year)
• AOC_LEADERBOARD_ID - Private leaderboard ID for quick access

Response Format

All tools return JSON responses:

{
  "success": true,
  "data": "...",
  "message": "Operation completed"
}

Error responses:

{
  "success": false,
  "error": "Error message",
  "details": { ... }
}

Rate Limiting

Be mindful of Advent of Code's rate limits:

• Don't submit answers too rapidly
• Cache puzzle inputs locally
• Respect the spirit of the competition

Troubleshooting

Session Token Issues

If you get authentication errors:

1. Log out and back into adventofcode.com
2. Get a fresh session token
3. Update your .env file

Puzzle Not Available

Puzzles unlock at midnight EST each day in December. You'll get errors for future days.

Wrong Answer Format

Answers must be submitted as strings, even if they're numbers. The plugin handles this conversion.

Development

This plugin uses the OpenPets SDK with proper schema validation and error handling. See the source code for implementation details.

Contributing

Feel free to submit issues or enhancement requests!