Chef Overflow: Agent API Reference

Build an AI agent to run your kitchen. Top scores earn automatic admission to Hack the 6ix 2026.

← Back to Game KitchenAPI v2.0.0

1. How the Game Works

Game Phases

2. Quick Start

1. Open index.html in Chrome (or another modern browser).
2. Open DevTools F12 → Console.
3. Paste one of the example agents from Section 8 (or the minimal snippet printed in the console banner). Register it with KitchenAPI.run(fn).
4. Click Start Game or call KitchenAPI.start().
5. Iterate: add chefs, more recipes, bussing logic, and rush handling.

3. API Reference

KitchenAPI.version

Type: string. Current value: "2.0.0".

KitchenAPI.run(fn)

Recommended entry point. Registers fn as your agent. It runs once per game frame and survives start() and restarts. Calling run() again replaces the previous agent, so re-pasting your script is always safe (no double-registration).

Signature: fn(state, api, tick), where state is a fresh getState() snapshot, api is KitchenAPI, and tick is { dt, time }. Exceptions thrown inside fn are caught and logged as "Agent error:" — the run continues.

Returns: undefined.

KitchenAPI.run((s, api) => {
  if (!s.running || s.paused) return;
  // your logic here
});
KitchenAPI.start();

KitchenAPI.stop()

Unregisters the agent set by run(). Does not stop the game.

Returns: undefined.

KitchenAPI.plan(fn, opts)

Canonical LLM entry point. Registers an async planner that runs on a cadence (default every 1000ms, clamped 100–60000ms) independent of the game's tick loop. The planner's return value is stored as the current policy and exposed on state.policy and via KitchenAPI.getPolicy(). Re-entrancy is guarded — if a planner call takes longer than the interval, subsequent ticks are skipped rather than queued.

Signature: fn(state, api) → Promise<policy>. Exceptions are caught and logged; the last good policy is preserved on error.

Use plan() together with run() for the two-tier pattern: a slow async planner sets policy, a fast sync executor dispatches commands against it. This is the recommended shape for any agent whose decision step takes longer than a frame (LLMs, MILP solvers, search-based planners).

KitchenAPI.plan(async (s) => {
  // Slow side: call an LLM, solve an LP, whatever takes >16ms.
  // Return any object — it becomes state.policy.
  const urgent = [...s.orders].sort((a, b) => a.timeLeft - b.timeLeft)[0];
  return { focusDish: urgent?.dish || null };
}, { everyMs: 2000 });

KitchenAPI.run((s, api) => {
  // Fast side: dispatch against the current policy.
  if (!s.running || s.paused || !s.policy) return;
  // ...act on s.policy.focusDish with the same per-tick guards as before.
});

KitchenAPI.unplan()

Unregisters the planner. Clears the current policy. Does not affect the run() agent.

KitchenAPI.getPolicy()

