Meal OS is a personal, file-backed meal planning system for a household. It uses structured Markdown, YAML, grocery flyers, and receipt history to maintain a recipe rotation, detect sale opportunities, generate weekly meal plans, and produce aisle-grouped shopping lists.
This repository is designed for two audiences:
- Users who want a repeatable weekly planning workflow with AI assistance.
- Developers who want to maintain or extend the Claude skill system behind that workflow.
- Stores recipes as individual Markdown files in
data/recipes/. - Parses weekly store flyers into normalized sale data in
data/flyers/. - Builds weekly meal plans in
data/meal-plans/. - Generates shopping lists in
data/shopping-lists/. - Tracks receipt-derived price history in
data/receipts/. - Normalizes ingredients through
data/canonical-ingredients.yaml.
All project state lives in the repository. There is no database, backend service, or web UI.
Each household customizes Meal OS through data/config.yaml, which controls:
- Diet style (e.g., mediterranean, paleo, vegetarian)
- Excluded ingredients (allergies or preferences)
- Grocery stores (for flyer parsing and sale comparisons)
- Rotation and threshold targets
Running /meal-setup creates this file interactively. See samples/config.sample.yaml for the format.
.
├── .claude/skills/ # Claude skill definitions for setup, recipe intake, flyers, planning, receipts
├── data/ # Local household data (gitignored)
│ ├── config.yaml # Household preferences (diet, stores, thresholds)
│ ├── canonical-ingredients.yaml
│ ├── recipes/ # One recipe per Markdown file
│ ├── flyers/ # Parsed store flyers
│ ├── meal-plans/ # Weekly meal plans
│ ├── shopping-lists/ # Generated shopping lists
│ └── receipts/ # Receipt images, aliases, and price history
├── samples/ # Sanitized examples (tracked in git)
│ ├── recipes/
│ ├── flyers/
│ ├── meal-plans/
│ ├── shopping-lists/
│ └── receipts/
├── docs/plans/ # Design and implementation planning docs
└── CLAUDE.md # Project operating rules and directory contract
git clone <your-fork-or-repo-url>
cd meals-agentThis project is built around the skills in ./.claude/skills. The intended interface is Claude Code or a comparable tool that can read and execute repository-local skill instructions.
Run:
/meal-setup
This creates the data/ directory structure, asks a few setup questions (diet, stores, excluded ingredients), and seeds the config and canonical ingredient files.
Paste recipe text and run:
/meal-add
Recipes are saved as Markdown files in data/recipes/.
Use pasted flyer text or a PDF and run:
/meal-flyer
Parsed flyers are written to data/flyers/ and can include likely loss leaders.
Drop receipt images into data/receipts/images/ or pass them directly, then run:
/meal-receipt
This updates the price ledger used for cost estimates and sale detection.
All household data lives in data/ (gitignored). Sanitized examples are in samples/.
Run:
/meal-plan
Outputs:
- Meal plan in
data/meal-plans/ - Shopping list in
data/shopping-lists/
/meal-setup
/meal-add
/meal-flyer
/meal-receipt
/meal-plan
Examples:
/meal-plan 4 meals
/meal-plan skip salmon
/meal-plan include lemon-garlic chicken
/meal-receipt
At a high level, Meal OS:
- Reads recipe metadata from
data/recipes/*.md. - Reads current flyer data from
data/flyers/*.md. - Reads recent price history from
data/receipts/price-history.yamlwhen available. - Scores recipes using rating, ingredient overlap, on-sale ingredients, likely loss leaders, cost signals, and repetition penalties.
- Writes a plan and a shopping list back into the repository.
Because the workflow is file-backed, every output is inspectable and easy to version in Git.
This is a docs-first automation repo, not a conventional application. Changes usually fall into one of these categories:
- Updating a skill in
./.claude/skills - Adjusting canonical ingredient data in
data/canonical-ingredients.yaml - Adding or refining recipe and flyer examples in
data/ - Writing design notes and implementation plans under
docs/plans
meal-setup: bootstrap the projectmeal-add: normalize and save recipesmeal-flyer: parse flyers and detect likely loss leadersmeal-receipt: OCR receipts and maintain price historymeal-plan: generate plans and shopping lists
- Keep data human-readable and Git-friendly.
- Prefer Markdown and YAML over introducing application state elsewhere.
- Preserve the contracts described in
CLAUDE.md. - When changing a skill, update the relevant planning or design docs if behavior changes materially.
- All household data lives in
data/(gitignored). Sanitized examples go insamples/.
- Does the change respect the user's
data/config.yamlsettings rather than hardcoding constraints? - Does it keep outputs deterministic enough to review in Git?
- Does it avoid breaking the existing directory and file naming conventions?
- Does it improve or preserve the user-facing confirmation and preview steps in each skill?
- Use focused pull requests with a clear scope: recipes, skills, or planning docs.
- Include before/after examples when changing a skill output format.
- Link related design notes in
docs/plansfrom your PR description. - Keep sample data sanitized if you add real receipts or purchase history.
The repository already contains:
- A seeded canonical ingredient list
- A recipe collection
- Weekly flyer and meal-plan examples
- Claude skills for setup, recipe intake, flyer parsing, receipt processing, and planning
The repo is usable now as a personal planning system and is also set up for iterative refinement through the planning docs.
- There is currently no standalone CLI, web app, or packaged release.
- Receipt images may contain sensitive information; review them before committing.
- Keep live receipt-derived data local where appropriate; use the sample ledger for documentation and sharing.