Portage

<h1 align="center">
  <img src="docs/assets/portage-logo.svg" alt="Portage" width="520">
</h1>

<p align="center">
  <a href="https://rubygems.org/gems/portage-cli"><img src="https://img.shields.io/gem/v/portage-cli" alt="gem version"></a>
  <a href="https://rubygems.org/gems/portage-cli"><img src="https://img.shields.io/gem/dt/portage-cli" alt="gem downloads"></a>
  <a href="https://github.com/tomtom87/homebrew-portage"><img src="https://img.shields.io/badge/dynamic/regex?url=https%3A%2F%2Fraw.githubusercontent.com%2Ftomtom87%2Fhomebrew-portage%2Fmain%2FFormula%2Fportage.rb&search=portage-cli-(%5Cd%2B%5C.%5Cd%2B%5C.%5Cd%2B)&replace=%241&label=homebrew&color=orange" alt="homebrew"></a>
  <img src="https://img.shields.io/badge/ruby-%3E%3D%203.2-red" alt="ruby">
  <img src="https://img.shields.io/badge/license-MIT-blue" alt="license">
  <a href="https://portage.readthedocs.io/en/latest/"><img src="https://img.shields.io/badge/docs-readthedocs-blue" alt="docs"></a>
  <a href="#install-the-buy-plugin"><img src="https://img.shields.io/badge/claude%20code-plugin-D97757?logo=claude&logoColor=white" alt="Claude Code plugin"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-supported-black?logo=modelcontextprotocol" alt="MCP"></a>
  <a href="https://ucp.dev"><img src="https://img.shields.io/badge/UCP-supported-4B32C3" alt="UCP"></a>
  <a href="https://clawhub.ai/tomtom87/portage-buy"><img src="https://img.shields.io/badge/openclaw-skill-14B8A6" alt="OpenClaw skill"></a>
  <a href="https://glama.ai/mcp/servers/tomtom87/Portage"><img src="https://glama.ai/mcp/servers/tomtom87/Portage/badges/score.svg" alt="Portage-UCP MCP server – quality and maintenance score on Glama"></a>
</p>

<p align="center">
  <img src="docs/assets/portage-demo.gif" alt="portage buy searching The Light Yard over UCP and opening the checkout for a gold leaf bathroom wall light" width="900">
</p>

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](https://modelcontextprotocol.io) and [UCP](https://ucp.dev)) 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.18.0 ([changelog](CHANGELOG.md)).

## 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

<!-- buy-plugin-install-start -->
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.

2. **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
    ```

3. **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.

4. **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:

```bash
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.
<!-- buy-plugin-install-end -->

### Other agents: Codex, Cursor, OpenCode and more

<!-- other-agents-start -->
The `buy` skill is a plain [`SKILL.md`](https://github.com/tomtom87/Portage/blob/main/plugins/buy/skills/buy/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`](https://github.com/tomtom87/Portage/blob/main/plugins/buy/skills/shop-research/SKILL.md): 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/`](https://github.com/tomtom87/Portage/tree/main/plugins/buy/skills/buy) folder into the agent's skills directory, and [`plugins/buy/skills/shop-research/`](https://github.com/tomtom87/Portage/tree/main/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](https://clawhub.ai/tomtom87/portage-buy): `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](https://docs.openclaw.ai/clawhub)). 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](https://docs.openclaw.ai/tools/skills)), so copy or symlink `plugins/buy/skills/buy/` into either. `shop-research` is on [ClawHub](https://clawhub.ai/tomtom87/portage-shop-research) 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](https://github.com/tomtom87/Portage/blob/main/openclaw-plugin/README.md).

- **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](https://mise.jdx.dev/) (`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.
<!-- other-agents-end -->

### Use the CLI yourself

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

```bash
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](portage-cli/README.md#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:

```bash
portage buy http