Skip to content

Portage

Portage lets an AI agent find and buy things from real online stores for you, and you approve every payment. It ships as a command-line tool (portage), a Claude Code plugin (buy) that drives it, and Ruby gems that let any store serve the same open protocols (MCP and UCP) to shopping agents.

Status

Pre-1.0. APIs may still change between minor versions. Latest release set: 0.23.0 (changelog).

Start here

You want to… Read
Buy something through Claude or another agent Quickstart, then the buy plugin
Build an agent that shops through Portage Agentic flow tutorial, then the CLI JSON reference
Call a store's UCP endpoint from Ruby Walkthrough and the portage-ucp-client API
Let agents buy from your store Serving /.well-known/ucp, portage-ucp API, security hooks
Write an adapter for a new platform Writing adapters, architecture, capability coverage
Understand the protocols UCP overview

How it works

A shopper's agent never scrapes. It works with stores that publish a UCP manifest at /.well-known/ucp, with stores whose pages expose WebMCP tools, and with platforms whose API credentials you already hold (your own store). Everything else ends in a hand-off: Portage builds what it can, then opens the checkout for you to pay.

Tier What happens Default
A Opens the checkout in your own browser. You pay. On
B A separate Portage browser profile builds the cart, then stops at payment. You pay. Off (opt in)
C Hand-off only. Portage opens the page and you buy it yourself. No requests to the site, no scraping, no automation of any kind. Every Amazon site, plus walmart.com, ebay.com, bestbuy.com and any host you add

Hard rules, in every tier: card data never passes through Portage; nothing is bought without your explicit yes; Portage never reads your browser's password, cookie or autofill stores or attaches to your default browser profile; and it never solves or bypasses a CAPTCHA. Portage is open-source software provided as-is, without warranty of any kind (MIT). How you use it on any site, and compliance with that site's terms, is your responsibility. Details: CLI reference § Tiers and Security.

Packages

Package Version For What it does Docs
buy plugin 0.10.5 Shoppers Claude Code plugin that shops through portage, plus a read-only shop-research skill buy skill, shop-research skill
portage-cli 0.16.0 Shoppers, agent builders The portage command CLI reference, tutorial, JSON reference
shop-via-ucp skill – Agent builders Buy through a store's UCP endpoint, with or without portage skill
browse-via-ucp skill – Agent builders Read-only: a store's manifest, catalog and whether it supports automated buying skill
portage-ucp-client 0.8.0 Agent builders Ruby client: connect to a store's manifest, or drive your own Adapter, as the shopper's agent API, README
portage-ucp-decision 0.1.2 Agent builders Offer ranking, escalation policy, confidence gate (Jev/Laya), PolicyGuard API, README
portage-ucp-journal 0.1.1 Agent builders Buyer-side purchase journal and its Store abstraction API, README
portage-ucp-webmcp 0.2.0 Both WebMCP transport: serve tools in the page, or drive a page's tools (Tier B profile, autofill) API, README
portage-ucp 0.17.0 Merchants Protocol core: Adapter contract, capability registry, manifest builder, MCP server API, README
serve-via-ucp skill – Merchants Set up a store's own UCP endpoint skill
portage-ucp-shopify 0.7.0 Merchants Shopify Admin and Storefront GraphQL APIs README
portage-ucp-wix 0.2.1 Merchants Wix Stores Catalog and eCommerce REST APIs README
portage-ucp-woocommerce 0.3.0 Merchants WooCommerce Admin REST API and Store API README
portage-ucp-bigcommerce 0.2.1 Merchants BigCommerce v3 Catalog/Carts/Checkouts and v2 Orders APIs README
portage-ucp-magento 0.2.1 Merchants Magento/Adobe Commerce REST v1 README
portage-ucp-etsy 0.1.5 Merchants Etsy Open API v3 catalog and orders; checkout is a redirect link README
portage-ucp-instagram 0.2.0 Merchants Meta Commerce Catalog; checkout is a redirect link; get_order is deprecated and stops working after Meta removes its Order Management endpoints on 2026-10-27 README

Every adapter gem ships an exe/ server and the PORTAGE_UCP_CONFIG hook, with a shared examples/portage_ucp.rb starting point (library usage). Credentials per platform: adapter requirements. Row-per-adapter view: the feature matrix. On Shopify, the native Universal Commerce Agent app covers checkout and orders with no code; Portage adds cart, catalog and a signed manifest (serving /.well-known/ucp).

Requirements

Ruby 3.2 or newer, and the mcp gem ~> 1.8 (pulled in by portage-ucp). The Homebrew formula brings its own Ruby, so a Homebrew install needs neither.

Contributing

Bug reports and pull requests are welcome at tomtom87/Portage. The project is pre-1.0 and still tracking the spec, so open an issue before any change bigger than a bugfix. Contributing has the workflow. AI agents: this site publishes llms.txt and llms-full.txt.

License

MIT. Copyright (c) 2026 Tom Whitbread.