Commands

Mental model

mind connects sources (git repos full of agent tooling) and lobes (your agent homes, like ~/.claude/~/.agents).

Source. A melded git repo. mind meld <repo> clones the repo into ~/.mind/sources/<host>/<owner>/<repo> and records it in ~/.mind/sources.json. This initializes the source and makes its items available to mind learn. mind sync (or re-melding, re-running mind meld <repo>) refreshes the clone.

Item. A unit offered by a source, one of four kinds:

• skill - a skills/<name>/ directory containing a SKILL.md and any associated resources (scripts, templates, etc).
• agent - an agents/<name>.md file.
• rule - a rules/<name>.md file.
• tool - a tools/<name>/ directory containing a TOOL.md, a script/executable, any associated resources. Tools are an optional feature to assist with managing and referencing shared scripts/executables utilized by multiple skills.

Items are discovered by convention (the paths above) or declared in a mind.toml.

Lobe. A directory mind links items into: the directory holding skills/, agents/, and rules/. A lobe may be a global agent home (~/.claude, ~/.gemini/config) or a project subdirectory (.windsurf inside a project root). The default lobe is ~/.claude; you can add Gemini, Codex, Windsurf, Antigravity, or any directory, each with an optional per-kind filter (see Configuration). The gemini preset (path ~/.gemini/config) covers both Gemini CLI and the Antigravity IDE. Users of the Antigravity CLI who previously used an antigravity-cli preset should configure a custom lobe path manually.

Learn. mind learn <item> copies the item out of the source clone into the store (~/.mind/store/<kind>/<name>) and symlinks that store copy into every lobe. The store copy is the stable thing your agent homes point at, so a later sync cannot change an installed item under you until you choose to upgrade. forget reverses it.

What each step puts on disk

mind meld jaemk/mind clones the source. Nothing is linked yet:

$ mind meld jaemk/mind

~/.mind/
  sources.json                              # registry: `mind` is now melded
  sources/
    github.com/jaemk/mind/                  # the clone (a staging area)
      examples/hello/skills/hello-mind/     # the offered skill
        SKILL.md
      ...                                   # the rest of the repo
  store/                                    # empty - nothing learned yet

mind probe browses what the melded sources offer before you learn anything (kind:name, source, content hash, description):

$ mind probe

  skill:hello-mind  github.com/jaemk/mind  c62e88cc  A hello-world skill; confirms mind melded this repo

mind learn jaemk/mind#skill:hello-mind copies that one item into the store and symlinks it into the lobe:

$ mind learn jaemk/mind#skill:hello-mind

~/.mind/
  manifest.json                                  # registry: `hello-mind` installed
  store/
    skill/hello-mind/SKILL.md                    # the copy, taken from the clone
  sources/
    github.com/jaemk/mind/ ...                   # clone untouched

~/.claude/                                       # a lobe (agent home)
  skills/
    hello-mind -> ~/.mind/store/skill/hello-mind # symlink the harness discovers

The harness now resolves /hello-mind through that symlink. A tool the skill referenced would instead land in ~/.mind/store/tool/<name> with no symlink under ~/.claude, present for the skill to call but invisible to the harness.

Stay current. sync refreshes every source clone; upgrade moves installed items to the refreshed version, reporting hash and commit deltas before changing anything; evolve updates the mind binary itself.

Inspect. recall and probe show what is installed and what is available; introspect reports drift and broken links.

Verbs

A source repo exposes items by convention (skills/<n>/SKILL.md, agents/<n>.md, rules/<n>.md, tools/<n>/), via a mind.toml, or via a Claude .claude-plugin/ manifest (see Claude plugin marketplaces). See Source layout and the examples/: starter for the plain convention layout, namespacing for {{ns:}} reference tokens under a namespace, and policy for an enterprise managed policy. The full behavioral spec is at spec/.

Verb aliases

Each primary verb has a visible alias for users familiar with conventional package-manager vocabulary. The primary verb is always preferred in docs and scripts.

