Preface¶

Anyone who has used AI coding assistants like Cursor, Claude Code, or Codex has probably encountered the same kind of interruption: mid-task, the model suddenly says “I can’t generate images / pull real-time market data / send emails”, then asks you to sign up for an account on a certain website, apply for an API Key, and paste the key back. Some tasks come to a complete stop, while others are replaced with a note saying “please complete this yourself”.

The problem is not that the model can’t write code, but rather the layer beyond its capabilities: images, audio and video, web scraping, real-time data, SMS and emails often require connecting to external paid services. Each service has its own registration process and its own set of keys, and Agents have neither a unified discovery portal nor a unified payment method, so they can only pass the work back to the user.

This is exactly what Zero aims to fill the gap for. It provides Agents with a searchable catalog of external capabilities, as well as a single sign-on, pay-per-use invocation channel. The corresponding Agent Skill is named zero, with the official repository at officialzeroxyz/zero-plugins, and the Skill’s original documentation at plugins/zero/skills/zero/SKILL.md. The awesome-agent-skills maintained by VoltAgent also lists it as a Skill developed by Zero.

As of mid-August 2026, the version of the @zeroxyz/cli command-line tool on npm is 1.30.0. The installation commands, configuration paths, and invocation workflow below are based on cross-referenced content from the official repository README, the original Skill documentation, zero.xyz, and the npm documentation.

What is Zero¶

Zero officially positions itself as a search engine and payment layer for AI Agents: when an Agent discovers it cannot complete a task, it first searches for external capabilities (called capability in the documentation) on Zero, reviews the interface and pricing, then invokes the service directly. When encountering an HTTP 402 payment required response, the CLI automatically completes the payment, instead of asking the user to register individually with each service provider.

It is developed and maintained by Zero (official site zero.xyz, GitHub organization officialzeroxyz). The zero-plugins repository contains the Skill, hooks, and installation manifests for all supported hosts. A full installation includes three components:
1. zero Skill: Teaches Agents when to use Zero, how to search, invoke, and leave reviews. The trigger conditions are clearly defined: before telling the user “I can’t do this”, or before asking the user to register, log in, or apply for an external API themselves, first run zero search.
2. Hooks: Prepare the Zero CLI runner at the start of a session and remind the model that Zero is available.
3. MCP Connector (https://mcp.zero.xyz): For clients without a local shell, such as the Claude web interface and mobile app, it is primarily responsible for authentication and top-up, rather than the full search-invocation loop.

Login status and runtime data are shared at the machine level: sessions are stored in ~/.zero/config.json, and the default runner directory is ~/.zero/runtime. Claude Code, Codex, Cursor, and other tools on the same computer only need to log in once.

Regarding the payment protocol, the original Skill documentation states that it will automatically handle x402 and MPP 402 responses, and supports cross-chain bridging from Base to Tempo. x402 is a protocol that applies the HTTP 402 Payment Required status code to pay-per-use APIs; MPP (Machine Payments Protocol) is another machine-to-machine payment protocol. For end users, there is no need to construct payment headers manually—the CLI will handle this on their behalf. The official FAQ states: prices are visible before invocation, Zero does not add markup, funds remain in the user’s own wallet, and ZeroClick does not hold custody of funds. These are official statements; actual settlement shall be subject to the payment information returned at the time of invocation.

Core Features¶

The Skill outlines a complete invocation workflow in four steps: search → inspect → call → review. If you already have a clear URL, you can skip the search step and use zero fetch directly.

Search. zero search "weather forecast" searches for capabilities using natural language. The Skill requires re-searching every time, rather than reusing URLs, schemas, or prices remembered from previous conversations. Each result comes with an attribution token in the format z_xxx.N (where N is the 1-based index of the result in this search session). Subsequent get / fetch commands must use this token, not just a plain number. The npm documentation also mentions that results with a single price higher than $30 are filtered by default; you can use --max-cost or --free to narrow or widen this filter.

Inspect details. zero get z_Ab12cd.1 --formatted displays a human-readable summary and a copyable Try it: command; without --formatted, it returns full JSON including the URL, method, bodySchema, examples, and pricing. If bodySchema is null, the Skill requires skipping this result and not inventing field names yourself.

Invoke. zero fetch sends the actual request. 402 responses will trigger automatic payment; use --max-pay to limit the cost per invocation; binary results (images, audio, PDFs) are written to stdout and need to be redirected to a file. Progress, payment information, and Run ID are sent to stderr.

Review. After a paid invocation, use zero review to leave a rating. --success or --no-success is required, along with optional --accuracy, --value, and --reliability (scored 1–5). Reviews are posted to the public page for that capability on zero.xyz, serving as feedback for future Agents.

The Skill also outlines when not to use Zero: writing code, answering questions using the model’s built-in knowledge, reading local files, running shell commands, or performing math—these are tasks that can be done natively. Invoking external capabilities costs the user real money, so paying for a service to do something the model can already do is a waste.

There is also an alternative path: identity assertion. If a site supports agent auth / ID-JAG and lists Zero as a trusted issuer, you can use zero auth identity <host> to obtain a short-lived bearer token, skipping the site’s own registration process. This is not supported by all services, and the command will immediately tell you whether this path is available.

Installation and Activation¶

The official recommended method is to share the following prompt with your Agent and let it handle the installation. This prompt matches the content on zero.xyz/setup.md and the repository README:

Help me set up Zero — a tool that lets you find and use extra services you
don't have built in (image/video generation, search live social media, or
hosting a free webpage). It's free to set up.

