SkillFoxx

Model Shelf plugin

Claude Code plugin and CLI: before downloading a Hugging Face model the agent checks your local GGUF, MLX and safetensors shelf

  • 128 ★ on the repository
  • Last commit
  • MIT
Plugin

Extended access

Why this level

  • The CLI downloads model files from Hugging Face to disk and installs itself through `uv`.
All reasons and checks

alexziskind1/model-shelfAuthor:alexziskind1

Install

Manual install

/plugin install model-shelf@alexziskind1/model-shelf

The command from the Install section: the plugin adds a skill and a SessionStart hook that installs the CLI.

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

  • The CLI downloads model files from Hugging Face to disk and installs itself through `uv`.

This is third-party code. Review the repository files before installing.

What it does

Model Shelf maintains a local library of Hugging Face models in three formats: GGUF, MLX and safetensors. The command `model-shelf resolve "Qwen/Qwen3-14B-GGUF" --quant Q4_K_M` reports whether the file is on the shelf and returns its path. The format is detected from the repo id. The Claude Code plugin installs a `resolve` skill that makes the agent query the shelf first, plus a SessionStart hook that installs the CLI through `uv` on the first session. On a miss the download lands directly on the shelf at a readable path such as `gguf/Qwen/Qwen3-14B-GGUF/`, with no parallel Hugging Face cache. The layout matches what LM Studio expects. The shelf can live on an external drive, a NAS or an internal folder.

Who it is for. People running local models across several tools and machines who are tired of downloading the same files again.

Good fit when

  • An agent is about to download a model that already sits on an external drive.
  • One model library is shared by LM Studio, llama.cpp and MLX.
  • The shelf sits on a shared NAS mounted on several machines.
  • A drive was renamed or swapped and you do not want to edit paths in settings.

Not a fit when

  • Models are downloaded rarely and kept in the standard Hugging Face cache.
  • You need download locking: two machines pull the same model at once.
  • Models come from somewhere other than Hugging Face.

Example request

Find Qwen3-14B GGUF at Q4_K_M quantization on my shelf and download it only if it is missing.

Limitations

Python 3.11 or later and `uv` are required for the plugin's automatic CLI install. There is no download locking: on a shared shelf do not request the same missing model from two machines at once. If the path for `init` sits under a mount point that is not currently mounted, the command fails loudly instead of creating anything silently. Downloads are on by default (`allow_downloads = true` in `~/.config/model-shelf/config.toml`), so a miss makes the CLI fetch files from Hugging Face onto the shelf, which uses disk space and bandwidth.

How to disable. Disable the plugin in Claude Code and remove the CLI with `uv tool uninstall model-shelf`. Model files on the shelf stay on disk and must be deleted by hand.

FAQ

How do I install Model Shelf in Claude Code?

`/plugin install model-shelf@alexziskind1/model-shelf` installs the skill and hook. The CLI is pulled in through `uv` on the first session.

How do I install it without Claude Code?

Run `uv tool install git+https://github.com/alexziskind1/model-shelf` or `pip install git+https://github.com/alexziskind1/model-shelf`. Python 3.11 or later is required.

What does model-shelf init do?

It finds an external drive with a `ModelShelf/models` folder and uses it silently. Otherwise it shows a drive picker, the internal folder or a custom path.

Is a separate server or protocol needed?

No. One shell command, `model-shelf resolve … --json`, is enough, so any agent that can run shell commands can use it.

Where are models looked up?

First the primary shelf, then every mounted volume with a `ModelShelf/models` folder, then the internal `~/.cache/model-shelf/models`. The first hit wins.

Discussion

No questions or reviews yet.

Plugins
Official

A plugin and MCP server that let Claude Code drive the local Guaardvark AI studio on your own graphics card

PluginBroad access318
Official

A local model server for Apple Silicon Macs in OpenAI, Anthropic and Ollama formats: Claude Code, Codex and OpenCode connect with one command

CLIBroad access2.4K

A Claude Code plugin marketplace with ready sets of agents, slash commands, hooks and skills, plus a search site

PluginExtended access3.7K

A Claude Code plugin that runs one task across several external models and surfaces disagreements before you ship

PluginExtended access4.4K

Local memory for Claude Code, Codex and Cursor Agent: learns from your activity on a Mac and gives agents context with source receipts over MCP

MCP serverBroad access1.3K

Skills, mods, subagents and hooks for Claude Code: the agent inspects your setup and installs what fits after your approval.

SkillExtended access98

README in short

The project solves one task: not downloading models twice. It returns a file path with one command, and the Claude Code plugin builds that check into the agent's routine.

README badge

Original SKILL.md

---
name: resolve
description: Always resolve Hugging Face models via `model-shelf` before any download. Supports GGUF, MLX, and safetensors. Triggers whenever the user asks to load, run, or use a local LLM model (llama.cpp / Ollama / MLX / vLLM / transformers flows).
---

# Resolve a Hugging Face model locally

When the user wants to load, run, or use a Hugging Face model — **always**
go through `model-shelf`. Do not invoke `huggingface-cli download`, `hf
download`, `snapshot_download`, or any other direct download command.

The user does **not** need to give you an exact `org/repo` id. Loose
descriptions ("qwen 3 4b mlx 4-bit", "the latest llama 3.1") are normal
and expected. Do not push back on whether a model exists — your training
data is stale and Model Shelf can search the live Hub.

## Workflow

1. **Decide whether to search first.**
   - If the user gave a clean `org/repo` string (e.g. `Qwen/Qwen3-14B-GGUF`),
     skip to step 2.
   - Otherwise the input is loose — run:
     ```
     model-shelf find "<user's words>" [--format gguf|mlx|safetensors] --json --limit 5
     ```
     Use any format hint from the user (`mlx`, `gguf`, `safetensors`). Pick the
     top result that matches the user's format/quant intent. Use its `repo_id`
     as the input to step 2. If `find` returns nothing, tell the user no
     matching model was found — do **not** invent a repo id.

2. **Resolve the repo to a local path.**
   ```
   model-shelf resolve <repo_id> [--format gguf|mlx|safetensors] [--quant <QUANT>] --json
   ```

   - `--format` is auto-detected from `repo_id` if omitted:
     - `*-GGUF` (case-insensitive) → `gguf`
     - `mlx-community/*` or `*-mlx` → `mlx`
     - everything else → `safetensors`
   - `--quant` is **required for `gguf`** (e.g. `Q4_K_M`); ignored otherwise.

3. **Use the returned `path`** with the user's runtime:
   - **gguf**: file path → `llama.cpp` / `llama-server` / Ollama / LM Studio
   - **mlx**: directory path → `mlx_lm.generate` / `mlx_lm.server` (Apple Silicon)
   - **safetensors**: directory path → `transformers` / `vllm`

4. **Error handling:**
   - If `status == "missing"`, downloads are disabled in their config —
     surface that to the user and stop.
   - If `model-shelf` exits **non-zero with a message on stderr**, surface

Report a problem