Note (migration): --link-only on meld is now --register-only; --unlink-only on unmeld is now --keep-items. The old spellings continue to work as hidden deprecated aliases. The config target and unmeld detach aliases are removed.

Note (migration): upgrade now syncs the involved sources before computing deltas (equivalent to running sync then upgrade on those sources). Pass --no-sync to skip the fetch step and get the old behavior. sync --upgrade is kept as deprecated sugar but upgrade alone is the preferred form.

Pinning a source version

meld --pin <value> records how a source tracks upstream. The value is required and decides freeze vs follow:

A freeze records an immutable ref that sync never moves. Freezing a branch or tag snapshots its current tip; it does not keep tracking it. With no --pin, a source follows the remote default branch.

To change a pin later, run meld --pin again against the already-melded source. It resolves the new value against the pin currently in effect, re-checks-out the clone when the commit differs, and records both. Nothing is mutated until every git step has succeeded, so a bad ref leaves the source on its old pin.

Common mistake: --pin stable and --pin branch=stable are different. --pin stable takes a one-time snapshot of stable (frozen; sync never updates it); --pin branch=stable tracks the branch (floating; sync advances it). Use the branch= form to keep following a branch.

# Freeze the current tip.
mind meld owner/repo --pin HEAD

# Freeze a specific point: a tag, a commit sha, or a branch's current tip.
mind meld owner/repo --pin v2.0
mind meld owner/repo --pin a1b2c3d4e5f6...
mind meld owner/repo --pin release-branch

# Follow a moving point. sync advances these to the tip on each run.
mind meld owner/repo --pin branch=stable
mind meld owner/repo --pin tag=latest

A --pin value overrides the repo’s [source] pin directive (see The mind.toml file). --pin requires a value, so a bare --pin is a usage error rather than silently consuming the next argument.

For a deep-link URL, learn --pin (a bare flag on learn) freezes the link’s ref to its current commit in the same step:

# Without --pin the link follows the branch in the URL; with it the link is
# frozen at that branch's current commit.
mind learn https://github.com/owner/repo/tree/main/skills/foo --pin

Note (migration): the old --follow-branch <b> / --pin-tag <t> / --pin-ref <c> flags map to --pin branch=<b> / --pin tag=<t> / --pin <c>. They still work as hidden deprecated aliases.

probe

mind probe with no flags opens an interactive browser of melded sources and items (search, install, remove, meld, unmeld, sync, upgrade) when stdout is a terminal. --no-tui or --json, or a piped or redirected stdout, prints the listing instead.

Selecting items (globs)

learn, forget, upgrade, unmeld, probe, recall, and sync all accept a glob in place of an exact ref or filter argument. The kind prefix, source qualifier, and glob compose:

The glob is matched against the effective (installed) name. A glob matching nothing is ItemNotFound (for items) or SourceNotFound (for sources). The exception is upgrade: a glob (or exact ref) that matches no installed item reports up-to-date rather than erroring, since upgrading nothing is a no-op.

Shell-quoting caveat: quote the glob so the shell does not expand it before mind sees it:

mind learn 'skill:*'
mind forget 'owner/repo#*'

Spec: CLI-31, CLI-41, CLI-65.

Refs vs filters

• Ref must resolve to exactly one target, erroring rather than guessing: unmeld <name> (a non-glob source name; AmbiguousSource), and a bare non-glob item name given to learn/forget/upgrade (AmbiguousItem). Item names are never suffix-matched, so this last case only fires across kinds (the manifest is keyed kind:name), e.g. upgrade greet hitting both skill:greet and agent:greet.
• Filter may match several targets with no ambiguity check, and every match is acted on: sync’s [source], recall/probe’s --source <filter>, hooks run <target>’s source form, and any glob ('*', 'skill:*', 'owner/repo#*') given to any of the verbs above. The embedded owner/repo# source qualifier inside upgrade’s item argument is a filter too, not a ref: it is a trailing-suffix match with no ambiguity check, so it can span several sources, upgrading each one’s items and re-running each one’s install hook.

