Smart Shopping List
Agent

Build an AI agent that manages your grocery list, suggests recipes from what you have, and helps you shop smarter. Built with OpenCode in under 20 minutes.

Start Building Setup Guide First
Need to set up OpenCode first?

This guide assumes you have OpenCode and a free model provider configured. If you haven't set that up yet:

  1. Install OpenCode: curl -fsSL https://opencode.ai/install | bash
  2. Get a free API key from OpenRouter (no credit card needed)
  3. Or follow the full setup guide for detailed steps

What You'll Build

By the end of this guide, you'll have a command-line shopping list agent that can:

  • Add items to your shopping list with quantities and categories
  • Remove items when you've bought them or changed your mind
  • Display your list organized by category (produce, dairy, pantry, etc.)
  • Suggest recipes based on what's already on your list
  • Save and load your list between sessions using a JSON file

The entire thing is built by asking OpenCode to write it for you. You describe what you want, it writes the code, you run it and refine.

1

Create Your Project

Set up a project folder with an AGENTS.md file that tells OpenCode what kind of project this is.

mkdir -p ~/projects/shopping-agent
cd ~/projects/shopping-agent
mkdir -p ~/projects/shopping-agent
cd ~/projects/shopping-agent

Now create an AGENTS.md file. This is the context file that OpenCode reads to understand your project:

# Shopping List Agent

## Project Type
Python CLI application

## Description
A command-line shopping list manager that lets users add/remove grocery items,
organize by category, suggest recipes, and persist data to a JSON file.

## Tech Stack
- Python 3.8+ (standard library only, no external deps)
- JSON for data storage
- argparse or interactive menu for CLI interface

## Conventions
- Use type hints
- Keep it in a single file for simplicity
- Categories: produce, dairy, meat, pantry, frozen, beverages, other
- Store data in shopping_list.json in the project directory

Save this as AGENTS.md in your project folder. You can create it manually or use OpenCode:

opencode
Why AGENTS.md?
OpenCode reads this file automatically when you start it in the project directory. It gives the AI context about your project's purpose, tech stack, and conventions -- so every response is more relevant and accurate.
2

Build the Shopping Agent

With OpenCode running in your project folder, give it the task. One prompt builds the whole thing.

Type this into OpenCode:

Create a Python script called shopping.py that manages my shopping list.
It should have an interactive menu with these options:

1. Add item (ask for name, quantity, and category)
2. Remove item (by name)
3. Show list (grouped by category)
4. Suggest recipes (based on current items)
5. Clear list
6. Save and quit

Store the list in shopping_list.json so it persists between sessions.
Include at least 10 built-in recipe suggestions that match against
common ingredient combinations.

OpenCode will generate a complete Python script. You'll see it write the file in real time. When it's done, you'll have a working shopping.py in your project folder.

What OpenCode Generates

The output will typically include:

  • A ShoppingList class that handles add, remove, display, and save/load
  • Category-based organization with color-coded terminal output
  • A recipe dictionary mapping recipe names to required ingredients
  • A matching function that suggests recipes when you have enough ingredients
  • JSON persistence so your list survives between runs
3

Run and Iterate

Test your agent and ask OpenCode to improve it based on what you find.

Run your new shopping agent:

python3 shopping.py

You should see an interactive menu like this:

=============================
   Shopping List Manager
=============================

1. Add item
2. Remove item
3. Show list
4. Suggest recipes
5. Clear list
6. Save and quit

Choose an option (1-6):

Try adding a few items: chicken, rice, broccoli, soy sauce. Then try option 4 (suggest recipes) -- you should see it suggest stir-fry or similar matches.

Iterate with OpenCode

Found something you want to change? Go back to OpenCode and ask. The AI remembers your project context from AGENTS.md.

# Example iteration prompts:
Add a "budget tracker" feature that lets me set prices for items
and shows a running total.

Add color coding to the categories when displaying the list.

Add an "essentials" feature that auto-adds common items I always
need (milk, eggs, bread) with one command.
Version control tip
Initialize a git repo with git init and commit after each working version. Store it on GitHub for free. That way you can always roll back if an iteration breaks something.

Example Prompts to Try

Once your basic shopping agent works, try these prompts to extend it:

# Meal planning
Add a weekly meal planner that generates a shopping list for 7 days
of meals, avoiding duplicate ingredients.

# Price comparison
Add a feature that stores typical prices for items and warns me
if I'm buying something that's usually cheaper at a different store.

# Import/export
Add the ability to export my shopping list as a shareable text
message or markdown file.

# Smart suggestions
When I add "pasta", automatically suggest related items I might
need (pasta sauce, parmesan, garlic) and let me add them with y/n.

Each prompt builds on the existing code. OpenCode reads the current state of shopping.py and modifies it in place.

What's Next?

You've built a working shopping list agent. Here's where to go from here:

  • Deploy it: Turn it into a web app with Flask or FastAPI. Host it for free on Cloudflare Pages (static frontend) with a lightweight backend.
  • Track analytics: Add Umami to your web version for privacy-friendly usage tracking.
  • Try another agent: The setup is the same -- only the task changes. Pick your next project:

Ready for the Next Agent?

The pattern is always the same: create a folder, write AGENTS.md, give OpenCode the task. The only thing that changes is the prompt.

Build Email Agent All Guides