Aegis Kitchen Coach Documentation

Aegis Kitchen Coach helps you decide what to cook, plans your week, keeps your recipe library, makes the shopping list and hands the recipe to your phone for step-by-step cooking. Everything runs on your computer: the language model runs locally through Ollama, and your recipes, plans, household profiles and photos are stored in a local SQLite file. There is no account and no cloud.

Installation & Setup

Aegis Kitchen Coach is available for Linux as a Snap or as a Debian/Ubuntu .deb package from the download page.

Snap

Install from the Snap Store, or in a terminal (the Snap is currently on the beta channel):

sudo snap install aegiskitchencoach --beta

To import and export recipes and PDFs on USB drives, connect this interface once:

sudo snap connect aegiskitchencoach:removable-media

With the Snap, your data lives under ~/snap/aegiskitchencoach/current/.aegiskitchencoach/.

Debian / Ubuntu (.deb)

Download the package, then install it with apt so its dependencies are pulled in:

cd ~/Downloads
sudo apt install ./aegiskitchencoach_*_amd64.deb

The app appears in your applications menu, and as aegiskitchencoach on the command line. The package bundles its own Python environment.

Local AI (Ollama)

The AI Assistant, AI recipe drafts and the Ask Aegis panel use a local model through Ollama, installed separately — see our Ollama setup guide. Then pull the default model:

ollama pull qwen2.5:7b

It runs on an 8 GB laptop without a GPU. Two optional models add more:

ollama pull nomic-embed-text   # smart search by meaning
ollama pull qwen2.5vl:7b       # recognize ingredients in a photo (or llava:7b)

The app checks for Ollama on first start and explains anything that is missing; models are chosen in Configure.

The Pages

The Ask Aegis panel on the right answers questions — substitutes, safe temperatures, "make it serve 6" — and proposes changes you accept or reject. The Research menu has short guides to the world cuisines in the library and to kitchen basics.

Your Household

Profiles come first: every suggestion, plan and AI answer is filtered by the people you cook for. Add them in Settings → Household.

How the checks work

Allergies and diets are hard rules enforced by code. Each ingredient in the bundled table carries allergen and diet tags, and every ingredient line is also scanned for allergen words ("almond", "shrimp", "cheese"), so an ingredient the table doesn't know still trips the check. A recipe with a conflict is marked Not safe for everyone and left out of suggestions and plans; an AI draft with a conflict is never shown.

The AI Assistant

Tell Aegis about the meal and it asks one thing at a time: who's eating and how many, the occasion, the time you have, what you feel like (or a cuisine), ingredients to use up, equipment, and effort or budget. Say several things at once — "a quick vegetarian curry for four tonight" — and it skips what it already knows.

The meal brief

The card on the right shows what was recorded and where it came from: you said, inferred (Aegis reads these back to confirm) or default. Click any value to change it, and tick who's eating under the brief.

Suggestions

Suggest dishes gives three: recipes from your library first, ranked by fit, then new ones drafted by the AI and marked NEW. Every suggestion has passed the allergen and diet check for the people eating. From a suggestion: Cook this, Add to plan, or Save to library for new ones.

Plan a Meal

Dinner is rarely one recipe. Suggest a meal picks a main that fits your time and is safe for your household, then a side and a salad that go with it: a matching cuisine, one starch on the plate, and kind to the one oven. Each card says why it was picked; Another swaps in the next best and + Add a dish adds a starter, dessert or second side.

Cooking it together

The Cooking order blends every dish's steps, worked back from serving everything at once: slow things start first and quick ones fit into the waiting. If two dishes need the oven at different temperatures, one is scheduled earlier and you're told to keep it warm. Cook this meal steps through that order with a timer for every dish, on screen or on your phone.

Shopping list for the meal merges every dish, and Add to this week's plan puts the whole meal on the next free dinner.

Cook With What I Have

For "dinner in 30 minutes" moments: pick the time you have (15, 30, 45 minutes or an hour) and how many are eating, confirm what's on hand — pantry items near their use-by date come first — and press Find recipes. Recipes are ranked by how much of their ingredient list you already have and whether they fit the time, with swaps from a bundled substitution table ("no shallots: use onion"). If nothing fits, Aegis can draft a recipe from what you have; it goes through the same checks as any other.