No-match behavior differs by verb:

• sync <filter> with no match: a hard SourceNotFound error.
• upgrade <filter> with no match: reports up to date and exits 0.
• --source <filter> (recall/probe) with no match: an empty listing.

Item links: install one skill by URL

Paste the URL of a skill directory (or its SKILL.md) straight from GitHub or GitLab and learn installs just that skill:

mind learn https://github.com/owner/repo/tree/main/skills/foo
mind learn https://github.com/owner/repo/blob/main/skills/foo/SKILL.md

The repo registers as its own single-item source instance with the identity host/owner/repo#<path>: it clones, syncs, and upgrades like any source, but offers exactly the linked skill. Several links into the same repo (and a plain meld of it) coexist as separate sources. The URL’s ref supplies the pin: a branch name follows that branch, a 40-hex commit pins it. Add --pin (a bare flag on learn) to freeze a branch-ref link at the branch’s current commit (see Pinning a source version).

Because the consumer names the exact path, the link bypasses the repo’s declared inventory: it reaches a skill an authoritative mind.toml or a .claude-plugin/marketplace.json does not list (see Claude plugin marketplaces).

mind meld <url> accepts the same form and follows the standard meld flow (--register-only, --namespace, pin flags). forget of the skill leaves the instance registered and hints at mind unmeld <identity> to drop it. A local repo is addressable through file:///path/to/repo/tree/<branch>/<path>.

Spec: spec/item-link.md.

Filtering with –kind and –source

recall and probe accept two composable filters:

• --kind <skill|agent|rule|tool> narrows to one item kind.
• --source <filter> narrows to items from a matching source. The filter is an exact name, a trailing suffix (repo or owner/repo; a multi-source match is normal, not an error), or a glob matched against the full host/owner/repo identity (so * spans /):

mind recall --kind skill
mind probe --source '*agents'
mind recall --source my-repo --kind rule

For recall, these filters apply to the installed-items listing only, not to --sources or a single-item lookup. Spec: CLI-83, CLI-86.

Global flags and output

--json, --yes (-y), and --ascii are global flags accepted before or after any verb. Position does not matter: mind --json recall and mind recall --json are equivalent (CLI-150).

Color and Unicode. Output uses ANSI color and Unicode glyphs when all of the following hold: stdout is a TTY, the locale is UTF-8, NO_COLOR is unset, and neither --json nor --ascii is in effect. Any one of those conditions being false forces plain ASCII output with no color escapes. The ASCII fallback substitutes visually equivalent characters (+ installed, ! warning, x error, - available) so no information is lost (CLI-151, CLI-152, CLI-154).

NO_COLOR set to any value (including empty), a non-UTF-8 or unset locale, or --ascii each independently force plain ASCII regardless of the others.

--json output. --json is universal: every verb answers it with exactly one JSON document on stdout, except a closed exclusion list – dump (always emits TOML, CLI-153 does not apply), completions/man (print their script or roff page as the entire output), evolve (writes its own result document from selfupdate.rs rather than through the shared JSON machinery – the document IS JSON, just emitted on a separate path), and init-source (a maintainer scaffolder with no JSON result to offer). Every other verb answers with a document.

recall and probe emit {"schema": 1, "items": [...]}. introspect emits {"schema": 1, "issues": [...], "sources": N, "items": N} where issues is an array of findings and sources/items are integer counts. Every mutating verb (meld, learn, forget, sync, upgrade, unmeld, config lobes add/remove) emits a structured result object with "schema": 1 and at minimum action, target, and outcome fields (CLI-153).

review --json answers with {"schema": 1, "action": "review", "outcome": "clean|advisory|failed", "hard": [...], "advisory": [...], "fixed": [...]}, where hard/advisory are arrays of {"kind": "<slug>", "message": "<text>"} findings and fixed lists the files --fix rewrote. A hard finding still fails review (CLI-132 is unconditional): the document is not printed as a success envelope in that case, but folded into the error envelope’s details member instead (see below).

