Grimoire for VS Code

A marketplace UI for grim — the OCI-backed package manager for AI artifacts (skills, rules, agents, MCP servers, and bundles). Search the catalog, read the docs, and install, update, and remove artifacts without leaving the editor — the familiar Extensions view, but for the AI artifacts your tools rely on.

What it does

• Browse the catalog — the Browse tab searches every configured registry at once. Filter by kind with the chip row (Skill / Rule / Agent / MCP / Bundle).
• Stay current — once a day Grimoire asks your registries which installed artifacts have newer versions and carries the count on the activity-bar icon and on the Updates tab. The tab lists them; an Update All icon appears in the sidebar's title bar whenever updates are pending and updates them in one click (also always available in the title bar's … menu). Check on demand with Grimoire: Check for Updates, or turn the automatic ones off with the grimoire.checkArtifactUpdates setting — the verdicts already gathered keep counting either way. The update check asks the registries your grimoire.toml names, so it is skipped in a restricted (untrusted) workspace and starts as soon as you trust the folder. The command is deliberately not gated that way: running it yourself is the go-ahead.
• See what you have — the Installed tab lists your installed artifacts, with a Project / Global toggle to switch which scope's list you're looking at. A status line pinned below the list shows when the catalog was last synced.
• Read before you install — open any artifact in an editor tab with README, CONTENTS, and CHANGELOG tabs and a metadata rail (installation status, package info, source and license, keywords). Single-click opens a reusable preview tab; double-click pins it, and links between artifacts navigate in place.
• Instant details — reopening an artifact paints immediately from an on-disk cache and refreshes in the background; the Browse rows you can see are prefetched as you scroll, so opens feel instant and card logos appear as they load.
• Install, update, and uninstall per scope — install into your project (grimoire.toml in the workspace) or globally (~/.grimoire), or both at once — a project install shadows the global one. Artifacts pulled in by a bundle point back to their bundle instead of offering a direct uninstall.
• Pick a version — install, downgrade, or pin an exact tag from the details header or a card's menu.
• Recover from a blocked install — when grim refuses to overwrite local changes, Grimoire offers an Overwrite confirm instead of a bare error. A refusal it can never safely force — a recorded path resolving outside its anchor root — points you at Show Output and the uninstall-then-reinstall fix instead. A whole-scope run that stops for the same reason (Update All, or Complete Install) never offers a one-click overwrite, because forcing it would discard your edits to every other artifact in the scope: it names the modified artifact and offers to open it, so you can decide one at a time.
• Finish an incomplete install — when an artifact is installed and intact but grim would still write something for it (a client that gained support since the last install, or a render-layout move), the row shows an Install incomplete hint and a Complete Install action that re-materializes that scope's lock.
• Share a link — copy a vscode:// deep link to any artifact; opening it reveals that artifact's details.
• Upvote from the web — an index site can link vscode://grimoire-rs.grimoire-vscode/vote?repo=<url-encoded repo>. It opens the artifact and asks to upvote it; the vote is a public post on the index's forge thread under your own account, so it only happens after you confirm the dialog naming the artifact. Needs grim 0.14.0 or newer. A link can only cast a vote — retracting one stays a button in the details panel.
• Get grim automatically — if grim isn't on your PATH, Grimoire offers to download the latest release from GitHub (checksum-verified).
• Stay up to date — once a day Grimoire checks GitHub for a newer grim release. If it manages the binary it offers a one-click update; otherwise it links the release page. Turn it off with grimoire.checkForUpdates.
• Live refresh — watches grimoire.toml / grimoire.lock and refreshes the views when things change on disk, so the UI stays in sync with the grim CLI and its terminal UI (TUI).
• Configure grim itself — the $(settings-gear) icon opens a Settings editor tab with Project / Global peer tabs for every grim config key (registry, clients, TUI defaults, …) and registry management, backed directly by grim config/grim config registry — no separate copy of the config to keep in sync.

Installing artifacts runs the grim executable, so Grimoire's install actions require a trusted workspace.

Commands

Run from the Command Palette (all under the Grimoire category).

grimoire.openDetails is intentionally omitted from the palette — it is invoked via the vscode:// deep link.

Settings

Requirements

Grimoire drives the grim CLI — it doesn't reimplement it. If grim isn't found on your PATH, Grimoire offers to install the latest release for you; you can also point grimoire.path.executable at an existing build.

Grimoire requires grim 0.11.0 or newer — the release that ships the forceable/anchor-escape error contract behind the overwrite-confirm and anchor-escape recovery dialogs.

An older grim does not blank the view: browsing keeps working off the catalog, behind a banner naming the reason. What it cannot do is report install state, so every install and update affordance is suppressed rather than claiming "Install" on an artifact that may already be installed. Point grimoire.path.executable at a current build, or run Grimoire: Show Info to see which binary is actually being spawned.

Editing a registry in place needs grim 0.13.0 or newer — the release that ships the config registry set verb, the --include/--exclude browse filters on config registry add, and the per-registry --insecure plain-HTTP opt-in.

Below that version the feature is absent rather than reduced: registry rows carry no edit button, the add-registry form shows neither pattern fields nor the plain-HTTP checkbox, and a share link that carries filters is refused outright instead of adding the registry without the filters you approved. Adding, removing, and switching the default registry are unaffected.

A registry declared with insecure = true is contacted over plain HTTP — for a local or in-cluster registry without TLS. The panel marks such a row, because grimoire.toml is normally committed and the downgrade applies to everyone who clones the project. GRIM_INSECURE_REGISTRIES (via grimoire.extraEnv) still covers hosts no entry declares; the two add up.

Contributing

Bug reports, feature requests, and PRs welcome. See CONTRIBUTING.md for the development setup, build/test workflow, and conventions.

License

Apache-2.0