Purpose
Record, once per machine, what the host has and which identity domains it holds, with the observation behind every value, so a plugin setup run starts from observed answers and a kept default says whether anyone looked. The profile drives setups; it never replaces their prerequisite logic. Design and rulings: machine-profile-design, placement in ADR 0041.
Everything here is read-only except two steps the operator confirms in that turn: record --confirm (writes the profile document) and apply --confirm (prints what to hand to each setup; it writes nothing itself).
Actions
<script> is bash "${CLAUDE_SKILL_DIR}/scripts/profile.sh". Every command that reads or writes the store takes --data-dir "${CLAUDE_PLUGIN_DATA}".
- profile (default). Run
/harness-ops:prerequisites, save its table to a scratch file, then run<script> discover --prerequisites <file>and print what it observed: machine facts, then each identity domain with its tree, git include,ghdirectory and verdicts. Offer to record it. On the operator's yes, run<script> record --data-dir ... --confirm <saved discover output>; without--confirmit validates and writes nothing. - diff.
<script> diff --data-dir ... --prerequisites <file>compares the stored document with fresh discovery. Empty output and exit 0 mean nothing changed: say so and ask nothing. Exit 4 lists each difference with both values and bothobserved_byentries. The store cannot tell a hand edit from a host change, so report the difference and do not attribute it. - explain
<key>.<script> explain --data-dir ... <key>prints the stored record and the command or path behind it. - apply
--option <key>. Rundifffirst and show it. Then<script> apply --data-dir ... --option <key>prints the plan. Only after the operator says yes in that turn, add--confirm. Setup skills aredisable-model-invocation: true, so ahandoffline is relayed for the operator to type as/<plugin>:setup; the model does not invoke it. An option recorded under a domain is a per-domain identity: the script reports aconflictand stops for it, and it is never put into the singlepluginConfigsslot.
Exit codes: 0 ok, 1 refused, 2 usage or missing tool (jq), 3 no profile stored, 4 differences found.
Where the profile lives
${CLAUDE_PLUGIN_DATA}/machine-profile/profile.json. The machine section is not project-keyed (it describes the host, the same for every project), which the design ratifies as a deviation from docs/contracts/plugin-data-report-keying rule 1; each domain is keyed by its tree root. A missing document reads as "no profile for this machine" and offers to produce one; there is no fallback path. The document is regenerable from the host, so uninstalling the plugin from its last scope costs a re-run, not data. It holds names, paths and observation commands, and discovery never reads a credential or a sensitive userConfig value. The writer is a backstop for hand-supplied records, not a secret detector: it refuses the key words and value shapes listed under Gotchas, so do not supply a secret that matches neither.
We keep the profile in the plugin data directory, accepting that an uninstall from the last scope can remove it.
- Pointer: when stating where
${CLAUDE_PLUGIN_DATA}resolves or when uninstall removes it, fetch plugin manifest reference: environment variables and plugin uninstall live. As of: 2026-10-11. Recheck trigger: the plugins reference changes the data directory location or its uninstall behavior.
Document shape and verdicts
Records live in machine.facts, machine.options, and per domain in identity, facts and options. Each record has key, value, verdict, and these by verdict:
| Verdict | Meaning | Required |
|---|---|---|
set |
a non-default value is in force | observed_by, mode, supplied_by |
default-verified |
unset; discovery looked | observed_by, mode, observation (including "found nothing") |
default-unexamined |
unset; nothing was looked at | skipped_because, and no observed_by |
blocked |
a guard prevents the change | observed_by, mode, guard with the operator command |
mode is observed or reproduced. A binary whose row in the prerequisites table names a :setup check is reproduced, because that setup is hidden and the profile cannot run its own check. A fact discovery measured directly (a binary present, a path, a core count) is recorded set with the source in supplied_by; absence is default-verified. There is no bare keep, and a value equal to its default is never written to mark it decided. default-unexamined becomes default-verified only through an observation, never through written rationale.
Discovery reads identity domains from the includeIf "gitdir:..." entries in git config --list --show-origin. It attaches a gh directory to a tree only when that tree's own .envrc exports a literal GH_CONFIG_DIR, which it reads as text and never evaluates; otherwise gh_config_dir is default-unexamined and the machine's directory is not copied to the tree.
We attach a gh directory to a tree only through a literal GH_CONFIG_DIR in its .envrc, because we read gh's lookup as naming no directory per working directory. Pointer: when stating where gh finds its configuration directory, read gh help environment live. As of: 2026-11-10. Recheck: that page changes the GH_CONFIG_DIR lookup order.
We treat one pluginConfigs slot as serving the whole machine. Pointer: when stating which scopes pluginConfigs is read from, fetch settings reference: pluginConfigs live; for what claude plugin install --config writes, read facts 5 and 9 of docs/contracts/hook-config-delivery (probes on Claude Code 2.1.292, 2026-10-07, and 2.1.283, 2026-09-27). As of: 2026-11-10. Recheck: the settings guide stops letting --settings set user-scope keys, the documented pluginConfigs scope changes, or --config starts honoring a scope flag.
Next
- A binary row is missing: /harness-ops:prerequisites
- The fleet's plugin versions, a different question: /harness-ops:plugins-audit
Gotchas
Binary facts come only from the prerequisites table. Without --prerequisites, discovery records binaries as default-unexamined and adds no probe of its own, so a diff run without the table reports the per-tool rows as removed.
The writer refuses a record whose key contains token, secret, password, credential, api_key or private_key, and a record whose value looks like a credential: a GitHub, AWS, Slack or sk- token, a JWT, a private-key block, or a URL with an embedded password. A key discovery derives from host text (a binary such as docker-credential-pass, an include path under a token directory) gets the first letter of each such word bracketed, as binary.docker-[c]redential-pass, so the profile still records it. explain needs the bracketed key, and a hand-supplied record keyed api_token is still refused.
diff compares facts and identity only. Option records are stored state that discovery does not observe, so a hand-edited or never-applied option does not show as drift.
record replaces the whole document, so options recorded earlier survive a re-record only when they are merged into the document first.
Discovery reads the effective user and system git configuration from a neutral directory, so the repository the session runs in does not add or hide a domain.
A read-only include file is detected with test -w; an immutable attribute on a file that still looks writable is not.
Do not reapply a stored value from a hook, a session start or a schedule. apply re-asserts a value only when the operator selects it in that run.