Feature

AI-First Design

Ze uses shared registrations to describe commands and configuration. The CLI, MCP and other operator interfaces read this metadata for the surfaces they support. AI tools can discover the command catalog, call daemon commands and read structured output while helping an operator use or debug the system.

Shared Registrations

The core design point is broader than AI. A feature added to Ze should avoid separate hand-written glue for every surface. The same registration path can feed the CLI, SSH sessions, the web workbench, REST/gRPC, MCP, generated references, completion, authorization, audit, and diagnostics.

CLI commands as the API surface

The CLI and MCP use the same command catalog and daemon dispatcher, with availability determined by each command's registration. Offline commands may have a different daemon path, interactive views require a terminal, and streaming-only commands are excluded from one-shot surfaces. A shared catalog therefore describes which commands each interface offers; it does not promise that every CLI interaction has an equivalent MCP call.

Self-Describing Command Reference

ze help command              # full command catalog, filterable
ze help command bgp          # filter to BGP-related commands
ze help command --json       # machine-readable JSON (for tooling, wiki generation)
ze help ai                   # AI-oriented summary with recipes and context
ze help ai --json            # machine-readable JSON reference
ze help ai api               # daemon API endpoints (ze-bgp:*, ze-iface:*, ...)

The command and RPC listings are assembled from the binary's plugin registry, YANG schemas and command registrations. Generation removes a separately maintained list of those definitions. Descriptions can still be wrong, and the hand-written recipes need updating when command behavior changes.

ze help command is the human-facing catalog. The native ./le cli catalog update file <destination> action renders the corresponding Markdown from the live registries.

Both commands are served by the daemon too, so ze cli -c, SSH, REST, gRPC, MCP and the web reach them, under show command catalog (help command) and show command reference (help ai): help is an offline root, not a verb, so no daemon command path starts with it. --json, --verbose and -v are flags of the local ze help command only. On every other surface show command catalog answers its catalog rows as data: it prints the table, and show command catalog bgp | json gives the same rows as JSON. show command reference answers its Markdown page as text, and the structured reference is the MCP ze_reference tool. A bare word means the same on every surface: help command json filters on the word json, and help ai json prints the summary.

Structured Diagnostics

ze cli -c "show config validation <file> | json"
ze show diagnostic [--json] <diagnostic-code>
ze config fix --plan <file>

The validation verdict is a record the pipe layer renders, so | json, | yaml and | table are three views of one payload and no command carries a rendering flag of its own. The fix plan prints for a reader.

Config validation emits diagnostic records with a code, severity and message. Source spans, expected/actual facts, help and repair metadata are included when the producing check supplies them. Agents must handle their absence.

Codes such as config-parse, config-yang-type and config-listener-conflict identify the kind of failure. ze show diagnostic <code> explains a registered code. The readiness checks ze doctor runs report codes from the same table, which the package owning each dependency declares: the DNS resolver's doctor-dns-resolver-port-unavailable (a listener port the system will not let ze bind) and doctor-dns-resolver-upstream-unreachable (no forward server answers a probe), for example.

ze config fix --plan <file> reports candidate repairs without editing files. Where a repair is available, its diagnostic can carry a stable repair ID and a safety label such as format-only, section-local, behavior-preserving or requires-human-review. A diagnostic does not always have an automatic repair.

A doctor diagnostic can also carry fix: the command or config statement the operator runs to clear the problem, held alone with no label of its own. It is not a repair ID and carries no safety label. The ze doctor text report draws it on a line of its own under the finding, opened by fix:, and JSON carries it under fix when the check names one. An entry of show errors and show warnings carries the same fix key when its producer named the command, and show doctor's row for that event shows it as the fix line.

A transient code a component raises on the report bus (a plugin process that ended unasked, a refused plugin request) is registered by its owner as an event code, so ze show diagnostic <code> describes it and show doctor reports the event under it.

Bundled Skills

ze show skills
ze show skill ze-diagnostics
ze show skill ze --full

