# Agent instructions > 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. Section: Reference Canonical: https://gno.sh/docs/agents-install Markdown: https://gno.sh/docs/agents-install.md 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 , --extra-dir (repeatable), --json # install, update, uninstall: --dry-run prints a unified diff and writes nothing ``` ## Harness matrix: who reads which file Detection 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. | ### Evidence behind the matrix - **File locations and fresh-session behavior:** a hand-managed reference deployment across three hosts and all seven harnesses (2026-09). In each harness a fresh session asked for its loaded knowledge protocol described the GNO retrieval ladder. That deployment decided the matrix; the installer generalizes it. - **The installer itself:** the release test suite runs the real CLI against an isolated home with every harness directory present: fresh install, idempotent re-run, `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. - **Hermes Agent and OpenClaw:** the memory adapters (separate from the block) were verified live: the Hermes provider against Hermes v0.20.5 on a real host, the OpenClaw plugin against OpenClaw 2026.8.1 in an isolated sandbox workspace. See [Memory: adapters](https://gno.sh/docs/memory#adapters). Import-chain dedupe is data in the matrix (Grok to Claude today), so a future chain is one more row in the matrix. ## Markers and the version stamp ``` ...ladder + writing contract... ``` - **Markers are stable across versions.** `` and `` never change once shipped, so a block installed by any release is found by every later one. - **The stamp carries the content version and a hash.** The block body is static: identical on every machine, with no filesystem paths. A block is current exactly when its stamp version matches the installed release and the hash matches its body. At v3 the body is 1,491 characters, under the 1,500-character budget the test suite enforces. - **Owned block only.** Install, update, and uninstall touch the text between the markers and nothing else. A fresh install appends the block after one blank line; uninstall removes the block and that blank line. Edits inside the markers are overwritten on the next update; your conventions live outside them. - **Malformed markers fail closed.** Zero or one of each marker is a clean state; any other count, or an END before a BEGIN, is an error with guidance. The installer never guesses or repairs. ### What verify reports `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. ## Installer guarantees - **Backup-first, atomic.** An existing file is copied to `.gno-agents.bak.` 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. - **Idempotent.** Re-running when the block is current writes nothing and creates no backup. - **Fail-closed with a manual fallback.** Malformed or duplicate markers, a file that is not valid UTF-8, or an unwritable file produce a per-target error and no write; the command then prints the complete block for you to paste (`manualBlock` in `--json`). Other targets proceed. - **Symlink-aware.** Writes go through the resolved real file, so one canonical file linked into several harnesses survives and is written once; the other targets report `covered via (same file)`. - **No fabricated trees.** An undetected harness is skipped. The installer creates the instruction file when a detected harness lacks one; it never creates harness directories. - **Encoding preserved.** A leading UTF-8 BOM and CRLF line endings outside the markers survive every operation. ## Nonstandard and multi-instance layouts 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-cli ``` ## What the block teaches The block is the routing contract; the workflows stay in the [gno skill](https://gno.sh/docs/skills). Version 3 teaches the retrieval ladder, scoped to a collection first: 1. Exact term, identifier, quote, or error: `gno search` 2. What do we know or believe (memory): `gno recall "" --scope `, current facts, cited 3. Entity or known document: `gno query "" --fast -n 10` 4. Multi-document evidence: `gno context build "" --budget 12000` 5. Change and dependency questions: `gno changes`, `gno diff`, `gno impact` 6. Generated factual answer: `gno ask "" --verify` (abstention is valid) 7. Expected document missing: `gno query diagnose` with a target, and a scope re-check, before any grep Then 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 --predecessor-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](https://gno.sh/docs/protocol) page. ## Versions and migration 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. ## Multiple machines 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.