---
name: kitchenos
description: Connect to and use the person's kitchenOS account - the meal plan, recipes, what's in the pantry, fridge or freezer, the shopping list, and the people they cook for. Use for any cooking, meal-planning, pantry or grocery request.
---

# kitchenOS

kitchenOS is a household kitchen app: a meal plan, a recipe collection, stock (pantry, fridge, freezer), a shopping list, and the people the household cooks for. This file tells you, the assistant, how to connect to the person's kitchenOS account and how to use it well.

## Connect: choose one way

Use the first option that fits where you are running. Every option ends the same way: a kitchenOS window opens in the browser, the person signs in (password, emailed code or Google) and clicks **Allow this connection**. Never ask for their password yourself. If the `kitchenos` tools are already available, skip to "Using kitchenOS".

### Claude Code

```sh
claude plugin marketplace add payamrajabi/kitchenos-plugin
claude plugin install kitchenos@kitchenos
```

If either command fails, add the connector on its own instead: `claude mcp add --transport http --scope user kitchenos https://recipes-ui-henna.vercel.app/api/mcp`. Then in a session run `/mcp`, choose **kitchenos** and **Authenticate**.

### Codex

```sh
codex plugin marketplace add payamrajabi/kitchenos-plugin
```

Then install **kitchenOS** from Codex's plugin browser. If that fails, add the connector on its own instead: `codex mcp add kitchenos --url https://recipes-ui-henna.vercel.app/api/mcp`, then `codex mcp login kitchenos`.

### Claude on the web, desktop or phone

You can't add a connector yourself. Tell the person: Settings, then Connectors, then **Add custom connector**. Name it KitchenOS, paste `https://recipes-ui-henna.vercel.app/api/mcp`, choose **Add**, then **Connect** and **Allow**. In a new chat, turn KitchenOS on from the **+** menu.

### ChatGPT

Tell the person: on chatgpt.com, Settings, then Apps, then Advanced settings, and turn on **Developer mode**. Then **Create app**: name KitchenOS, MCP server URL `https://recipes-ui-henna.vercel.app/api/mcp`, authentication **OAuth** with the client ID and secret left blank. Tick the acknowledgement, choose **Create**, then **Allow**.

### Any other MCP client

Add a remote MCP server (Streamable HTTP) at `https://recipes-ui-henna.vercel.app/api/mcp`. It uses OAuth with discovery and dynamic client registration. kitchenOS approves only Claude, ChatGPT and apps on the person's own computer (callbacks to localhost), so a hosted assistant other than those will be refused at the Allow step.

### Keep this file

If you installed the plugin, it already includes these instructions as a skill. Otherwise, if your client has a skills folder (for example `~/.claude/skills/` or `~/.agents/skills/`), save this file there as `kitchenos/SKILL.md` so you know how to use kitchenOS next time.

### Then start

Don't stop after setup. If the person already asked for something, do it. Otherwise ask what they'd like: plan the week, what's for dinner, a stocktake, or the shopping list.

## Using kitchenOS

Start every conversation with `get_kitchen_snapshot`. It gives today's date in the household's time zone, the plan for today and the next six days, what is in stock, low, out or expiring soon, the recipe collection with ids, and the shopping list. The connector also sends its own ground rules when it connects; where they differ from this file, follow the connector.

### Ground rules

- Only use ids that came from a tool result or the snapshot. Never guess an id.
- When several items are named at once (a stocktake, a shopping haul), make one `update_stock` call with all of them. Report the count and only the items that failed or were ambiguous.
- If a name could mean several things, ask one short question with the options.
- Confirm before `delete_recipe`, and before removing more than three planned meals at once. Make other changes directly; the app you're running in asks the person to approve them anyway.
- Before planning meals, check `get_household` for allergies and diets. Never suggest a dish a member is allergic to; if the person asks for one, say so and ask before adding it.
- Household goods (toilet paper, dish soap, cat litter) belong in stock and on the shopping list only, never in a recipe, a meal or the plan.
- Stock changes go to the household's default kitchen unless the person names another ("we're out of eggs at the cabin"). Fridge, Freezer, Pantry and Counter are shelves inside a kitchen, not kitchens.
- Say what happened in plain words. Never show ids, JSON or tool names. Give single rounded figures ("about 2 hours"), not ranges.

### Common jobs

**Plan the week.** Read `get_household`, then draft with `suggest_week_plan`, using up what expires soon. Show one short line per day with the reason and what needs buying. Redraft with the agreed meals in `locked`. On a clear yes, write it with `apply_week_plan`, then offer `add_plan_to_shopping_list` for the same days.

**What's for dinner.** `suggest_meals` for today's dinner with `only_in_stock` true first. Offer one or two by name with a short reason and what's missing. Add the chosen one with `add_plan_meal`. Keep rejected recipes in `exclude_recipe_ids`.

**Stocktake.** For a photo of a fridge, pantry, freezer or receipt, read it yourself and list what you see. Ask about anything unclear, then make one `update_stock` call. "We're out of milk" is status out, "running low on eggs" is low, "just bought coffee" is stocked (added if new), "keep pickles stocked" is staple true.

**Shopping.** `get_shopping_list` shows what the plan needs that isn't in stock, staples that are low or out, and extras. Group it by aisle. Tick items off with `check_off_shopping_item` as they're bought (they go into stock). Add with `add_shopping_extra`; remove an extra with `remove_shopping_extra`.

**Recipes.** Find with `search_recipes` and read with `get_recipe` before answering about ingredients or steps. Import a link or pasted text with `import_recipe`, create from a description with `create_recipe`, and edit the person's own recipes with `update_recipe`, `update_recipe_ingredient` and `update_recipe_step`. Save a community recipe with `save_recipe`.

**Remember the household.** When the person states a lasting fact (an allergy, a diet, a food someone loves or refuses, a routine), save it with `remember_household_fact`. `get_household_memory` reads what's remembered; `forget_household_fact` removes one. Today's rundown is `get_brief`.

### Retries

Changes are not protected against repeats. If a change times out, check first (`get_plan`, `get_shopping_list` or `search_recipes`) before trying again, or it may be added twice. A recipe import can take a few minutes and may finish even when the call reports a timeout.
