Install Zero

Zero (zero.xyz) is a search engine and payment layer for AI agents: search for a capability, call it, and pay per use. The CLI is published on npm as @zeroxyz/cli; the plugin packaging and this runbook are maintained at officialzeroxyz/zero-plugins.

Install

The default path is npm — it works in any harness with Node.js:

Environment	Command
Anything with npm (default)	npm i -g @zeroxyz/cli && zero init
Claude Code	claude plugin marketplace add officialzeroxyz/zero-plugins && claude plugin install zero@zero-plugins
Codex	codex plugin marketplace add officialzeroxyz/zero-plugins && codex plugin add zero@zero-plugins
Gemini CLI	gemini extensions install https://github.com/officialzeroxyz/zero-plugins
Hermes Agent	hermes plugins install officialzeroxyz/zero-plugins/plugins/zero-hermes/hermes --force --enable
Claude Chat (claude.ai) / Claude Cowork	no shell — follow zero.xyz/install/claude.md instead
None of the above	see Fallback installer

The npm row installs the CLI from the public @zeroxyz/cli package (inspect it with npm view @zeroxyz/cli), then zero init integrates the skill and hooks with every harness it detects. The Claude Code, Codex, Gemini CLI, and Hermes Agent rows are per-harness alternatives that install through that harness's own plugin manager: they add the zero-plugins repo as a source (or, for Hermes, install straight from a subdirectory of it), then install the Zero plugin via the manager's normal review-and-consent flow. The plugin's full contents are listed below. The npm and fallback rows end by running zero init.

What the plugin installs

The plugin-manager rows install the same contents, from plugins/zero/ in the repo (Hermes Agent installs the same skill and session-start hook from plugins/zero-hermes/hermes/, where they are vendored for its plugin format; instead of an auto-approve hook — Hermes hooks can't approve — it adds a guard that blocks zero fetch commands missing an explicit --max-pay cap, plus a /zero command):

• A skill — the usage guide for the zero CLI (source)
• An MCP connector pointing at mcp.zero.xyz — how clients without a shell (Claude web and mobile) sign in and reach Zero; CLI harnesses use the zero CLI instead
• Three hooks (source):
  • SessionStart — installs the zero CLI into ~/.zero/runtime/ (downloads Node only if the system lacks v20+) and puts it on PATH. On harnesses without session-env support this appends one PATH line to the shell rc (ZERO_PATH_AUTOADD=0 skips it). Also refreshes the plugin install in the background at most once a day (ZERO_PLUGIN_AUTOUPDATE=0 disables).
  • UserPromptSubmit — adds a one-line reminder that Zero is available for tasks beyond the agent's built-in abilities
  • PreToolUse — auto-approves read-only zero subcommands (search, get, review, …). zero fetch (spends money) and zero wallet are never auto-approved; those always go through the harness's normal permission prompt.

What zero init does

Runs automatically at the end of the npm and fallback install paths (the plugin-manager rows integrate through the harness's own installer instead). It:

• writes the Zero skill into every well-known agent-skill directory it finds on the machine (currently includes ~/.claude/skills/ and ~/.agents/skills/, and others as harnesses are added — see supported paths for the current list)
• registers hook scripts in the config file of any harness it detects with its own hook system (e.g. ~/.claude/settings.json)

It prints each file it writes as it goes. zero uninstall reverses all of it.

Read the skill file now

Skills normally load at session start, so the session that just ran the install can't see the skill it installed yet. Read it now instead of waiting for a reload or a new session:

• npm / fallback path: zero init's output names the file it wrote — read whichever matches your harness, e.g. ~/.claude/skills/zero/SKILL.md or ~/.agents/skills/zero/SKILL.md.
• Plugin-manager path: the skill ships inside the installed plugin at skills/zero/SKILL.md under the plugin's install root.

That file is the day-to-day usage guide — the same one the harness loads at the start of future sessions. Reading it now just brings this session up to parity with the next one.

Authenticate

Already signed in? zero auth whoami --json shows a user object when a sign-in exists — if so, skip to Try it.

Both paths below create a free account. Account creation cannot make purchases.

Interactive (a person is present to approve a browser sign-in) — device-code sign-in, the same pattern as gh auth login:

zero auth login --start --json      # prints a url + code
zero auth login --finish <code> --json   # waits for browser approval

Whoever is signing in opens the URL, enters the code, and approves in their browser. --finish polls until the sign-in is approved (expected, not a hang), and re-running it with the same code is safe.

Unattended (sandboxes, CI — no one available for a browser step):

zero auth agent register --json

Output includes "balance": 0, "payment_method": null — the account exists but can't purchase anything until a person funds it. A person can take ownership of the account later with zero auth agent claim <email>.

Check balance / add funds

zero wallet balance --json

Funds can only be added by a person in a browser; no CLI command adds funds directly. If the balance is 0 and a paid capability is needed, the account owner runs:

zero wallet fund --start --json     # same device-code pattern as sign-in

and completes payment-method setup and the amount in the browser. This is the same regardless of which auth path created the account.

Try it

zero search "<capability you need>"
zero fetch <result-id>

A good first task if you don't have one in mind: build a small site and host it with Zero.

Fallback installer

Only needed with no npm and no supported plugin manager. Installs Node (only if the system doesn't have v20+) and the CLI into ~/.zero/runtime/, adds zero to PATH for this shell, then runs zero init (see above). The script is plain shell; source is in the zero-plugins repo.

curl -fsSL https://www.zero.xyz/install.sh -o /tmp/zero-install.sh
bash /tmp/zero-install.sh

Re-run to update. zero uninstall reverses everything either path wrote.