AI-Powered Meal Planning Made Practical

meal-plan is a Python-based meal planning assistant that bridges artificial intelligence, grocery shopping APIs, and personal recipe management. It generates weekly meal plans tailored to your household, budget, and dietary preferences—then resolves ingredients against real Kroger inventory with live pricing and adds items directly to your cart. Built as an OpenClaw skill, it integrates seamlessly into AI-orchestrated workflows while remaining fully functional as a standalone tool.

Key Features

AI Recipe Generation: Claude creates personalized meal plans based on household size, weekly budget, dietary restrictions (PCOS, high-protein, vegan, etc.), and preferred meal counts.
Real-Time Pricing: Resolves recipe ingredients against Kroger's product catalog at your nearest store, showing actual prices before purchase.
Obsidian Integration: Saves recipes as markdown files with YAML frontmatter (tags, dates, servings, source), fully compatible with Obsidian properties and dataview queries.
Smart Cart Management: Adds resolved grocery items to your Kroger cart for pickup—never auto-checks out, giving you full approval control.
OpenClaw Skill Support: Registers as a native OpenClaw skill (/meal-plan) for orchestrated multi-step AI workflows.
Recipe Reuse: Filter saved recipes by tag, export as JSON for meal planning, and track last-used dates to identify your household's favorites.
Flexible CLI: Works standalone with Python or integrates into larger OpenClaw agent systems.

Purpose and Significance

Meal planning remains a high-friction task: balancing budget constraints, dietary needs, household preferences, and ingredient availability across grocery stores. meal-plan automates this end-to-end using Claude for dietary reasoning, the Kroger API for live pricing discovery, and local storage for recipe persistence. It demonstrates how open-source AI skills can solve genuine household problems by combining multiple APIs (LLM + grocery commerce) into a coherent user experience. The project is particularly valuable for families managing dietary restrictions (PCOS, allergies, keto, etc.) or strict weekly budgets.

Getting Started

Installation is one command:

curl -fsSL https://raw.githubusercontent.com/shuperj/meal-plan/master/deploy.sh | bash

Then configure in four steps: (1) obtain Kroger and Anthropic API keys, (2) set environment variables in .env, (3) run python execution/meal_config.py setup to define household defaults (ZIP, budget, meal count, dietary rules), and (4) authorize Kroger via python execution/kroger_api.py auth. Restart the OpenClaw gateway if using the skill integration.

Core workflows are command-line driven: python execution/meal_planner.py generates a plan, python execution/grocery_list.py resolves it to real products, and python execution/kroger_api.py cart-add stages items in your cart.

Architecture and Project Structure

The codebase is modular and purpose-built:

meal_config.py — Household configuration (budget, dietary preferences, household size, ZIP code).
meal_planner.py — Calls Claude to generate meal plans; optionally incorporates saved recipes from your Obsidian vault.
grocery_list.py — Converts meal ingredients into a normalized grocery list.
kroger_api.py — OAuth-based Kroger API client; handles store location, product search, pricing, and cart operations.
recipe_manager.py — YAML-aware recipe persistence; lists, filters, exports, and updates recipe metadata in your vault.
directives/meal_plan.md — OpenClaw workflow SOP (standard operating procedure) for AI orchestration.
references/pcos.md — Dietary guidelines reference (extensible for other dietary frameworks).

Configuration is persistent: Kroger refresh tokens and household defaults survive updates. Dependencies are minimal (requests, anthropic, python-dotenv, pyyaml) and installed automatically.

Who This Is For

OpenClaw users: Extend your AI agent with a native meal-planning skill that orchestrates multiple APIs in a deterministic workflow.
Budget-conscious households: Weekly budget constraints are baked in; the tool generates plans that respect your limits and show real prices upfront.
Dietary managers: Built-in support for PCOS, high-protein, vegan, keto, and custom dietary rules via Claude's reasoning.
Obsidian power users: Recipes integrate directly into your vault as searchable, taggable markdown documents.
Grocery automation developers: The Kroger API client and recipe manager are reusable components for other shopping workflows.

Extending the Project

The reference framework (e.g., references/pcos.md) is designed to be extended: add dietary guidelines for keto, carnivore, diabetic meal planning, or allergen-aware shopping, then pass them to Claude as context. Recipe vault tags are user-defined—organize by cuisine, cook time, cost per serving, or any schema that fits your household. The OpenClaw skill registration (SKILL.md manifest) allows integration with other skills for complementary workflows (budgeting, nutrition tracking, etc.).

Requirements and Dependencies

System: Python 3.10+ (no compiled extensions). APIs: Active Kroger developer app (client ID/secret) and Anthropic API key. Python packages: requests, anthropic, python-dotenv, pyyaml (all installed by the deployment script). Optional: Obsidian with local vault for recipe management (recipes still work without it).

Resources and Links

GitHub Repository: github.com/shuperj/meal-plan — Full source, CLI examples, deployment script.
Kroger API Docs: developer.kroger.com — Register app, OAuth flow, product/cart endpoints.
Anthropic Claude API: console.anthropic.com — API key management and usage documentation.
OpenClaw Integration: github.com/openclaw — Learn to register skills and orchestrate workflows. Antfarm: Multi-Agent Workflow Orchestration for OpenClaw
Obsidian Vault Setup: Configure RECIPE_VAULT_PATH to point to your recipes folder; YAML frontmatter is fully compatible with Obsidian properties.

License: MIT. Last updated February 2026. Actively maintained and compatible with current Kroger and Anthropic APIs.

Read original