hooks list --json answers with a document giving each matched source’s or item’s hooks (event, required/optional flag, command, and, for a recorded source install hook, its pending/last-ran status). hooks run --json on a successful run answers with a tally rather than nothing: {"schema": 1, "action": "hooks-run", "target": "...", "event": "...", "existed": N, "ran": N, "skipped": N}.

When an error occurs under --json, the process emits a JSON error envelope on stdout instead of plain text on stderr, then exits 1 (unchanged):

{"schema": 1, "error": {"kind": "item-not-found", "message": "..."}}

The kind field is a stable kebab-case slug per MindError variant (e.g. "item-not-found", "source-not-found", "git", "digest-mismatch"). Scripts may branch on kind to handle specific failures. The message field is the full display text. Exit code is always 1 for runtime errors; clap usage errors (exit 2) remain plain text and are not enveloped (CLI-181, CLI-182, CLI-183).

The envelope carries an optional details member when a verb has more to say than the kind/message pair: a failed review --json records its findings document there instead of printing it as a success envelope (CLI-221).

Exit status

Exit 0 on success. Any MindError exits 1; under --json it is written to stdout as the error envelope above instead of stderr (CLI-100, CLI-181).

sync exits non-zero (SyncFailed) when any per-source fetch fails, even if other sources succeeded; successfully fetched commits are persisted and reported (CLI-54).

review distinguishes hard errors (malformed mind.toml, unknown item kind, unresolved {{ns:}} token) from advisory findings (unguarded references, missing descriptions). Hard errors exit non-zero; advisory-only exits zero. Neither mode writes to disk, except review --fix on a local-path target (CLI-132).

Running unattended / in CI

Pass --yes (-y) to skip confirmation prompts. Without it, any command that would prompt on a TTY instead exits non-zero with ConfirmationRequired when stdin is not a TTY (CLI-23, CLI-42).

meld is the exception: a non-TTY meld without --yes registers the source only, prints a note that nothing was installed, and exits 0. Pass --yes to install its items non-interactively.

Install and uninstall hooks are skipped in non-TTY contexts and a note is printed. To run them unattended, pass --dangerously-skip-install-hook-check (meld/learn/sync/upgrade/hooks run) or --dangerously-skip-hook-check (unmeld/forget, which gate an uninstall hook). This executes arbitrary code from the source; only use it for sources you trust (HOOK-22).

Item build hooks (the per-item build command, distinct from a source’s install hook) are likewise skipped in non-TTY contexts, so an item’s tooling is not built. To run them unattended, pass --dangerously-skip-build-hook-check (available on meld, learn, upgrade, and sync --upgrade). It too executes arbitrary code from the source; only use it for sources you trust.

For an end-to-end CI provisioning recipe, see Team / CI provisioning recipe.

dump

mind dump writes a super-source mind.toml to stdout (or --output <path>) that reproduces the current melded and installed state. Melding the output recreates the same source set at the same revisions. It is the inverse of melding a curated super-source.

mind dump                        # write to stdout
mind dump --output snapshot.toml # write to a file
mind dump --whole-sources        # include all items, not just installed ones

Each entry in the emitted [discover].sources references a melded source and pins it to its currently recorded commit as a pin-ref, overriding any pin the source itself declares (DUMP-1). The meld-time settings are carried through: namespace, scan roots, added roots, and the resolved commit pin (DUMP-4, DUMP-11).

An item link instance is emitted as a deep tree URL rebuilt from its recorded parts, pinned by pin-ref like any other entry, so a skill installed from a pasted URL is reproduced by melding the dump (LNK-13).

Item filtering. By default each source entry is stamped with the install directive that reproduces exactly which items are installed (DUMP-2):

• Every offered item installed: install = true
• No items installed: install = false
• A subset installed: install-items = [...] listing those items by kind:name

--whole-sources disables this filtering and emits install = true for every source, offering the full catalog instead of the recorded subset (DUMP-3).

With no melded sources, dump emits a valid super-source with an empty [discover].sources and exits 0 (DUMP-8).