The installed binary serves the workflow guides embedded when it was built. They cover diagnostics, config, commands and agent edit loops, so an agent can load the guide relevant to its task without fetching a separate version. Embedding fixes which text the binary serves. It does not check that every example describes the implemented behavior.

Over the daemon (MCP, REST, gRPC, SSH, web) the expanded form is the model's flag leaf full, as in show skill ze full; the local --full means the same.

Setting an agent up

These commands set an AI coding agent up to use Ze. For the step-by-step how-to, with the command's output and the Codex trust step, see Use Ze with an AI agent; this section is the reference.

ze create agent skill
ze show agent skill
ze delete agent skill

At a shell, ze create agent skill writes a stub skill named ze for each agent harness it finds under the home directory: Claude Code's own ~/.claude/skills/ze/SKILL.md (under CLAUDE_CONFIG_DIR when that is set), and the shared ~/.agents/skills/ze/SKILL.md that Codex, OpenCode and Pi read. A harness is found when its configuration directory exists (~/.claude, ~/.codex or CODEX_HOME, ~/.config/opencode, ~/.pi). agent <name> sets up that harness even where its directory does not exist yet; with no harness found and none named, the shared stub is written. The stub's frontmatter is the ze guide's name and description, its first line after that is Ze's marker, and its body tells the agent to run ze show skill ze, so the guide always matches the installed binary.

Ze owns a stub only by that marker line. A second run leaves a current stub untouched (unchanged) and rewrites one an older ze wrote (updated); a SKILL.md without the marker is left as it is (foreign), with the command that replaces it. A link at the ze directory or at its SKILL.md is replaced by Ze's own file and its target is left. Anything else Ze did not write at that place, such as a file where the ze directory belongs, is left as it is (foreign) by every command; a linked skills directory (a dotfiles setup) is followed, and the stub is written in the directory it points at.

ze show agent skill reports, for every harness the plugin knows, whether it was found and the stub's state (current, outdated, missing, foreign), and changes nothing. ze delete agent skill removes a stub Ze wrote and its emptied directory. Without agent it acts on every harness found, as agent all does, and agent <name> limits it to one harness. With one harness named, the shared stub stays while another harness found on the machine still reads it, and the answer names that harness. Each command answers one row per harness and item; the hook rows of OpenCode and Pi answer unsupported, because Ze knows no session-start hook format for them.

For Claude Code and Codex, ze create agent skill also installs a session-start hook: in Claude Code's settings.json (under CLAUDE_CONFIG_DIR when that is set) and in Codex's hooks.json (under CODEX_HOME). Ze appends one group, with no matcher, at the end of hooks.SessionStart. The group holds one entry: type command, command /bin/sh -c 'ze show agent context 2>/dev/null || true' and a timeout of 5 seconds. Both harnesses add the hook's output to the agent's context when a session starts, and the shell makes the hook print nothing and succeed when ze is not on the harness's path. Ze inserts a missing hooks or SessionStart key with the group, and creates a missing file, owner-only, holding the hook list alone. A group is Ze's when it holds one entry whose command runs ze show agent context. A second create leaves Ze's current group as it is (unchanged) and rewrites one an older ze wrote, in place (updated). Every other group, Rex's included, is never touched.

Ze splices its group into the file's own text, in the file's own indentation, so every byte outside that group stays as it was. It refuses a file it does not fully understand and leaves it as it is (refused). That covers text that is not valid JSON, a byte-order mark, a second hooks or SessionStart key, a hooks value that is not an object, a SessionStart value that is not a list, and a group that is not an object. The row then names what was found, at which line and column, and says to correct the file or add the hook by hand. A linked settings file (a dotfiles setup) is written through to the file it finally points at, and the link stays. A dangling link, a link to something other than a regular file, and a file or directory Ze cannot write are refused. The file keeps its permission bits. Ze writes the new content beside the file and replaces the file only if it has not changed since Ze read it. Claude Code rewrites its own settings file, and when that happens in between, the row is refused and says to run the command again.

