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. It is for people who want an agent to shop for them, developers building shopping agents, and merchants who want agents to buy from their store.

Status: pre-1.0. APIs may still change between minor versions. Latest release set: 0.22.0 (changelog).

Quickstart

Two ways in: let Claude shop for you with the buy plugin, or run the portage CLI yourself. Both use the same CLI and take about five minutes.

Install the buy plugin

The plugin teaches Claude Code to shop through the portage CLI, so install the CLI first.

1. Install the CLI (portage-cli 0.9.0 or newer):

bash brew install tomtom87/portage/portage

Or, on Ruby 3.2 or newer, gem install portage-cli. Homebrew bundles every adapter. With RubyGems, also install portage-ucp-webmcp 0.2.0 or newer if you want the Portage browser profile and checkout autofill.

1. Add the plugin. Inside Claude Code:

text /plugin marketplace add tomtom87/Portage /plugin install buy@portage

Or from a shell:

bash claude plugin marketplace add tomtom87/Portage claude plugin install buy@portage

1. Run `portage setup` once, in a terminal. It asks for your shipping address, optional search keys and spending caps, one skippable step at a time. It is interactive, so run it yourself rather than through Claude.

1. Ask Claude. Type /buy a burton snowboard under $600, or just ask in plain words. The skill is listed as buy:buy. Claude checks your setup, shows real offers and a dry-run total, and waits for your yes before any purchase.

To update or remove it:

claude plugin marketplace update portage

claude plugin update buy@portage # then restart Claude Code

claude plugin uninstall buy@portage claude plugin marketplace remove portage

A listing in the Claude plugin directory is coming. Until then, this marketplace is the install route.

Other agents: Codex, Cursor, OpenCode and more

The buy skill is a plain SKILL.md file, so any agent that loads skills and can run commands on your machine can use it. Install the CLI and run portage setup first, as above. The plugin carries a second skill, shop-research: read-only, for price, stock, store and order questions with no purchase in mind, and it hands over to buy to buy. Install it next to buy the same way.