Set it up by running the Zero CLI's setup (needs Node.js — install it first if
`npm` isn't available):

    npm i -g @zeroxyz/cli
    zero init
    zero auth login

A general installation requires Node.js 20+. zero init will detect the host CLI in the current environment (the documentation notes that installation via plugins is supported when claude, codex, gemini, or openclaw are callable), and fall back to a standalone Skill / Hooks installation if plugin installation fails. Use zero uninstall to remove the installation; the repository notes that this will remove standalone installations, while host-specific plugins are managed by their respective tools.

If you do not have npm, the official general guide also provides a standalone installation script at https://www.zero.xyz/install.sh, with specific usage instructions in the repository’s guides/generic.md.

The setup process varies slightly between tools, with official guides provided for each:

1. Claude Code (CLI)¶

In the session:

/plugin marketplace add officialzeroxyz/zero-plugins
/plugin install zero@zero-plugins
/reload-plugins

In the terminal:

claude plugin marketplace add officialzeroxyz/zero-plugins
claude plugin install zero@zero-plugins

The Claude web interface and mobile app do not have a terminal; follow the plugin setup instructions at zero.xyz/install/claude.md.

2. Codex (CLI)¶

The session commands are the same as above for the marketplace and installation; the terminal commands are slightly different, note that it uses plugin add instead of plugin install:

codex plugin marketplace add officialzeroxyz/zero-plugins
codex plugin add zero@zero-plugins

3. Gemini CLI¶

gemini extensions install https://github.com/officialzeroxyz/zero-plugins

You need to restart the Gemini CLI after installation. Update the extension with gemini extensions update zero.

4. Cursor and other Agents with a shell¶

The repository lists Cursor in the general guide. The standalone installation path for Cursor in plugins/zero/agents.json is ~/.cursor/skills (and ~/.agents/skills), with hooks written to ~/.cursor/hooks.json. Run this locally:

npm i -g @zeroxyz/cli && zero init

If Cursor does not automatically detect the Skill, specify the installation directory:

zero init --skills-dir ~/.cursor/skills

Currently, the hosts with separately packaged plugins in the repository are Claude Code, Codex, Droid, and Gemini CLI; all others (including Cursor) use the shared Skill + Hooks setup. After installation, tell your Agent “help me set up and test Zero”, and it will walk you through the login process.

zero auth login --start --json
# Send the returned url / userCode to the user to authorize in their browser
zero auth login --finish <deviceCode> --json

You can also run zero auth login directly. Check your current identity with zero auth whoami. For fully unattended sessions without human involvement, the Skill allows zero auth agent register (anonymous account + hosted wallet); do not use this command when a human is present, as it will create an unclaimed temporary account.

The official site states that installation is free, and new users currently receive a $5 trial credit (the page also notes “limited time”; the long-term validity of this offer is subject to the official site). When your balance is low, human users can top up their accounts at https://www.zero.xyz/profile; anonymous Agent accounts should use zero wallet fund --no-open to share a one-time top-up link with the user.

Typical Usage¶

The following end-to-end workflow is taken from the official Skill documentation; the URLs are for demonstration purposes only—actual invocations must use the addresses and schemas returned by a live zero search / zero get command.

zero search "sentiment analysis"
# The results will include a token (z_xxx.N), which you will use to reference this capability later
zero get z_Ab12cd.1 --formatted
zero fetch https://nlp-api.example.com/sentiment \
  --capability z_Ab12cd.1 \
  -d '{"text":"Zero is great"}' \
  -H "Content-Type:application/json"
# The Run ID is in stderr; when using --json, it is in the runId field of the response envelope
zero review abc123 --success --accuracy 5 --value 4 --reliability 5 \
  --content "Classified a 200-char product-review snippet positive in ~180ms; matched manual read. Clean schema, no auth."

