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. An agent home mind links items into: the directory holding skills/, agents/, and rules/. The default lobe is ~/.claude; you can add Gemini, Codex, 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 prefix, and policy for an enterprise managed policy. The full behavioral spec is at spec/.

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. -n / --no-tui or --json, or a piped or redirected stdout, prints the listing instead.

Selecting items (globs)

learn, forget, upgrade, unmeld, probe, and recall all accept a glob in place of an exact item ref. 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.

Filtering with –kind and –source

recall and probe accept two composable filters:

• --kind <skill|agent|rule|tool> narrows to one item kind.
• --source <selector> narrows to items from a matching source. The selector is an exact name, an unambiguous trailing suffix (repo or owner/repo), 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. Read-only verbs (recall, probe, introspect) emit their existing JSON shapes. Every mutating verb (meld, learn, forget, sync, upgrade, unmeld, config lobes add/remove) emits a structured result object with at minimum action, target, and outcome fields (CLI-153).

Exit status

Exit 0 on success. Any MindError is printed to stderr and exits non-zero (CLI-100).

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).

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. This executes arbitrary code from the source; only use it for sources you trust (HOOK-22).

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: prefix (as), scan roots, and the resolved commit pin (DUMP-4).

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).