Let's cook with that (a photo)

Photograph your ingredients from a file or with your phone. A local vision model lists what it sees; correct the list, then search. The photo never leaves your computer and is deleted after use unless you keep it. Without a vision model, just type your items.

Recipes & Smart Search

The library opens with about a hundred recipes written for the app across twelve cuisines, plus everyday sides and salads. Pick a cuisine, then Meat, Poultry, Fish & seafood or Veggie, a mood (weeknight, comfort, party, make-ahead…), course, diet, time and difficulty.

Smart search

Type what you feel like: "something cozy and vegetarian for a rainy day", "Italian under 30 minutes". With Smart search ticked, a small embedding model in Ollama (nomic-embed-text) ranks the library by meaning; clear words like vegetarian or under 30 minutes also filter. Without it, search matches names, tags and ingredients word for word.

Editing, history and files

Ingredients are typed one per line as a cook writes them ("1 ½ cups chopped onion"); a preview shows how each line is read. Steps can carry markers for a timer ({timer 10 Pasta}), the oven ({oven 200}, °C), hands-off time ({wait}) or make-ahead work ({ahead}). Every save is a revision you can restore. Export as .aegisrecipe (optionally password-protected) or as schema.org Recipe JSON.

Importing Recipes

Library → Import from web page…: paste a recipe page's address. The app fetches that one page, with no cookies and no JavaScript. When the page embeds a schema.org Recipe (most recipe sites do), it is read by code with no AI; otherwise the local model copies the recipe out of the page text. A review screen shows the result beside the source, with problems flagged.

Paste recipe text… takes a recipe from an email or a cookbook. Every page fetch is listed in Settings → Privacy. Imported recipes are for your personal library: keep the source link, and don't republish other people's instructions.

Plan for the Week

The Week tab is a grid of days × breakfast, lunch, dinner and snacks. Drag a recipe into a slot or double-click to choose one; right-click for servings or a note ("leftovers", "eating out").

Rules and Plan my week

Write rules one per line: "fish once", "two vegetarian nights", "under 30 minutes Monday to Thursday". Plan my week asks Aegis to fill the empty dinners, choosing only from recipes the app has already cleared for your household and each day's time rule. Its picks appear in amber as proposals. Fill without AI does the same with code alone.

The variety guard warns when the same protein or cuisine repeats too often. Day and week nutrition totals per person sit under the grid. Send the week to the shopping list merges everything into one list.

Special Occasions

Start from a template — Thanksgiving, Christmas dinner, Easter lunch, birthday, dinner party, game day, potluck, summer barbecue or brunch — then set the serving time, the number of people and guest needs ("2 vegetarian cousins", "1 gluten-free"). Fill the menu picks a safe recipe for each course.

The timeline