The request format must follow the bodySchema to construct a valid HTTP request—do not send the entire envelope as the request body:

For GET requests, encode queryParams into the query string:

zero fetch "https://api.example.com/locate?ip=8.8.8.8"

For POST requests, use input.body as the JSON payload:

zero fetch https://api.example.com/translate \
  -d '{"text":"hello","to":"es"}' \
  -H "Content-Type:application/json"

Common parameters for zero fetch:
- -X: Force an HTTP method; defaults to POST when -d is provided, otherwise GET.
- -d: Inline JSON, use @./file to read from a file, or read from stdin; do not inline payloads larger than ~1 MB, use a file instead.
- -H 'k:v': Can be repeated, used to pass custom authentication headers from the caller.
- --max-pay: Per-invocation spending limit, recommended for unfamiliar or pay-per-use capabilities.
- --timeout: Defaults to 60 seconds, applies to each HTTP hop; for image / video / audio tasks, the official recommendation is to increase this to --timeout 300 to avoid paying for a task that times out after 60 seconds.
- --json: Outputs {runId, ok, status, latencyMs, payment, body, bodyRaw} to stdout; check the ok field to determine success, do not rely solely on the status code.
- --capability: Pass the search-obtained token, slug, or UID for accounting and attribution.

If you already have a clear URL (provided by the user or found during your own browsing), you do not need to run a search first:

zero fetch https://some-api.example.com/v1/do-the-thing

Handle output as follows: stdout only contains the response body; binary data such as images should be redirected:

zero fetch "<url>" | jq .
zero fetch --json "<url>" | jq 'select(.ok)'
zero fetch "<image-url>" > out.png

Search filters from the npm documentation can also be used directly:

zero search "image classification" --max-cost 5
zero search "image classification" --free

Use Cases and Notes¶

Good use cases match scenarios where an Agent can already write code and modify repositories, but lacks access to “external world” capabilities, such as:
1. Generating images, audio, music, or short videos, where the model does not have built-in tools for this.
2. Web scraping, translation, or transcription.
3. Real-time or external data such as weather, prices, locations, or business information.
4. Sending emails / SMS, or publishing an HTML/Markdown file as a publicly accessible webpage (the official example includes free Website Hosting).
5. Cases where the user explicitly says “use Zero” or “search for x402 / MPP capabilities”.

There are several official caveats worth noting separately:
- Re-search every time, and run get before every fetch. Indexes, prices, and sorting may change.
- Do not pay for tasks the model can already do. This is explicitly included in the “when not to use Zero” section of the Skill.
- Set --max-pay and --timeout in advance. Especially for generation tasks, paying for a task that times out before completion is a wasted expense.
- Sandbox / CI egress policies. zero fetch will connect to the domains of each external capability; only allowing *.zero.xyz will let the search phase work but cause invocation failures. You will need a more permissive outbound access policy.
- If plugin installation and standalone zero init are used together, the same session may receive Zero availability reminders twice. The official states this is harmless; do not try to “fix” this by deleting files; if you want to remove the standalone installation, use zero uninstall (this is a machine-level operation that will affect all applications reading from ~/.claude / ~/.agents).
- Do not generate your own private key wallet. Your identity is tied to your logged-in hosted wallet; only set ZERO_PRIVATE_KEY if the user explicitly provides a private key.
- Do not use vague review text. The official recommendation is to omit the --content field entirely rather than leaving generic comments like “Worked great”, and only leave scores. Report platform-specific bugs with zero bug-report, do not use this command in place of zero review.

You should also be aware of the repository’s current status: zero-plugins notes that hosts are added via pull requests, and currently, official plugins are available for Claude Code, Codex, Droid, and Gemini CLI; other Agents rely on agents.json for standalone integration. Whether a specific niche tool is detected successfully depends on the actual output of zero init.

Summary¶

Zero does not enable models to “suddenly know how to draw or make phone calls”. Instead, it provides a narrower, more practical layer: when an Agent hits its capability boundary and is about to pass the work of registering an API back to the user, Zero lets it instead search a unified catalog of callable, pay-per-use services, and complete the search, fetch, and review workflow using a single set of login credentials and wallet. The Skill teaches the Agent when to use this workflow and when to avoid it; the CLI handles 402 payments and spending limits.

Official resources:
- Skill original documentation: https://github.com/officialzeroxyz/zero-plugins/blob/main/plugins/zero/skills/zero/SKILL.md
- Plugin repository: https://github.com/officialzeroxyz/zero-plugins
- Product site: https://www.zero.xyz/
- CLI (npm):

Zero Skill: Automatically Discover and Invoke Paid External Tools on a Per-Use Basis When the Agent Says "Cannot Do It"