An online Advent calendar
An Advent calendar as a website: a puzzle and a clue every day, until the gift is revealed by scratching off the last door.
We wanted to surprise a family we are friends with at Christmas with a trip together, but not simply hand over a voucher. So I built an Advent calendar as a website: a door opens every day, with a little puzzle and a clue behind each one. Bit by bit, it becomes clear what it is. At the last door, the secret is revealed by scratching it off.
Of course, you can personalise everything about it, whether you want to tell a story with each door that looks back over the year or build little games. It is about a kind gesture and making others happy. What matters here is not how the code was made, but the thought that goes into what will make someone else happy.

Demo calendar with made-up content: the overview on a phone, open doors in red.
In our case, it was a trip together with an overnight stay, so we wanted to give clues over the course of the calendar about the length, the place and what you can do there. We are also meeting as early as 19 December, so there are only 19 doors.
This is an example of what I mean by Power of Agentic Software.
These things also mattered to me:
- The children read for themselves. Short sentences, big buttons, everything playable on a phone and tablet.
- No tracking. I cannot see who opened what or when. Progress is stored only in the family’s browser.
The games
Eight types of game, spread over 19 days.
| Game | How it works |
|---|---|
| Hidden objects | Things are hidden in a drawn scene, partly concealed behind others. When you swipe and tilt, the layers shift slightly, as in 3D. |
| Memory | Find pairs, sometimes with symbols, sometimes with photos. |
| Quiz | Two or three questions with answers to tap, each with a short explanation. |
| Maze | A character finds the way to the goal, sometimes on a kind of map, sometimes with obstacles that move on with every step. |
| Zoom | A photo, zoomed in very close: what is it? If you are stuck, zoom out. |
| Photo puzzle | Put a jumbled photo back together by swapping the pieces. |
| Torch | A dark scene: shine a light around with your finger and look for what is hiding in it. |
| Scratch card | On the last day, the big secret is revealed by scratching it off. |

Hidden objects in 3D: the eggs are partly behind flowers, a pot, a bench and grass. Two out of five have been found.

Memory: two cards turned over, not a pair.

Maze in the style of a map: use the arrows to reach the goal.
How it works technically
The project itself is super simple, but when you tell Claude about it, it does not do things by halves: it does them 100% correctly. And this is what you end up with:
The hardest thing about a digital Advent calendar is not the game, but the secret. A normal website sends everything to the browser at once, and anyone who looks at the source code already knows the ending on 1 December.
That is why the calendar is split into two parts:
- The interface is public: HTML, CSS, JavaScript and the general game modules, without a single clue. A small checking script raises the alarm if a word in this part gives anything away.
- The doors live on the server. A small server function checks the access key and the date (in the recipients’ time zone) and returns exactly the doors that are already open. The door for the 12th does not exist for the browser until the 12th.
- The access key is in the link, after the #. This part of the address is not sent to servers and does not end up in any log. The page remembers the key and removes it from the address bar.
- Test access with its own key opens all the doors and lets me simulate any day. It is separate from the family’s access, including saved progress.
- Photos have random filenames, so no filename gives away the secret.
- No build step, no library: plain HTML and JavaScript that you can still open in ten years.
I did not build this by hand. I described what I wanted, and an AI agent (Claude with Codex) planned, coded and tested; I checked, clicked through and gave feedback. The instructions you can give an agent to build something like this yourself are below.
Where to host it?
- No server? Cloudflare Pages. Free for a project like this, including the small server functions and HTTPS. Connect a GitHub repository, and every change is online a few minutes later.
- Several projects, less technical work? eigava.de. There, your own AI assistant builds the app, and eigava takes care of running it, updates and backups, hosted in Germany.
Example: instructions for an AI agent
Put this file in an empty folder as INSTRUCTIONS.md and tell the agent: “Read INSTRUCTIONS.md and implement it.” Fill in the placeholders in <…> first.
# Brief: Digital Advent calendar
Build an Advent calendar as a website for <recipients, e.g. “our friends' family,
two children, aged 7 and 9”>. It reveals <the gift> day by day. The secret is only revealed at the last door.
## Scope
- Period: 1 December to <last day>, so <number> doors. Time zone: <Europe/Berlin>.
- Language: <German>. The children read for themselves: short sentences, large text, big buttons.
- Devices: phone and tablet first, computer too.
- Missed doors stay open and can be caught up on.
- No tracking, no cookies, no external fonts or scripts.
- No build step and no library: plain HTML, CSS and JavaScript.
## Keeping the secret (most important)
- Everything that reaches the browser is public. There must be no clue to the secret
there, including in filenames, comments or image metadata.
- The door content lives outside the public folder. A server function
(Cloudflare Pages Functions) only returns a door from its day onwards, checking
a secret access key (environment variable `ADVENT_ACCESS_KEY`).
- The key arrives with the link after the `#` and is then removed from the address
bar.
- Write a test that searches the public folder for forbidden words
(list: <anything that gives away the gift>), and run it with every test.
- Images get random filenames; metadata is removed.
## Content
First plan how the suspense builds across all the doors and show me before you build:
one puzzle, one clue and one keyword per day. Order of clues: <from general to specific>.
Research facts with sources; do not make anything up.
Game types (reusable modules, content as data):
Hidden objects, Memory, quiz, maze, zoomed image, photo puzzle, torch, scratch card.
## Testing
- Test access with its own key (`ADVENT_TEST_KEY`) opens all the doors and lets you
simulate a day. Without this key, it is disabled. Its saved progress is
separate from the family's saved progress.
- Automated tests for: date boundaries (midnight in the time zone), wrong key,
future doors, every puzzle is solvable, the word list.
- Play through each door once in the browser, at phone size, and send me screenshots.
## Publishing
- Hosting: Cloudflare Pages with Git integration, output folder = the public folder,
no build command. Set secrets in the Pages project, never in the repository.
- The repository stays private until the calendar is over.
- At the end, write down for me: the link for the family, the test link, and what I still
need to click.