Code schedules every step backwards from serving time. The dish that needs the oven longest gets its slot first; other oven dishes share it only at about the same temperature, or move into a free window (the turkey's rest is a good one). Long make-ahead work — thawing, marinating, chilling — moves to the days before. Turkey thawing and roasting times come from bundled USDA figures by weight. Print the timeline, or open it on your phone to tick tasks off.

Shopping & Pantry

Build a list from a recipe, a meal, the week's plan or an occasion. The same ingredient is merged across recipes with units normalized ("2 onions" and "1 cup chopped onion" become "3 yellow onions"). Pantry items and staples are ticked off for you; what's left is sorted by supermarket aisle, in your store's order if you set one.

On your phone

On my phone… shows a QR code for a page on your home Wi-Fi. The list is saved in the open browser tab, so it keeps working in the store, and ticks sync back when you're home. A second QR code holds the list as plain text, and the list prints as a PDF.

The pantry

Bought → pantry moves ticked items into a simple inventory by location (fridge, freezer, pantry, spice rack) with optional quantity and use-by date.

Cooking & Your Phone

The Cook page shows everything to gather first (scaled to your servings, with anything to start straight away, like heating the oven), then one step at a time with the ingredients it uses and a timer button. Several timers can run at once and keep running on every page. F11 opens full-screen cook mode with large text. At the end: stars, a note and a photo.

Cook on your phone

Cook on phone starts a small web server inside the app and shows a QR code. Scan it with the phone's camera and the page opens over your home Wi-Fi — no app to install, nothing on the internet. Swipe through big steps; timers run in the phone's browser and sound and vibrate when done; progress syncs back; and Add a photo sends a picture of the dish straight to your computer.

Printing

Four printable PDFs, on Letter or A4 (Settings), made on your computer and saved where you choose:

• Recipe card (Ctrl+P) — at the servings you choose, with nutrition, the household check and the cover photo.
• Weekly menu — the grid with each day's dishes and nutrition totals.
• Shopping list — by aisle, with tick boxes.
• Occasion — the menu, the timeline, the oven plan and food-safety notes.

Nutrition Estimates

Every recipe shows calories, protein, carbohydrate, fat, fiber, sugar and sodium per serving, computed by code: each ingredient line is weighed and multiplied by a bundled per-100 g table based on USDA FoodData Central. The model never quotes a nutrition number.

• An ingredient the table doesn't know is listed as not counted rather than silently counted as zero.
• Salt "to taste" isn't counted, so real sodium is higher. Oil "for frying" counts only the share food typically absorbs.
• These are estimates: brands, varieties and portions differ.

Cooking Safely

Food-safety figures in the app come from bundled USDA FSIS and FoodSafety.gov data, never from the model.

• Use a thermometer in the thickest part, away from bone.
• Thaw in the refrigerator — about 24 hours for every 4 to 5 pounds of turkey — never at room temperature.
• Refrigerate perishable food within 2 hours of cooking (1 hour above 90 °F / 32 °C), and eat leftovers within 3 to 4 days.
• Never leave hot oil unattended, and keep a lid nearby.

Your Data & Privacy

• No analytics, crash reporting, accounts or update checks.
• Recipes, plans, household profiles, pantry, lists and conversations are stored in ~/.aegiskitchencoach/, one SQLite file per profile, and are kept when the package is removed or updated. Photos are stored without GPS or other EXIF data.
• The model is reached only on your computer; a remote Ollama host is refused unless you allow it in Configure.
• Recipe import fetches exactly the page you paste, with no cookies. Each fetch is listed in Settings → Privacy and in logs/network.jsonl.
• The phone page is served from your computer over your home Wi-Fi, never through a relay, and loads nothing from the internet.
• Every prompt and reply to the local model is logged in logs/llm.jsonl; set AEGIS_LLM_LOG=0 to turn it off.
• Settings → Privacy deletes all chat history or wipes everything.

Beta & Licensing

Aegis Kitchen Coach is in Beta and free to use. There is no license charge during the Beta: every feature is available without paying anything.

The app is complete enough to cook with, and we are still improving it. Updating the app keeps your recipes, plans and history. You may find rough edges — please tell us about them.

In the future we may limit some features unless a one-time license is purchased. One-time means you pay once; it is not a subscription.

Troubleshooting

The AI doesn't answer

Check that Ollama is running (ollama serve) and that the models in Configure are installed (ollama pull qwen2.5:7b). On a slow computer, try qwen2.5:3b.

The phone can't open the page

The phone must be on the same Wi-Fi as your computer — not on mobile data or a guest network. A firewall may block the app; allow Aegis Kitchen Coach on private networks, or choose a fixed port in Settings and allow that port. Some routers isolate Wi-Fi devices from each other ("client isolation"); use full-screen cook mode (F11) instead.

An import comes out wrong

Some sites block apps or have no recipe data. Paste the recipe text instead, and use Edit before saving.

An ingredient isn't counted for nutrition

Rename the line to a common name ("chicken thighs" rather than a brand) or give it a weight.

Reporting a problem

Use Help → Contact Us in the app — it opens your email program with your message filled in, so you see exactly what is sent — or our contact page. Please leave out personal details we don't need.

Contact Support