• With [dotagents](https://github.com/getsentry/dotagents) (Codex, Cursor, OpenCode): one command installs the plugin into ~/.agents/ and generates each agent's plugin or skill files.

bash npx @sentry/dotagents add tomtom87/Portage

Refresh it with npx @sentry/dotagents install. Remove it with npx @sentry/dotagents remove buy. If your agents.toml only allows trusted sources, run npx @sentry/dotagents trust add tomtom87/Portage first.

• As a plain skill (VS Code, or any agent without plugin support): copy the plugins/buy/skills/buy/ folder into the agent's skills directory, and plugins/buy/skills/shop-research/ next to it. With dotagents, declare them in ~/.agents/agents.toml and run npx @sentry/dotagents install to get them in ~/.agents/skills/buy and ~/.agents/skills/shop-research:

`toml [[skills]] name = "buy" source = "tomtom87/Portage" path = "plugins/buy/skills/buy"

[[skills]] name = "shop-research" source = "tomtom87/Portage" path = "plugins/buy/skills/shop-research" `

• OpenClaw. Install the CLI first (above), then the skill from ClawHub: openclaw skills install @tomtom87/portage-buy puts it in your active OpenClaw workspace, and clawhub install @tomtom87/portage-buy puts it in ./skills under the current directory (ClawHub docs). Then run portage setup. The skill's frontmatter carries OpenClaw's metadata.openclaw block (needs the portage binary, names every env var it reads as optional, brew install spec), so OpenClaw gates the skill until portage is installed. To skip ClawHub, use the plain-skill route above: OpenClaw reads personal skills from ~/.agents/skills and managed ones from ~/.openclaw/skills (OpenClaw skills docs), so copy or symlink plugins/buy/skills/buy/ into either. shop-research is on ClawHub too, as @tomtom87/portage-shop-research (install it the same way), or copy or symlink plugins/buy/skills/shop-research/. Its frontmatter has the same metadata.openclaw shape, with only the search and retailer keys it names. ClawHub republishes skills under MIT-0; this repo stays MIT.

• OpenClaw plugin. For typed tools instead of shell commands, install the native plugin: openclaw plugins install clawhub:tomtom87/portage, after the CLI (portage-cli 0.12.0 or newer) and portage setup. It gives the agent portage_* tools over the CLI and bundles buy, shop-research and a short OpenClaw skill that maps each buy step to its tool. The read-only tools are on by default; the ones that price, approve, buy or hand off are opt-in in OpenClaw's tool settings. Spending policy and approval stay in Portage, and no tool can pass --yes for a URL or loosen your limits. See the plugin README.

• Omarchy (Arch Linux). Install the CLI with Omarchy's own helper, omarchy-mise-install gem:portage-cli portage, which writes a ~/.local/bin/portage wrapper the way Omarchy installs claude, codex and gh. Plain mise (mise use -g gem:portage-cli) or Homebrew on Linux (brew install tomtom87/portage/portage) also work. Then run portage setup. A stock Omarchy needs sudo pacman -S --needed make first: Ruby 3.4 builds bigdecimal natively, gcc is already there through clang, and only make is missing. For the skills, link plugins/buy/skills/buy/ and plugins/buy/skills/shop-research/ into the skills directory of the agent you run. Omarchy's own provisioning links into ~/.agents/skills (OpenClaw, and the dotagents route), ~/.claude/skills (Claude Code; the plugin route above is preferred) and ~/.codex/skills.

• Chat apps in a browser (ChatGPT, Grok and similar) can't run portage on your machine, so they can't use the skill. Use the vendor's coding agent or CLI instead, if it loads skills.

Use Portage from any MCP client

portage mcp serves the same search, quote, approve and buy tools over MCP on stdio, for any client that runs local servers. Install the CLI (brew install tomtom87/portage/portage or gem install portage-cli, 0.14.0 or newer) and run portage setup in a terminal first. Spending policy and approval stay in Portage: the agent can search and price, but a purchase waits for your approval.

• Claude Desktop. Add this to claude_desktop_config.json (Settings, Developer, Edit Config) and restart. Claude Desktop doesn't inherit your shell PATH, so give the absolute path from which portage (typically /opt/homebrew/bin/portage or /usr/local/bin/portage):

json { "mcpServers": { "portage": { "command": "/opt/homebrew/bin/portage", "args": ["mcp"] } } }

• Claude Code. claude mcp add --scope user portage -- portage mcp (drop --scope user to keep it to the current project).

• Docker. docker run -i --rm -v "$HOME/.portage:/root/.portage" ghcr.io/tomtom87/portage-mcp:0.14.0 runs the same server from the registry image. A container can't open your browser, so a hand-off prints the checkout link instead.

Use the CLI yourself

Install the CLI as in step 1 above, run portage setup, then:

portage find --query "burton snowboards" --json

portage buy "burton snowboards" --max-price 600 --dry-run --json

find works with no keys. Its default search, DuckDuckGo's keyless API, resolves brand and store names ("burton snowboards") but not open-ended queries ("waterproof hiking boots"). For those, add a Brave or Google search key: portage setup asks, and search backends has the details. buy without a store URL lists offers and, in a terminal, lets you pick one. --dry-run shows the real total and never charges.

With a store URL, buy goes straight to that store's /.well-known/ucp manifest:

portage buy https://some-ucp-store.example --query "hoodie" --dry-run --json

To buy for real, enroll a payment method (portage payment enroll ), set spending caps (portage policy set), then drop --dry-run and add --yes. buy checks out only through a store's published UCP endpoint, or a platform API you already hold credentials for (your own store). Everything else ends in a hand-off. It never scrapes. The CLI tutorial walks through all of this, including what to do when search comes back empty.

portage setup saves to ~/.portage/.env (chmod 600), and .env.example lists every variable. Only ~/.portage/.env loads automatically, never a .env in the current directory, so a cloned repo can't quietly redirect your p