Codex skips a new or changed hook until its user trusts it, and keeps that trust in its own config.toml, keyed by the hook's position in the file. Ze never writes that store. The Codex row of create says to open Codex, run /hooks, and trust the hook. show agent skill reports the hook as installed (current, outdated, missing or refused), never whether it ran. For Codex it says that Ze cannot see the trust, and how to check it. delete agent skill removes Ze's group and its separating comma, and leaves an emptied SessionStart list or file as it stands. In Codex's file, a group of Ze's that is not the last is emptied in place ({"hooks": []}) instead, because removing it would move every group after it and Codex would no longer trust them.

Through the daemon (ze cli, SSH, REST, gRPC, MCP, web) the three commands read and write nothing on the daemon's host. They answer the files an agent on another machine places or removes in its own home: per harness, the default path relative to the home directory, the state not-inspected and, for create and show, the stub to write. That stub tells the agent to ask the Ze system it is connected to for show skill ze over the connection it already uses, and names no local ze command.

Session context

ze show agent context prints the Ze version, whether the daemon answered a dial bounded to one second, the config directory, and a pointer to ze show skill ze, and it always exits 0. It is the command the session-start hook ze create agent skill installs runs. Through the daemon it answers the version and that the caller reached the daemon, with no directory.

Development-Time Discovery

Feature, tooling, self-check, verification and test-infrastructure changes must update their discovery path in the same work. The standard path is ai/rules/repo-maintenance.md for policy, ai/INDEX.md for keyword lookup, and the relevant native action or docs page for verification and usage.

Agents should use the existing inventory and verification surfaces: ./le repo inventory, ./le cli list, ./le doc check all, ./le doc index update, and ./le doc wiring.

./le commit create prepares a commit: agents supply the vetted subject, body and explicit file list, and the helper validates the selected content and writes a message file and executable script. Preparation leaves the shared Git index untouched. Running the generated script creates and publishes the commit using a private index.

The script checks whether another commit changed a selected path since preparation. It builds on a parent read for that attempt and publishes with a compare-and-swap against that parent. If HEAD moved elsewhere, it rechecks the selected paths and rebuilds on the new parent, for at most five attempts.

MCP Transport

The MCP (Model Context Protocol) server exposes daemon command calls through the shared dispatcher:

Tool Description
ze_execute Dispatch a daemon command string, subject to the caller's permissions and the command's supported surface
ze_reference Reference assembled from this binary's registries and schemas; the same data as ze help ai --json
Generated tools Command groups named from their registered paths, with an action enum where the group has named actions

The server builds generated tools from the live command list at tools/list time. YANG RPC input metadata supplies typed parameters when it is available; groups without typed parameters expose a generic arguments string. Tool names and grouping depend on the registered command population, so clients should read the live tool inventory rather than assume a route-specific tool such as ze_announce or ze_withdraw exists.

ze_execute accepts the same daemon command grammar as other command callers. It does not turn offline file operations, interactive terminal views or event subscriptions into equivalent MCP operations. The presence of notification metadata in ze_reference describes the schema, and does not by itself provide an event subscription.

Start with ze start --mcp <port> or configure via YANG (environment/mcp).

What Makes This Different

Other software adds an API endpoint and expects operators to build separate wrappers, UI, documentation, and automation around it. Ze exposes its command surface through a self-describing interface that tools can discover at runtime. ze help command lists the commands this binary carries with their descriptions. ze help ai adds context such as recipes, families and update syntax. Generated MCP tools use typed parameters where the registrations provide them and generic arguments otherwise. system command list reads the running daemon's builtin and plugin-declared command registries; system command help name "<path>" reads a command's help. The separate show command list lists builtins; show command help <path> can resolve both registries.

The useful property is the shared surface: when a plugin or subsystem registers commands, YANG, RPCs, or events, the same metadata can feed CLI, web, generated references, automation, authorization, audit, and diagnostics.

See MCP Guide for configuration and MCP Remote Access for tunneling.