Pick a real problem. Plan it with Timefold.

Ready-made model, or build your own with an AI agent

Ship an app people can use

One day, teams of two to five

The day

• 09:00 Briefing: problems, both build options, teams form
• 09:15 Hack: five hours to build your model and your app
• 13:15 Lunch is served, hacking continues
• 14:15 Demos and judging: five minutes per team, live
• 15:00 Close: winners announced

Somewhere near you…

A hospital struggles to plan its staff rotas fairly

A food bank works out who drives where

A volunteer group juggles too many people and too few time slots

These are all planning problems

Who builds what

Your data goes in.
The best plan comes out.

1. You describe the problem as JSON: what, to whom, which rules
2. Timefold searches: tries many plans, scores each, keeps the best
3. You get the plan back with a score, like 0hard/-12soft

Hard vs. soft

• HARD Never break. 0hard means every one holds.
• SOFT Preferences. Closer to 0soft is better.

What it looks like

POST /rotas
{
  "volunteers": [
    { "name": "Amira", "skills": ["driving"], "maxHours": 6 },
    { "name": "Tom",   "skills": ["packing"], "maxHours": 4 }
  ],
  "shifts": [
    { "id": "sat-09", "start": "09:00", "end": "12:00", "skill": "driving" },
    { "id": "sat-13", "start": "13:00", "end": "16:00", "skill": "packing" }
  ]
}

200 OK
{
  "assignments": [
    { "shift": "sat-09", "volunteer": "Amira" },
    { "shift": "sat-13", "volunteer": "Tom" }
  ],
  "score": "0hard/0soft"
}

Fair rotas for a care team or ward

• HARD Required skill on every shift
• HARD Minimum rest between shifts
• SOFT Spread nights and weekends fairly
• SOFT Respect preferred days off

Start with: A → Employee Shift Scheduling · B → employee scheduling quickstart

Food-rescue and grocery deliveries

• HARD Each stop inside its time window
• HARD Never exceed van capacity
• SOFT Minimize total driving time
• SOFT Chilled food on the shortest routes

Start with: A → Field Service Routing · B → vehicle routing quickstart

Your problem has rules a ready-made model can't express?

Build your own.

More problem ideas on the website

How teams form

1. At the briefing, pitch your problem in one or two sentences
2. People join the problem they care about most
3. Organizers balance teams that are too big or too small
4. Every team gets a problem, a name, and a table

What every project needs

1. Help people locally: a real planning problem in a local community
2. Teams of two to five, formed on the day
3. Use Timefold for the planning: ready-made or your own
4. AI agents are welcome, but you must understand your code

And

5. Open tools and data are fine. Credit them.
6. No real personal data. Names, addresses, health details: made-up or anonymized only.
7. Follow the code of conduct and privacy policy of The AI Collective.

Breaking the rules can mean disqualification. Teams get a chance to explain first.

Custom models can score highest on modeling the problem.

Get an API key

1. Sign up for a free trial at app.timefold.ai
2. Create an API key in the Platform
3. Keep it out of Git: environment variable or git-ignored file
4. Pick the model that fits your problem

Pick a model

• Field Service Routing
  Visits for people on the road
• Employee Shift Scheduling
  Shifts for staff and volunteers
• Pick-up and Delivery Routing
  Moving goods from A to B
• Task Scheduling
  Tasks for people over time

Stuck? Point your agent at docs.timefold.ai/llms.txt

Know what the model can and can't do

A ready-made model supports a fixed set of rules.

A rule you need isn't supported? Say so in your demo, or switch to option B.

Step 1: JDK 21 or higher and Maven

# macOS
brew install --cask temurin@21
brew install maven
# Windows
winget install EclipseAdoptium.Temurin.21.JDK
winget install Apache.Maven
# Ubuntu / Debian
sudo apt install openjdk-21-jdk maven
# Any OS, with SDKMAN
sdk install java <21.x-tem identifier from: sdk list java>
sdk install maven

java -version   # openjdk version "21.0.x" or higher
mvn -version    # Apache Maven 3.9.x, running on Java 21+

Step 2: connect the MCP server

Copy the server URL from prd.timefold.ai

# Claude Code
claude mcp add --transport http timefold-prd <MCP_SERVER_URL>

# Codex: ~/.codex/config.toml
[mcp_servers.timefold-prd]
url = "<MCP_SERVER_URL>"

Check: ask your agent "Which tools does the timefold-prd MCP server give you?"

Step 3: the license key

Download the hackathon license: timefold-license.pem

# Easiest: put it in your home directory
mv ~/Downloads/timefold-license.pem ~/timefold-license.pem

# Or point an environment variable at it
export TIMEFOLD_LICENSE_PATH=/absolute/path/to/timefold-license.pem
export TIMEFOLD_LICENSE="$(cat ./path/to/timefold-license.pem)"

Keep the name timefold-license.pem exactly, and don't commit it to your repository.

Step 4: start from a quickstart

• People assigned to shifts → Employee scheduling
• Drivers visiting stops → Vehicle routing
• Sessions in a room and slot → School timetabling or Meeting scheduling

git clone https://github.com/TimefoldAI/timefold-quickstarts.git
cd timefold-quickstarts/java/employee-scheduling
mvn quarkus:dev   # open http://localhost:8080

Half the score is the panel.
Half is the room.

Judges panel criteria

• 30% Community impact: a real, local problem; clear who benefits
• 30% Modeling the problem: sensible hard and soft constraints, feasible plan
• 20% Working solution: model and app work end to end, live, on realistic data
• 20% Demo: problem, solution and result clear in five minutes

Custom models can score highest on modeling

A well-configured ready-made model (A) can reach a three or four.

A five needs custom constraints for your community's specific rules (B), and a trade-off the model made that you can explain.

Audience vote

After the last demo, agree as a team on the three projects you'd most like to see used in your own community.

• First choice: 3 points
• Second choice: 2 points
• Third choice: 1 point

Ties: more judges points wins, then higher community impact.

Prizes

€500 in Amazon vouchers

Winners may be featured in The AI Collective's global newsletter: 300,000+ subscribers