zero

Files (1)

• SKILL.md

SKILL.md (first lines)

# zero

Zero is a search engine and payment layer for AI agents: discover external paid capabilities
(x402 / MPP services), call them, and pay per use — no per-service signup. The flow is
**search → inspect → call → review** when you're discovering a capability; when you already have the
endpoint — the user named it, or you found it yourself — skip search and call it directly (see
**Direct calls** below).

**When to use it:** as the fallback for anything genuinely beyond your native abilities — before
telling the user "I can't do that," run a `zero search`. **When NOT to use it:** for things you
already handle yourself — writing code, answers from your own knowledge, local files, shell
commands, math. Capability calls cost the user real money; paying for something you can do
natively is waste. If you can do it yourself, just do it.

Two surfaces give you Zero:

- **The runner** — the `zero` CLI, provisioned by the plugin/extension for this session or
  installed standalone by the user (see **Resolving `zero`**). This is your primary tool: it runs
  the whole loop, handles 402 payment (including cross-chain), streams binary output, and enforces
  spend caps.
- **The MCP connector** (`https://mcp.zero.xyz`) — the Zero connector tool surface. Its job is
  **authentication and funding**, not the loop. In ephemeral/sandbox environments it is also the
  *only* way to authenticate the runner (see below).

## Resolving `zero`

Every example below invokes the runner as plain `zero`, and that is also what you should type
in real commands whenever it resolves: users read your commands, and `zero search …` reads like
a normal CLI where `"$ZERO_RUNNER" search …` reads like machinery. The name is generic, though,
so resolve it once, before your first call — don't trust `$PATH` blindly. Take the first tier
that resolves to a working executable, then use the same spelling everywhere `zero` appears
below:

1. **`zero` on `$PATH`** — preferred. Either the provisioned runner (the SessionStart hook
   prepends its directory to PATH: immediately on hosts that persist hook env vars, in new
   shells elsewhere) or a standalone CLI install (`npm install -g @zeroxyz/cli`). Trust it
   without further checks when `command -v zero` matches `$ZERO_RUNNER` or points into
   `$HOME/.zero/runtime/bin`; any other path counts only if `zero --help` prints the Zero CLI
   header (`Zero CLI — Search engine for AI agents`). Anything else → fall through.
2. **`$ZERO_RUNNER`** — the runner's absolute path, exported by the SessionStart hook on hosts
   that persist hook env vars (Claude Code, Codex). The fallback spelling when bare `zero`
   doesn't resolve yet or failed the check above.
3. **`$HOME/.zero/runtime/bin/zero`** — the provisioned runner's well-known path, for hosts
   that don't persist hook env vars (e.g. Gemini CLI); the SessionStart hook reports it.
4. **`npx -y @zeroxyz/cli@latest`** — ephemeral/sandbox environments only, where nothing is
   provisioned or installed (see **Ephemeral / sandbox** below).

```bash
ZERO="$(command -v zero || true)"                     # tier 1 — verify per the rules above
[ -n "$ZERO" ] || ZERO="${ZERO_RUNNER:-}"
[ -x "$ZERO" ] || ZERO="$HOME/.zero/runtime/bin/zero"
```

When tier 1 wins, invoke it as plain `zero`; on the lower tiers use the absolute path (which
also survives shells that don't persist variables between commands).

If no tier resolves in a persistent environment, tell the user Zero isn't available here —
don't install the CLI yourself. In an ephemeral sandbox, fall through to `npx`. Never generate
a private-key wallet yourself either way (managed wallets come from auth — see below).

## The runner

The runner is the published `@zeroxyz/cli`. Under the plugin/extension it's installed once per
session into a shared, plugin-owned home and reported by its absolute path (also exported as
`$ZERO_RUNNER` on hosts that persist hook env vars; default path `~/.zero/runtime/bin/zero`); a
standalone `npm install -g @zeroxyz/cli` serves the same role. Either way you do **not** install,
update, or configure it yourself, and the runner needs no wallet setup. Identity comes from a
session (below); signing is managed server-side.

**Prefer the runner for every step of the loop, even when MCP search/get/fetch tools are also
available.** The runner is the complete, auditable path: it pays 402 challenges automatically,
applies `--max-pay` caps, separates body from progress on stdout/stderr, and writes binary
responses to disk. Use the connector only for what the runner can't do itself: authenticating in a
sandbox, and funding.

## Authentication

Before touching any auth command, decide **who the account is for**:

- **A human is present** (or asked you to sign *them* in) → `zero auth login`. It's the device
  flow below and creates their account on first sign-in; `zero auth register` is an alias for
  the same command, not a separate signup.
- **Fully autonomous — no human in the loop** → `zero auth agent register`. Anonymous account
  plus a managed wallet, no browser, no one to hand a URL to.
- **Never** use `zero auth agent register` when a human is present — it mints an account owned
  by *no one* (a human can only take it over later via the claim flow). If there's a human,
  `zero auth login` already creates their account.

Beyond that, the environment picks the mechanics.

### Persistent — the user's own computer (not a sandbox or cloud runner)

Authenticate the runner with the **device-code login**. It's non-interactive and agent-friendly:
you start it, show the user a URL, then run the finish step — which **polls on its own** until they
authorize. No browser is opened on the machine running the agent, and you do **not** wait for the
user to tell you they're done — the finish command blocks until it knows.

```bash
# 1. Start: prints a URL + user code and exits immediately (no waiting, no browser).
zero auth login --start --json
# → {"deviceCode":"…","userCode":"WXYZ-1234","verificationUri":"https://…",
#    "url":"https://…?code=WXYZ-1234","pollInterval":5,"expiresAt":…}

# 2. Show the user the "url" (and the userCode) and ask them to authorize it in their browser.

# 3. Immediately run finish. It BLOCKS and polls (~every 2s) until the user authorizes, then
#    persists the session. Run it right after step 2 — do NOT pause to ask "are you done yet?";
#    the command returning is your signal.
zero auth login --finish <deviceCode> --json
# → {"status":"ok","user":{"id":"…","email":"…"}}     once authorized
# → {"status":"expired"}                                if the ~10 min code TTL lapses first
```

Treat the finish command's return as the source of truth: a successful exit means the session is
already persisted; `{"status":"expired"}` means the code lapsed — start over from step 1. Never
block the conversation polling by hand or waiting on the user to confirm; `--finish` is the poll.

The session is saved to the shared `~/.zero/config.json`, so authenticating once here also signs
you in everywhere Zero is used on this machine — the standalone `zero` CLI and your other agents

From officialzeroxyz/zero-plugins, MIT.

More from officialzeroxyz/zero-plugins