Use Ze with an AI agent
If you test Ze with Claude Code or Codex, one command sets the agent up. It
installs a skill named ze that sends the agent to the guide your installed
ze serves, so the agent works from the version you run. For Claude Code and
Codex it also adds a hook, so every new session starts knowing the Ze version,
whether the daemon answers, and where the configuration is.
Ze is pre-release software. Give the agent a lab, not a live network.
Before you start
ze must be installed on the machine the agent runs on, and on the path the
agent sees: the skill and the hook both run ze. To build and install it, see
Quick Start. Check with ze version.
Set the agent up
Run the command as the user who runs the agent, on the machine the agent runs on:
$ ze create agent skill
Ze set the ze skill up for each harness below. A refused row names its fix.
claude skill: created (harness found)
/home/you/.claude/skills/ze/SKILL.md
claude hook: created (harness found)
/home/you/.claude/settings.json
codex skill: created (harness found)
/home/you/.agents/skills/ze/SKILL.md
Codex, OpenCode and Pi all read this one file.
codex hook: created (harness found)
/home/you/.codex/hooks.json
Codex skips a new or changed hook until you trust it. To trust it, open Codex, run /hooks, and trust the hook that runs ze show agent context.
Ze sets up each harness whose configuration directory exists: ~/.claude for
Claude Code, ~/.codex for Codex, ~/.config/opencode for OpenCode and ~/.pi
for Pi. To set up one harness before its directory exists, name it:
ze create agent skill agent codex. When Ze finds no harness, it writes only
the shared skill and says so. The command exits 1 when a row is refused, and
the row names the fix.
Trust the hook in Codex
Codex does not run a new or changed hook until you trust it. Open Codex, run
/hooks, and trust the hook that runs ze show agent context. Do this again
when a later ze create agent skill updates the hook. Ze never writes Codex's
trust store, so ze show agent skill can say the hook is installed, but it can
not say whether Codex trusts it.
What to ask the agent first
Ask it to use the ze skill, for example "use the ze skill and check my
configuration". The agent reads the guide itself: the skill sends it to
ze show skill ze, the guide built into your ze, which names the entry
points (configuration validation, diagnostic codes, repair plans and the
command reference from ze help ai --json). ze show skills lists the other
guides the binary carries, and the agent loads the one its task needs with
ze show skill <name>. The guides come from the binary, so they change when
you upgrade it.
What changed on your machine
| File | What Ze put there |
|---|---|
~/.claude/skills/ze/SKILL.md |
The ze skill, for Claude Code |
~/.claude/settings.json |
A session-start hook that runs ze show agent context |
~/.agents/skills/ze/SKILL.md |
The ze skill that Codex, OpenCode and Pi read |
~/.codex/hooks.json |
The same session-start hook, for Codex |
When CLAUDE_CONFIG_DIR is set, both Claude Code files are under that
directory. When CODEX_HOME is set, only Codex's hooks.json moves there: the
skill Codex reads stays at ~/.agents/skills/ze/SKILL.md. Ze adds its hook to
the settings file and leaves the rest of the file as it was. OpenCode and Pi
get the skill only, because Ze knows no session-start hook format for them.
At each session start, the hook adds a few lines like these to the agent's context:
ze dev (built unknown)
daemon: not answering at 127.0.0.1:2222 (dial tcp 127.0.0.1:2222: connect: connection refused)
config directory: /etc/ze
guide: the ze skill, read it with ze show skill ze
The hook waits at most one second for the daemon and always succeeds. When
ze is not on the path the harness sees, the hook prints nothing and the
session starts as usual.
Check the setup
ze show agent skill
It reports, for each harness Ze knows, whether Ze found it and the state of its
skill and hook. It changes nothing. Run ze create agent skill again after you
upgrade Ze: it rewrites what an older version wrote and leaves a current setup
as it is.
Remove the setup
ze delete agent skill
It removes only what Ze wrote: a skill file Ze did not write and every hook Ze
did not add stay as they are. Without agent it acts on every harness Ze
finds, and agent <name> limits it to one. When you name one harness, the
shared skill under ~/.agents stays while another harness on the machine
still reads it.
An agent that reaches a remote router
When the agent runs on another machine and reaches Ze over MCP, REST, gRPC,
SSH or the web, send the same commands over that connection, for example
create agent skill through the ze_execute MCP tool. The router reads and
writes nothing. It answers, for each harness, the path relative to your home
directory and the skill to write there, on the agent's machine. That skill
tells the agent to ask the Ze system it is connected to for show skill ze
over the connection it already uses. There is no hook, because the hook needs
a local ze. To connect an agent over MCP, see MCP Integration.
Details
The full behavior of each command (every state a row can answer, how Ze edits the settings files, what it refuses) is in Setting an agent up and Session context. The command reference has one entry per command: create agent skill, show agent skill, delete agent skill and show agent context.