Returns the latest value the planner returned (or null if no planner is registered or it hasn't resolved yet).

KitchenAPI.clearListeners()

Removes all event listeners registered via on() / onTick() / etc. The run() agent is re-attached automatically. Useful to reset raw listeners without restarting.

Returns: undefined.

KitchenAPI.start()

Starts or restarts the game. Resets stations, chefs, orders, and score. Clears raw event listeners (those registered with onTick, on, etc.), so re-register them after each start(), or use KitchenAPI.run() instead, which survives restarts automatically.

Returns: undefined.

KitchenAPI.togglePause()

Toggles the pause state. Syncs with the in-game Pause button.

Returns: undefined.

KitchenAPI.command(chefId, stationId)

Signature: (chefId: number, stationId: string) → { success: boolean, error?: string }

Queues pathfinding to a walkable tile adjacent to the target station, then triggers the same interaction as a mouse click. Fails if: game not running or paused, invalid chef id, chef is busy, unknown station id, no adjacent walkable tile, or A* finds no path.

Chef IDs: 0–4. Station IDs: strings like 'bin_3', 'stove_0', 'reception_2', see Section 4.

const r = KitchenAPI.command(0, 'plating_0');
if (!r.success) console.error(r.error);

KitchenAPI.boost(chefId)

Returns: { success: boolean, error?: string }. Applies a 3.5 s movement speed boost with a 12 s cooldown. Same as pressing B in-game.

KitchenAPI.selectChef(chefId)

Visual selection only (highlights chef in UI). Does not move the chef.

Returns: undefined.

KitchenAPI.getState()

Returns a plain snapshot of the entire game state. Ingredient objects are { ingredient, state }. Plates are { type: 'plate', items: [...] }. The run ends when failedOrders >= maxFailedOrders (currently 3).

Reception order when present: { id, dish, timeLeft, components }. Stove ready / burnt mirror the UI progress thresholds.

KitchenAPI.getRecipes()

Returns: Array<{ name, icon, difficulty, components }>, static recipe metadata without internal step strings. icon is a short string code (e.g. "STK" for Steak).

Event Registration

Each method returns an unsubscribe function: const off = KitchenAPI.onTick(fn); off();

4. Station ID Reference

5. Recipes

6. Game Mechanics for Agents

• Chefs block each other — no two chefs on the same tile; pathfinding may fail if every adjacent tile is occupied.
• One hold slot — a chef holds either one ingredient (with state) or one plate (bag of ingredients). No stacking.
• command() is asynchronous — it sets the chef's path. Wait until !chef.busy && !chef.hasPath before issuing the next command for that chef.
• Busy during processing — chopping and cooking both set busy = true. Don't stack commands on a busy chef.
• Stoves cook unattended — food left on a stove keeps cooking and can burn; send someone back to collect it in time.
• Plating is infinite — no plate inventory to manage. A held plate exists whenever you pick up from a plating area that has items.
• Delivery matching is exact — component count and every (ingredient, state) pair must match; extras cause a failed delivery.
• Wrong delivery — the plate is discarded and the streak resets to 0.
• VIP orders — shorter timer, 1.5× score (marked ★ in the UI).
• Streak multiplier — +5% per consecutive correct delivery, capped at 2× by streak 20; any wrong delivery or expiry resets it.
• Rush mode — periodic spawn-rate spike; check state.rush.active to react.
• Rush bursts — when rush activates, up to 3 orders spawn simultaneously (clamped to free reception stands), then sustained pressure continues at a milder rate. Subscribe onRushBurst or watch for back-to-back onOrderSpawned events to react in time.
• Lookahead — state.upcomingOrders previews the next 3 dishes before they go live, each with an estimated etaSeconds. The dishes are locked in (no re-roll on consumption), but ETAs are estimates and will shorten dramatically when rush triggers.
• Commitment cost — redirecting a chef mid-route (issuing command() while the chef still has ≥3 tiles of path to a different target) costs a 1.5s stall. Idempotent re-issues (same target) and commands from idle are free. Check chef.stall before issuing new commands. Applies equally to human clicks and agent commands.
• Planner channel — register an async planner with KitchenAPI.plan(asyncFn, { everyMs: 1000 }). The planner runs independently of the tick loop; its return value is exposed on state.policy for a fast run() executor to dispatch against. This is how to integrate an LLM without starving the game loop.

7. Agent Architecture Tips

• Role split — assign each chef a dedicated role (cook, chopper, plater/deliverer). One role per chef keeps logic simple.
• Serve the most urgent order first — sort by order.timeLeft.
• Spread work across plating areas — plating_0..3 are independent buffers. Use one per recipe-in-progress to avoid mixing ingredients from different orders.
• Guard every command() with running && !paused && !chef.busy && !chef.hasPath to avoid error spam.
• Pre-route on onOrderSpawned rather than polling each tick to cut latency.
• Trash burnt items — check stove.burnt and clear it promptly.
• Pre-stage on upcomingOrders — if a Pizza is 8 seconds out, start cooking dough now. Reactive agents that only react to onOrderSpawned waste the cook/chop window.
• On rush activation, parallelize cooks across all 3 stoves — sequential service against a 3-order burst will leave at least one order to expire. Use onRushBurst to trigger your batch path.
• Commit your plans — once a chef is en route to a station, only redirect if the new destination is strictly better than completing the current one. Each redirect costs 1.5s; two stalls per chef per minute is a meaningful score drag in endurance.
• Two-tier pattern for LLMs (and slow planners) — use KitchenAPI.plan() for the decision step (set roles, assign chefs to orders, batch upcoming pizzas) and KitchenAPI.run() for the dispatch step (cheap per-tick guards + command()). Don't await inside run() — the tick loop will block.

8. Example Agents

These are teaching examples, not optimal solutions. They omit multi-recipe routing, full bussing, boost timing, and rush handling.

Example 1: Single-chef steak bot

Bin → stove → plating area → reception. Plating areas are infinite, so picking up from one with cooked meat on it produces a held plate containing that meat.

KitchenAPI.run((s, api) => {
  if (!s.running || s.paused) return;
  const c = s.chefs[0];
  if (c.busy || c.hasPath) return;
  const steak = s.orders.find(o => o.dish === 'Steak');
  if (!steak) return;

  const h = c.holding;
  const platItems = s.stations.platingAreas[0].items || [];
  const meatReady = platItems.some(i => i.ingredient === 'meat' && i.state === 'cooked');

  if (!h) { api.command(0, meatReady ? 'plating_0' : 'bin_3'); return; }
  if (h.ingredient === 'meat' && h.state === 'raw')    { api.command(0, 'stove_0');   return; }
  if (h.ingredient === 'meat' && h.state === 'cooked') { api.command(0, 'plating_0'); return; }
  if (h.type === 'plate') { api.command(0, steak.standId); }
});

Example 2: Simple multi-chef coordinator

Chef 0 cooks meat; Chef 1 chops lettuce for Salad; Chef 2 plates and delivers the most urgent available order.

KitchenAPI.run((s, api) => {
  if (!s.running || s.paused) return;
  const go = (id, station) => {
    const c = s.chefs[id];
    if (c && !c.busy && !c.hasPath) api.command(id, station);
  };

  // Chef 0: cycle meat through stove → plating_0
  const c0 = s.chefs[0];
  if (!c0.busy && !c0.hasPath) {
    const h = c0.holding;
    if (!h) go(0, 'bin_3');
    else if (h.ingredient === 'meat' && h.state === 'raw')    go(0, 'stove_0');
    else if (h.ingredient === 'meat' && h.state === 'cooked') go(0, 'plating_0');
  }

  // Chef 1: chop lettuce whenever a Salad order exists
  const c1 = s.chefs[1];
  if (!c1.busy && !c1.hasPath && s.orders.some(o => o.dish === 'Salad')) {
    const h = c1.holding;
    if (!h) go(1, 'bin_1');
    else if (h.ingredient === 'lettuce' && h.state === 'raw')     go(1, 'cutting_0');
    else if (h.ingredient === 'lettuce' && h.state === 'chopped') go(1, 'plating_1');
  }

  // Chef 2: pick up the prepared items from plating_1 → deliver most urgent order
  const c2 = s.chefs[2];
  if (!c2 || c2.busy || c2.hasPath) return;
  const urgent = [...s.orders].sort((a, b) => a.timeLeft - b.timeLeft)[0];
  if (!urgent) return;
  const h2 = c2.holding;
  if (!h2)                                          { go(2, 'plating_1');     return; }
  if (h2.type === 'plate' &&  h2.items?.length > 0) { go(2, urgent.standId);  return; }
});

Example 3: Lookahead pre-stager (beats Example 2)

Uses upcomingOrders to start cooking before the order is live. When a Pizza is forecast within 10 seconds, Chef 0 picks up dough and stoves it now — so the dough is already cooked by the time the order spawns. The same pattern generalizes to any cook-bound recipe.

KitchenAPI.run((s, api) => {
  if (!s.running || s.paused) return;
  const c = s.chefs[0];
  if (c.busy || c.hasPath) return;

  // Live work wins over speculative work.
  const livePizza = s.orders.find(o => o.dish === 'Pizza' || o.dish === 'Supreme Pizza');
  const soonPizza = s.upcomingOrders.find(u =>
    (u.dish === 'Pizza' || u.dish === 'Supreme Pizza') && u.etaSeconds < 10
  );
  const want = livePizza || soonPizza;
  if (!want) return;

  const h = c.holding;
  const platItems = s.stations.platingAreas[0].items || [];
  const doughReady = platItems.some(i => i.ingredient === 'dough' && i.state === 'cooked');

  if (!h) { api.command(0, doughReady ? 'plating_0' : 'bin_4'); return; }
  if (h.ingredient === 'dough' && h.state === 'raw')    { api.command(0, 'stove_0');   return; }
  if (h.ingredient === 'dough' && h.state === 'cooked') { api.command(0, 'plating_0'); return; }
});

Example 4: LLM planner + executor scaffold

The canonical shape for any agent whose decision step is slower than a frame. The planner runs every 2 seconds (swap in fetch() to your model of choice); the executor runs every tick and just dispatches against the latest policy. The game loop never blocks on the LLM.

// Replace this with a real model call to Anthropic / OpenAI / your backend.
async function callLLM(state) {
  // ... await fetch('/api/plan', { method: 'POST', body: JSON.stringify(state) })
  // For this skeleton, just pick the most urgent dish.
  const urgent = [...state.orders].sort((a, b) => a.timeLeft - b.timeLeft)[0];
  return { assignments: { 0: urgent?.dish || null } };
}

KitchenAPI.plan(async (s) => await callLLM(s), { everyMs: 2000 });

KitchenAPI.run((s, api) => {
  if (!s.running || s.paused || !s.policy) return;
  const dish = s.policy.assignments?.[0];
  if (!dish) return;
  const order = s.orders.find(o => o.dish === dish);
  if (!order) return;
  const c = s.chefs[0];
  if (c.busy || c.hasPath || c.stall > 0) return;
  // ... your per-recipe dispatch logic here, e.g. for Steak:
  if (dish === 'Steak') {
    const h = c.holding;
    if (!h) api.command(0, 'bin_3');
    else if (h.ingredient === 'meat' && h.state === 'raw')    api.command(0, 'stove_0');
    else if (h.ingredient === 'meat' && h.state === 'cooked') api.command(0, 'plating_0');
    else if (h.type === 'plate') api.command(0, order.standId);
  }
});