[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-83283":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":25,"readmeContent":26,"aiSummary":9,"trendingCount":15,"starSnapshotCount":15,"syncStatus":16,"lastSyncTime":27,"discoverSource":28},83283,"model-shelf","alexziskind1\u002Fmodel-shelf","alexziskind1","Model Shelf is a local-first model resolver that helps AI agents and scripts find model weights on your own storage before downloading from Hugging Face. Point it at an internal SSD, NAS, external SSD, or Thunderbolt DAS, and it returns the best local path for GGUF, MLX, safetensors, Ollama, vLLM, and other local AI workflows.",null,"Python",98,15,64,3,0,2,29,13,64.93,"MIT License",false,"main",true,[],"2026-06-12 04:01:40","# Model Shelf\n\nA local-first resolver for Hugging Face models — GGUF, MLX, and safetensors. Your agent checks your curated library before downloading.\n\n```\n> model-shelf resolve \"Qwen\u002FQwen3-14B-GGUF\" --quant Q4_K_M\n\n  shelf  \u002FVolumes\u002FMyDrive\u002FModelShelf\u002Fmodels\u002Fgguf          HIT\n\n  status      found\n  source      local_shelf\n  format      gguf\n  path        \u002FVolumes\u002FMyDrive\u002FModelShelf\u002Fmodels\u002Fgguf\u002FQwen\u002FQwen3-14B-GGUF\u002FQwen3-14B-Q4_K_M.gguf\n```\n\n## Why\n\nLocal AI workflows download the same model files over and over — across tools, runtimes, and machines. Model Shelf gives you one curated library at a path you own, and one shell command that asks: *do I already have this locally?*\n\n- Handles **GGUF, MLX, and safetensors** through one CLI — format auto-detected from the repo id.\n- **Publisher\u002Frepo layout** that mirrors Hugging Face Hub (and matches LM Studio's expected structure) — `gguf\u002FQwen\u002FQwen3-14B-GGUF\u002FQwen3-14B-Q4_K_M.gguf` instead of `models--Qwen--Qwen3-14B-GGUF\u002Fsnapshots\u002Fabc...\u002F...`.\n- Works with **any** storage you already mount: external SSD, Thunderbolt DAS, NAS, or just an internal folder.\n- Downloads land **directly** in the shelf at the friendly path — no parallel Hugging Face cache to manage or clean up.\n- A single shell command (`model-shelf resolve … --json`) means any agent that can run shell commands can plug it in — no special protocols, no extra server.\n\n## Install\n\n### Claude Code (one command)\n\n```\n\u002Fplugin install model-shelf@alexziskind1\u002Fmodel-shelf\n```\n\nThat's it. The plugin installs a [skill](skills\u002Fresolve\u002FSKILL.md) that tells the agent to always resolve through Model Shelf, plus a SessionStart hook that auto-installs the CLI via `uv` on first session. Requires [`uv`](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F) — install with `curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh` if you don't have it.\n\n### Anywhere else\n\n```bash\nuv tool install git+https:\u002F\u002Fgithub.com\u002Falexziskind1\u002Fmodel-shelf\n# or\npip install git+https:\u002F\u002Fgithub.com\u002Falexziskind1\u002Fmodel-shelf\n```\n\nRequires Python 3.11+.\n\n## Configure\n\nJust run:\n\n```bash\nmodel-shelf init\n```\n\nWhat happens depends on what Model Shelf can see:\n\n- **Your external drive already has a `ModelShelf\u002Fmodels\u002F` folder** → it uses that one silently. No prompt, no questions. (Most common: you've used this drive before.)\n- **External drives are connected but none has a shelf yet** → interactive picker (arrow keys) showing each drive plus an internal-storage option and a custom-path escape hatch.\n- **No external drives connected** → falls back to internal storage (`~\u002F.cache\u002Fmodel-shelf\u002Fmodels`) and tells you.\n- **Need explicit control** → `model-shelf init \u002Fpath\u002Fto\u002Fshelf` skips detection and uses that path.\n\nWhichever path is picked, Model Shelf creates the three format subfolders under it. Downloads then nest by publisher and repo (mirrors Hugging Face Hub, matches LM Studio's layout):\n\n```\nmodels\u002F\n├── gguf\u002F\n│   └── Qwen\u002F\n│       └── Qwen3-14B-GGUF\u002F\n│           └── Qwen3-14B-Q4_K_M.gguf\n├── mlx\u002F\n│   └── mlx-community\u002F\n│       └── Qwen3-14B-4bit\u002F\n└── safetensors\u002F\n    └── Qwen\u002F\n        └── Qwen3-14B\u002F\n```\n\nBy default `init` does **not** pin a path in the config — discovery handles drive swaps and renames automatically. Pass an explicit path (`model-shelf init \u002Fpath\u002Fto\u002Fshelf`) only when you want to pin a specific location in the config.\n\nSwitch shelves later by re-running `init`. Override which config file is used with `$MODEL_SHELF_CONFIG` or `--config \u003Cpath>`. The user-level config (`~\u002F.config\u002Fmodel-shelf\u002Fconfig.toml`) is the only implicit lookup — Model Shelf does not pick up a `.\u002Fconfig.toml` from your current directory, so unrelated tools' configs can't accidentally hijack it.\n\n> If you pass a path under `\u002FVolumes\u002F\u003Cname>\u002F` and `\u003Cname>` isn't currently mounted, `init` fails with a clear error instead of silently writing to the internal SSD.\n\n### Multi-shelf lookup\n\nModel Shelf treats every shelf it can see locally as fair game when resolving a model. On every `resolve` it checks:\n\n1. The primary shelf (configured `shelf_root` if pinned, or auto-discovered if not).\n2. Every mounted `\u002FVolumes\u002F*\u002FModelShelf\u002Fmodels\u002F` directory (any external drive with a shelf).\n3. The internal default at `~\u002F.cache\u002Fmodel-shelf\u002Fmodels` (if it exists).\n\nFirst hit wins. Downloads on a miss still go to the primary. So you can plug in any drive that has a ModelShelf folder, rename your main drive, or have multiple shelves spread across drives — if the file is local *anywhere*, it's used.\n\n### Pinned vs unpinned config\n\nBy default the config doesn't pin a specific path. The user-level config looks like:\n\n```toml\nallow_downloads = true\n```\n\nThat's it — no `shelf_root` line. At runtime Model Shelf auto-discovers a primary (first external `\u002FVolumes\u002F*\u002FModelShelf\u002Fmodels`, else internal). Swap drives, rename them, plug in a different drive entirely — nothing in the config needs to change.\n\nIf you *want* to pin a specific path (say, you have two external drives and want downloads to land on a particular one), run `model-shelf init \u003Cpath>` — that writes `shelf_root` to the config explicitly. Running `model-shelf init` without an argument never pins.\n\n## CLI\n\n```bash\n# Setup: auto-detects external drives, prompts or auto-picks, writes config + creates dirs.\nmodel-shelf init\n\n# Or skip detection and use an explicit path:\nmodel-shelf init \u002FVolumes\u002FMyDrive\u002FModelShelf\u002Fmodels\n\n# Search Hugging Face for a loose query — for when you don't know the exact repo id.\nmodel-shelf find \"qwen 3 4b mlx 4-bit\" --format mlx --limit 5\n\n# GGUF (format auto-detected; --quant required for gguf)\nmodel-shelf resolve \"Qwen\u002FQwen3-14B-GGUF\" --quant Q4_K_M\n\n# MLX (auto-detected from mlx-community\u002F* or *-mlx)\nmodel-shelf resolve \"mlx-community\u002FQwen3-14B-4bit\"\n\n# Safetensors (default when nothing else matches)\nmodel-shelf resolve \"Qwen\u002FQwen3-14B\"\n\n# Force a specific format\nmodel-shelf resolve \"Qwen\u002FQwen3-14B\" --format safetensors\n\n# Never reach out to the network, even on a miss.\nmodel-shelf resolve \"Qwen\u002FQwen3-14B-GGUF\" --quant Q4_K_M --no-download\n\n# Emit JSON for scripting.\nmodel-shelf resolve \"Qwen\u002FQwen3-14B-GGUF\" --quant Q4_K_M --json\n\n# List what's on the curated shelf (all three format subfolders).\nmodel-shelf list\n```\n\nExit codes: `0` on found\u002Fdownloaded, `1` on missing.\n\n## Agent integration\n\nIf you installed via `\u002Fplugin install`, you're done — the bundled skill tells the agent to always call `model-shelf resolve` before any Hugging Face download, and the SessionStart hook keeps the CLI installed. You may want to pre-allow the CLI in permissions so the agent doesn't prompt every time:\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\"Bash(model-shelf resolve:*)\", \"Bash(model-shelf list:*)\"]\n  }\n}\n```\n\nFor any other agent: copy [`skills\u002Fresolve\u002FSKILL.md`](skills\u002Fresolve\u002FSKILL.md) into wherever your agent reads instructions from, and allow `model-shelf resolve` as a tool. The agent calls:\n\n```\nmodel-shelf resolve \"Qwen\u002FQwen3-14B-GGUF\" --quant Q4_K_M --json\n```\n\nand gets back:\n\n```json\n{\n  \"status\": \"found\",\n  \"source\": \"hf_cache\",\n  \"path\":   \"\u002FVolumes\u002FMyDrive\u002FModelShelf\u002Fhf-cache\u002F...\u002FQwen3-14B-Q4_K_M.gguf\",\n  \"checks\": [ ... ]\n}\n```\n\n## How it works\n\nFormat is detected from the repo id (override with `--format`):\n\n| Repo pattern | Format | Notes |\n|---|---|---|\n| `*-GGUF` (case-insensitive) | `gguf` | requires `--quant` |\n| `mlx-community\u002F*` or `*-mlx` | `mlx` | directory of files |\n| anything else | `safetensors` | directory of files |\n\nFor every resolve request:\n\n1. **Curated shelf** — looks in `shelf_root\u002F\u003Cformat>\u002F`. Hit → return.\n2. **Download** — if `allow_downloads = true`, calls `huggingface_hub` with `local_dir` pointed at the shelf, so the file lands directly at the friendly path. For GGUF, a single rename normalizes the HF capitalization to lowercase. Otherwise returns `status=\"missing\"`.\n\nNo parallel cache to manage. `huggingface_hub` writes a small hidden `.cache\u002Fhuggingface\u002F` subfolder inside the shelf for download metadata (resumability) — it's filtered out of `model-shelf list`.\n\nCurated-shelf paths:\n\n| Repo | Quant | Path under `shelf_root` |\n|---|---|---|\n| `Qwen\u002FQwen3-14B-GGUF` | `Q4_K_M` | `gguf\u002FQwen\u002FQwen3-14B-GGUF\u002FQwen3-14B-Q4_K_M.gguf` |\n| `meta-llama\u002FLlama-3.1-8B-Instruct-GGUF` | `Q5_K_M` | `gguf\u002Fmeta-llama\u002FLlama-3.1-8B-Instruct-GGUF\u002FLlama-3.1-8B-Instruct-Q5_K_M.gguf` |\n| `mlx-community\u002FQwen3-14B-4bit` | — | `mlx\u002Fmlx-community\u002FQwen3-14B-4bit\u002F` |\n| `Qwen\u002FQwen3-14B` | — | `safetensors\u002FQwen\u002FQwen3-14B\u002F` |\n\nA directory-format shelf hit requires the directory to exist **and** contain a `config.json` — that's the minimal \"this is actually a model\" sanity check.\n\n## Storage backends\n\nThe code is storage-agnostic. Examples of where you might point the two roots:\n\n```toml\n# External SSD \u002F Thunderbolt DAS\nshelf_root = \"\u002FVolumes\u002FMyDAS\u002FModelShelf\u002Fmodels\"\n\n# NAS mount\nshelf_root = \"\u002Fmnt\u002Fnas\u002Fai-models\"\n\n# Plain internal folder\nshelf_root = \"~\u002F.cache\u002Fmodel-shelf\u002Fmodels\"\n```\n\n## Status\n\nv0.13 — GGUF, MLX, and safetensors via CLI + Python lib. **Publisher\u002Frepo nested layout** that mirrors the Hugging Face Hub (and matches what LM Studio expects). Config is unpinned by default: `shelf_root` is optional, auto-discovered at runtime from any mounted `\u002FVolumes\u002F*\u002FModelShelf\u002Fmodels` (else internal). `model-shelf init \u003Cpath>` pins; `model-shelf init` without an argument does not. Multi-shelf lookup: every `resolve` checks the primary plus every mounted drive with a ModelShelf folder plus the internal default. `model-shelf find \u003Cquery>` searches Hugging Face for loose natural-language queries. Mount precheck refuses to write if the configured volume isn't mounted. Roadmap: `verify` subcommand, quantized-safetensors variants (AWQ\u002FGPTQ).\n\n## License\n\nMIT\n","2026-06-11 04:10:47","CREATED_QUERY"]