Grocery shopping assistant for Kroger-owned stores. Find nearby stores, search products with pricing, and add items to your cart. Works with Kroger, Ralphs, Fred Meyer, King Soopers, Harris Teeter, Food 4 Less, Fry's, Smith's, and more.
Grocery shopping assistant powered by the Kroger API. Supports all Kroger-owned banners.
find_stores. The response includes the chain name (Kroger, Ralphs, etc.) and the locationId.locationId from the store result for all subsequent product searches.preview_cart with the locationId to validate item pricing and availability before adding to cart. No authentication required.check_auth_status to determine if the user is authenticated.kroger_start_auth to get the authorization URL and present it to the user.Authentication is decoupled from cart operations — add_to_cart and get_profile return an AUTH_REQUIRED error without opening a browser. Follow these steps when authentication is needed:
check_auth_status to see if the user is already authenticated (avoids unnecessary auth prompts).kroger_start_auth — this starts a local callback server and returns the Kroger authorization URL.Do not attempt to open the URL yourself. Present it to the user for them to open.
You can also use the kroger-oauth prompt to get step-by-step guidance for this flow.
1. find_stores(zipCode: "94102") → get locationId
2. search_products(term: "milk", locationId: ...) → pick product UPC
3. preview_cart(items: [{upc, qty}], locationId: ...) → verify price/stock
4. check_auth_status() → verify authentication
5. [if not auth] kroger_start_auth() → user logs in
6. add_to_cart(items: [{upc, qty}]) → confirm to user
1. check_auth_status() → already authenticated
2. find_stores(zipCode: "...") → get locationId
3. search_products(term: "eggs", ...) → find item
4. preview_cart(items: [...], locationId: ...) → verify availability
5. add_to_cart(items: [...]) → add items
All tools return structured JSON responses directly — no browser interaction is triggered automatically. The agent controls when to present auth URLs to users by explicitly calling kroger_start_auth.
npx @blanxlait/pantry-agent stores <zip>
npx @blanxlait/pantry-agent stores <zip> --limit 10
npx @blanxlait/pantry-agent store <locationId>
npx @blanxlait/pantry-agent search "<term>" --store <locationId>
npx @blanxlait/pantry-agent search "<term>" --store <locationId> --limit 20
npx @blanxlait/pantry-agent search "<term>" --store <locationId> --brand "Kroger"
npx @blanxlait/pantry-agent product <productId> --store <locationId>
npx @blanxlait/pantry-agent cart add <upc> --qty 2 --modality PICKUP
| Command | Description | Auth required |
|---|---|---|
stores <zip> | Find Kroger-owned stores near a ZIP code | No |
store <locationId> | Get store details including hours and departments | No |
search "<term>" --store <id> | Search for products by name, brand, or description | No |
product <id> --store <id> | Get detailed product info (price, stock, fulfillment) | No |
cart add <upc> | Add items to the user's Kroger cart | Yes |
auth | Authenticate with Kroger (opens browser) | — |
auth --status | Check authentication status | — |
| Tool | Description | Auth required |
|---|---|---|
find_stores | Find Kroger-owned stores near a ZIP code | No |
get_store | Get store details including hours and departments | No |
search_products | Search for products by name, brand, or description. Returns price, stock, fulfillment, size, and categories. | No |
get_product | Get detailed product info (price, stock, fulfillment) | No |
preview_cart | Preview items before adding: shows pricing, availability, and estimated total. Useful for validation before add_to_cart. | No |
check_auth_status | Check if the user is authenticated without triggering an OAuth flow | No |
add_to_cart | Add items to the user's Kroger cart | Yes |
get_profile | Get the authenticated user's profile | Yes |
kroger_start_auth | Start browser-based OAuth; returns authorization URL for user to open | — |
Agent-driven actions return structured errors for common failure modes:
| Error type | Description | Resolution |
|---|---|---|
AUTH_REQUIRED | User is not authenticated | Call kroger_start_auth, present URL to user |
| Out of stock | availability: "out_of_stock" in product results | Show alternatives from search_products |
| Unknown stock | availability: "unknown" in product results | Inform user; item may still be available |
| Product not found | error field in preview_cart item | Verify UPC or search for alternative |
| Fulfillment unavailable | fulfillment.delivery: false etc. in product | Show available fulfillment options to user |
~/.pantry-agent/tokens.json.kroger_start_auth.