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.