# claude-code The operator's agent on a machine (novox/hq design 36): its package, its machine-wide managed configuration, and the consumer side of the Anthropic licence manager (design 39, ADR 0183). ## What it owns Two directories, declared, so the mesh refuses a second module owning either: - `/etc/claude-code`, the agent's machine-wide managed directory, root's, `0755`. - `~/.claude` under the operator account's home, the operator's, `0700`. The module owns the directory — that it exists, who owns it, its mode — and of what is inside only what it writes. Everything else in it (memory, history, projects, local settings, a person's own rules and skills) is the person's and is never read or written (hq ADR 0182). Unassigned, the module leaves the directory: the host removes a directory only when it is empty. ## What it writes Under the agent's managed directory, `/etc/claude-code`, owned whole by this module and rewritten whenever the node's tool runtime collects the module's tools: | file | holds | |---|---| | `managed-mcp.json` | the tool servers every session loads: the mesh's console as `mesh`, and the servers set in this module's `mcp_servers` setting. **Exclusive**: a server not listed here does not load — not one added with `claude mcp add`, not a project's `.mcp.json`, not a plugin's | | `managed-settings.json` | the keys set in this module's `managed_settings` setting — at the controller's terminal alone (hq issue 340) — under the mesh's own keys: the repositories' attribution convention, the claude.ai connectors kept beside the managed servers, the key-helper while the node holds an API-key licence, and the two that name the `nox-mesh` marketplace and enable its plugin | | `CLAUDE.md` | how a session on this mesh works, this node's name and role, the conventions, the **"instead of" table** — then the instruction sections registered for every node and for this one | | `marketplace/` | the `nox-mesh` plugin (hq ADR 0216): the skills, subagents, commands and output styles registered for every node and for this one, offered in a session as `nox-mesh:` — and the **guard on the agent's shell** (`guard/`), the mesh's own hook and the plugin's only one (hq issue 340). Replaced whole, staged beside and swapped in | Under the operator's home: `~/.claude/.credentials.json`, only when the licence manager hands this node a subscription token; and what is registered at the **home** scope for this node — a skill, subagent, command, output style, or instructions as a rule file — each path recorded in the module's state (`home-placed.json`). It writes, changes and removes only those — never a path the person made, even one with the same content, and never through a directory that is a symbolic link. A placed file changed by hand is left alone, and one the person deleted stays deleted until the item is unregistered (hq ADR 0182). The status tool reads the rest of the home's items to report them; nothing else is read or written. ## Over NATS Everything between this module and the rest of the mesh is NATS, in three kinds: an **event** says that something happened and carries no secret, because a stream keeps it; a **request** carries a token, because nothing keeps it (hq design 32 §10); and **state** is the current value of something every node must see, a node that joins later included — kept, so it carries no secret either (hq ADR 0201). | what | how | |---|---| | what this node holds | the module's `holdings` state, one key for this node — the account, the kind, fingerprints and expiries, never a token — written at start and whenever the credentials file changes (hq ADR 0206) | | a person ran `/login` here | the credentials file gains a refresh token this module never writes; its next report shows it, and the licence manager asks `claude_code_grant` for it, giving its key — the one time a refresh token leaves the node, for the manager to adopt by refreshing it | | what this node should hold | the licence manager's `bindings` state, this node's key; on a newer generation this module asks `anthropic-licence-manager.current` for its token, sealed to the key it sends, and writes it access-token-only — so the agent here never refreshes. A node that was off reads its key when it is back | | an MCP server registered through this module before registering was refused (hq issue 340) | a key in the module's `servers` state — `all.` for every node, `.` for one; every node watches it and renders what applies to it, a node's own entry over the one for every node. A node that joins later, or was off, reads the whole current set at start; unregistering is a delete. Nothing adds a key any more: a new tool server is the operator's, in the `mcp_servers` setting at the controller's terminal | | the agent's configuration (hq ADR 0216) | a key in the module's `config` state per registration — `mesh..` for every node, `node...` for one, `home...` for one account's own directory — the item and its files in one value, at most 256 KiB. Every node watches it and renders what applies to it, a node item over a mesh item of the same kind and name. A hook, settings, or an item that would run something by itself is never taken, whenever it was put there (hq issue 340) | ## The mesh's tools first (hq ADR 0245) The agent kept reaching for `ssh journalctl` while the service manager's `journal` verb existed. So: - **The "instead of" table.** Every seat verb and module tool may say which shell commands it replaces (`replaces`, in the seat's definition or the module's manifest). The module asks the controller — `tools`, `modules`, `nodes`, `node` — at start, every ten minutes and on `claude_code_render`, keeps the answer in its state (`mesh-tools.json`), and renders it into `CLAUDE.md` as one row per seat or module: `/.` and each verb with the commands it replaces. Generated, never written by hand: a verb that gains `replaces` is in the next render. Ordered by what the guard here refused most, then the machines' seats, the modules, the mesh's seats; at most sixteen rows, the rest one `mesh_search` away. - **The guard.** A PreToolUse hook on `Bash`, `Edit`, `Write`, `MultiEdit` and `NotebookEdit`: this module's own binary (`claude-code guard`), copied root's into the plugin with what it judges with (`guard.json`: the machines by name, domain and address, and the replaced commands), run by its path under `/etc/claude-code` so the session cannot change it. It refuses `ssh`, `scp`, `sftp`, `rsync`, `mosh` and `autossh` to a mesh machine (any `*.internal` name, a machine's name or a name under its domains, one of its addresses, as `ssh -G` reads the destination; a jump through one too), writing `/etc/hosts` or `/etc/resolv.conf`, and `HOSTALIASES` — naming the verb that does the job on that machine when one says it replaces the command, and otherwise that a missing tool is created in the module that owns it, never worked around. **Stated, not silent:** an ssh login as `git` is the forge's account, which runs nothing but git, and passes; a git remote is never an ssh command line anyway. - **The operator's override**: `MESH_GUARD_OVERRIDE=`, exported in the operator's own shell before the session starts. It is read from the session's environment as the kernel kept it at exec (`/proc//environ` of the agent's process), so nothing a session does — a command's `export`, a settings `env` key — can set it, and a command naming it is refused outright. Every override and every refusal is a line in the module's `guard.log`; an override that cannot be recorded is not honoured. `claude_code_guard` shows the rules, the data and the record. It is a guard against the habit, not a sandbox: a command written to hide what it runs can hide it, and the record is how a habit that found a way round is seen. ## Tools `claude_code_status`, `claude_code_render`, `claude_code_guard`, `claude_code_pull`, `claude_code_grant` (for the licence manager), `claude_code_mcp_list`, `claude_code_mcp_unregister` (this node by default; `nodes: "all"` or a list for more). **What a session runs or obeys is the operator's, at the controller's terminal** (hq issue 340). A hook, a permission rule, any other managed setting, and a tool server run in, or decide what runs in, every session on the nodes they reach, as whoever starts it — the operator, whose account holds root. The tool runner acts for any caller of the mesh MCP server and is not told who called, so this module cannot tell the operator from an agent confined on another node. So these tools refuse, and say why and how it is done instead: - `claude_code_hook_register`, `claude_code_settings_set`, `claude_code_permission_add`, `claude_code_permission_remove`: the operator sets hooks, permission rules and every other managed setting in this module's `managed_settings` setting, `mesh-controller settings set claude-code '{"managed_settings": {…}}' [--node ]`, typed at the controller's terminal. The controller refuses `managed_settings`, `mcp_servers` and `role` through any verb: a mergeable file asks for every key its own content names; - `claude_code_mcp_register`: the operator sets tool servers in the `mcp_servers` setting the same way; - a skill, subagent or command that would run something by itself: a shell line the agent runs when it loads one (`` !`…` ``, or a block opened with ```` ```! ````), or `hooks`, `mcpServers`, `permissionMode` or `allowed-tools` in its front matter. Front matter is read as YAML (after a byte-order mark, flow style and merged keys included); front matter that does not close, does not parse or is not a mapping is refused rather than guessed at. A skill or command referring to a file with `@` that is not one of its own files is refused too: the agent reads it into the prompt. A script beside a skill is taken: it runs only when the agent runs it, through the session's own rules. What was registered before stays: a tool server is still rendered, and may be unregistered; a hook or settings the state still holds are never rendered, and `claude_code_hook_unregister` and `claude_code_settings_clear` remove them. `claude_code_registrations` lists everything registered, with who registered it, when, and whether it is rendered, beside what the operator set for this node at the terminal. Its `by` is the node whose tool runner served the call, never the caller, whom the runner is not told. **Text for every node or some is set at the controller's terminal too, for now** (hq issue 340, the operator's decision of 2026-10-09; a surface of the operator's own may update it later). Instruction sections, output styles, skills, commands and subagents at the `mesh` or `node` scope are refused through the tools, and the import tool is refused. They are keys of this module's settings, each text a list of its lines, because a setting holds no line break: `instructions`, `output_styles`, `commands` and `agents` map a name to its text; `skills` maps a name to its files, each a list of lines. For example `mesh-controller settings set claude-code '{"instructions": {"conventions": ["Commit in the imperative.", "", "Test before pushing."]}}'`. They land where a registration did, laid over what was registered before; what the operator writes there is not judged, but an item that is not well formed is left out and said in the render's answer. What was registered before is still rendered and may be unregistered. The home scope, the operator account's own `~/.claude` (`nodes`: a list, or `"all"` for every node running claude-code; absent is this node), is still registered through the tools: - for each kind — `skill`, `agent`, `command`, `output_style`, `instructions` — `claude_code__list`, `_register`, `_unregister`. A skill is its files (`files`, or `content` for a lone SKILL.md); - `claude_code_hook_list` and `_unregister`, `claude_code_settings_get` (the managed settings as written, the operator's setting, and what was registered before and is not rendered) and `_clear`; - `claude_code_config_list`, `_show` (one registration in full), `_status` (what applies here, the plugin as written, and the home's own items — which the mesh placed, which share a name with a mesh item, which call a tool server not loaded here) and `_import` (an item of this node's home, registered at a scope; the original stays); - `claude_code_home_show` (`kind`, `name`): one item of this node's home in full — a skill, subagent, command, output style, rule file (`instructions`), or the account's own memory `~/.claude/CLAUDE.md` (`memory`) — and whether the mesh placed it; - `claude_code_home_remove` (`kind`, `name`, `why`): removes one item the person made, on their word — removing it is the person's act, and this tool is that act made explicit. `why` is required; what the mesh placed is refused (its `_unregister` owns it), and so is a symbolic link. A copy is kept first in the module's state, `removed-from-home//