grim-usage

Grim Usage

Grimoire (binary: grim) is a package manager for AI-agent configuration. It distributes six artifact kinds — skills, rules, agents, MCP servers, hooks, and bundles — through any standard OCI registry (GHCR, Docker Hub, a private Distribution), with lockfile-pinned installs into a growing fleet of AI clients plus a vendor-neutral agents target. The current names are listed in references/registries.md; the set grows every minor release, so read it there rather than assuming. An MCP server artifact installs by registering an entry in each client's native MCP config file (never as a file of its own); uninstall removes only that entry, never the file.

Not every client can host every kind: a skill is the one kind every client hosts, but a rule needs a per-file scoping surface, an agent needs a shipped file format, and an MCP server needs a config file grim can splice — and many clients lack one or more of those. Where a client cannot faithfully host a kind, grim warns and skips it, writing zero files. Most of the fleet declines rules, but agents are hosted by a majority of clients (12 of the 18 supported clients), and the skills-only clients mostly write no MCP config either — except Cline (global scope only), Droid, and Warp. The authoritative per-client support matrix is the [Client Compatibility][clients] docs page — trust it over this summary, and check it rather than assuming.

Hooks are experimental and off by default. The kind publishes, resolves, locks, installs, and reports today; arming is gated twice: options.experimental.hooks must be true (false unless you set it, config-only — no environment variable overrides it) and the workspace must have consented (grim hook allow, grim add, or an accepted prompt; global scope is always consented). grim install and grim update never grant consent. So adding a hook gives you a declaration, a lock pin, and a materialized payload tree, and nothing fires until both gates clear. grim hook list is the surface for inspecting what you have. Full picture: references/consume.md; a hook that stays silent: references/troubleshooting.md.

Two consequences of that shape are worth knowing before your first install. When nothing is detected, grim targets the generic agents client — one copy into the shared .agents/skills pool — rather than writing a directory for every client it knows about; a lock holding only rules, agents, or MCP servers then has nowhere to go and exits 78. And a client that reads that shared pool can be moved into it deliberately with options.vendors.<name>.shared_skills. Both in references/registries.md.