gno agents install keeps one versioned, marker-managed GNO protocol block in the global instruction file of every harness on the machine: the harness matrix with its evidence, what the markers and the version stamp guarantee, and what the block teaches.
An agent uses GNO when its instruction file tells it how, and a hand-pasted paragraph falls behind the CLI it describes. gno agents install writes one compact protocol block, bounded by stable markers and stamped with a version and a content hash, into the global (user-scope) instruction file of every harness it detects. verify compares the stamp against the installed release, update replaces an older block in place, and uninstall removes block and markers. Everything outside the markers is yours and stays byte-identical.
The block is a knowledge protocol you configure, not a note-taking convention: it names the commands and their order, and it names no collection, no path, and no folder layout. Which collections exist, which scopes memory uses, and which harnesses receive the block are your settings.
gno agents install # every harness detected on this machine
gno agents verify # deterministic per-target checks
gno agents update # refresh after a gno upgrade
gno agents uninstall # remove block and markers
# every verb: --target <harness|all>, --extra-dir <path> (repeatable), --json
# install, update, uninstall: --dry-run prints a unified diff and writes nothingDetection is the presence of the harness's standard config directory. Only documented locations are discovered; nonstandard and multi-instance layouts are served by --extra-dir.
| Harness | Target id | Global instruction file | Detected by | Notes |
|---|---|---|---|---|
| Claude Code | claude | ~/.claude/CLAUDE.md | ~/.claude | Honors CLAUDE_CONFIG_DIR when set. |
| Codex | codex | ~/.codex/AGENTS.md | ~/.codex | Honors CODEX_HOME when set. |
| Cursor Agent | cursor | ~/AGENTS.md | ~/.cursor | The CLI discovers AGENTS.md walking from the working directory toward home. |
| OpenCode | opencode | ~/.config/opencode/AGENTS.md | ~/.config/opencode | |
| Grok Build | grok | imports the Claude global file | ~/.grok | grok inspect shows the import; the installer reports covered via claude and writes no second block. |
| Hermes Agent | hermes | ~/.hermes/SOUL.md | ~/.hermes | A marker-managed block inside your own SOUL.md. |
| OpenClaw | openclaw | ~/.openclaw/workspace/AGENTS.md | ~/.openclaw/workspace | Existing workspaces only. |
verify, in-place migration of an older block, and an uninstall that leaves the file byte-identical, hash-checked. The same suite covers the Grok import chain, --extra-dir, symlinked files, a UTF-8 BOM with CRLF content, refusal of a file that is not valid UTF-8, malformed markers, and an unwritable target. The live verification of the shipped installer ran in that isolated home, not against an operator's production instruction files.Import-chain dedupe is data in the matrix (Grok to Claude today), so a future chain is one more row in the matrix.
<!-- gno:agents:begin -->
<!-- gno-agents block v3 sha256:<16 hex> — managed by `gno agents`; manual edits inside the markers are overwritten -->
...ladder + writing contract...
<!-- gno:agents:end --><!-- gno:agents:begin --> and <!-- gno:agents:end --> never change once shipped, so a block installed by any release is found by every later one.gno agents verify is deterministic: exactly one marker block per target, stamp version and hash equal to the installed release. Per target it reports one of ok, outdated (older version or a body that no longer matches its hash), missing (no file or no block), malformed, error (the file could not be read), covered (another target owns the same file, via an import chain or a shared real file), or not-detected. Exit code 1 on any outdated, missing, or malformed target; exit 2 when the only failures are unreadable files. Install and update report per-target actions the same way: install, update, current, covered, not-detected, error; uninstall reports remove or absent.
A behavioral check stays a manual operator practice: after installing, start a fresh session in each harness and ask for the loaded knowledge protocol. The agent should describe the GNO retrieval ladder. Verification in this release is deterministic only.
<file>.gno-agents.bak.<timestamp> with the same permission mode; the new content lands through a temp file and an atomic rename, so a failed write leaves the live file untouched.manualBlock in --json). Other targets proceed.covered via <target> (same file).Several config directories of one harness on one machine are served by the explicit, repeatable flag; discovery never guesses at them. Inside an extra directory the installer manages the first existing of CLAUDE.md, AGENTS.md, SOUL.md, and creates AGENTS.md when none exists. The directory itself must exist.
gno agents install \
--extra-dir ~/.claude-instances/work-cli \
--extra-dir ~/.claude-instances/sub2-cliThe block is the routing contract; the workflows stay in the gno skill. Version 3 teaches the retrieval ladder, scoped to a collection first:
gno searchgno recall "<query>" --scope <scope>, current facts, citedgno query "<question>" --fast -n 10gno context build "<goal>" --budget 12000gno changes, gno diff, gno impactgno ask "<question>" --verify (abstention is valid)gno query diagnose with a target, and a scope re-check, before any grepThen the writing contract in four sentences: retrieve first, since a question alone is read-only; edit an existing canonical note in its source file; gno capture creates genuinely new notes and is never an update API; a fact that may change goes through gno remember, which proposes, with the --add or --supersede <uri> --predecessor-hash <hash> decision taken from a recall. Recalled spans are context, not new facts, so the recall receipt travels back as --receipt. After writes: reindex the collection and verify retrieval. Cite with gno:// URIs. The block closes with one static pointer: load /gno when the skill is installed, otherwise run gno skill install --scope user first.
The generalized version of that contract, with what each rung returns and where each one stops, is the knowledge protocol page.
The block content has shipped in three versions: v1 carried the ladder and the writing contract; v2 replaced a state-aware skill pointer with the static sentence above, so the text is identical on every machine; v3 added the memory rungs (gno recall as rung 2, gno remember with the add/supersede decision and the receipt fence). After a gno upgrade, verify reports outdated and update replaces the block in place, backup first.
The installer is per machine: GNO's index and database are machine-local derived state and never sync. Instruction files may be synced or repo-managed (dotfiles, a private instructions repo, symlink schemes); the installer writes through symlinks and its marker-managed block survives file-level sync. Run gno agents verify on each machine after syncing.