![\"Version](\"assets/hero.png\")
\n\n \n
\n ![\"Release\"](\"https://img.shields.io/github/v/release/KSEGIT/Version-Sentinel?color=blue\")
![\"License:](\"https://img.shields.io/github/license/KSEGIT/Version-Sentinel\")
![\"Claude](\"https://img.shields.io/badge/Claude%20Code-plugin-8b5cf6\"){kind=icon}
![\"Supported](\"https://img.shields.io/badge/ecosystems-npm%20%7C%20pip%20%7C%20cargo%20%7C%20nuget-22c55e\"){kind=icon}
Claude Code plugin that hard-blocks dependency additions, bumps, and downgrades until a fresh, source-cited version check is recorded.
\n\n> If Claude tries to add `\"lodash\": \"^4.17.21\"` without looking up the latest version first, the tool call is rejected with exit 2. Claude must run `WebSearch`, then `/vs-record`, then retry. Five ecosystems supported in v0.1.\n\n**Keywords:** Claude Code, Anthropic, AI coding guardrails, LLM supply-chain security, dependency management, hallucinated package versions, npm, PyPI, Cargo, NuGet, PreToolUse hook.\n\n## Why\n\nLLM-assisted coding silently ships whatever version the model remembers from its training data. For packages with frequent releases or known compromised versions, that's unacceptable. `version-sentinel` inserts a mandatory \"check the registry\" step — without stopping you from pinning an old version on purpose.\n\n## What it prevents\n\n- **Hallucinated versions** — LLM picks a version that never existed or never shipped.\n- **Stale defaults** — model reaches for a 2-year-old pin because training data froze there.\n- **Compromised-release installs** — no guard against yanked / malicious versions without a fresh registry lookup.\n- **Silent downgrades** — Claude \"fixes\" a CI error by reverting a package to an older vulnerable build.\n- **Supply-chain drift** — no audit trail of *why* a specific version was chosen.\n\n## How it compares\n\n| Tool | Scope | Enforcement |\n|------|-------|-------------|\n| `version-sentinel` | Claude Code **PreToolUse hook** — blocks the tool call before the edit lands | Hard-fail exit 2 |\n| Generic dependency-audit skills | Post-hoc scan of `package.json` / `requirements.txt` | Advisory |\n| Dependabot / Renovate | Scheduled PR bot against remote registries | Async PR |\n\nUnlike post-hoc auditors, `version-sentinel` runs **inside the agent loop** — the agent cannot merge a bad version by accident because the write itself is refused until the check is cited.\n\n## Supported ecosystems (v0.1)\n\n| File | Ecosystem | Registry |\n|------|-----------|----------|\n| `package.json` | npm/pnpm/yarn/bun | registry.npmjs.org |\n| `requirements*.txt`, `constraints*.txt` | pip | pypi.org |\n| `pyproject.toml` | PEP 621 + Poetry + uv | pypi.org |\n| `Cargo.toml` | Rust | crates.io |\n| `*.csproj`, `*.fsproj`, `*.vbproj` | .NET | api.nuget.org |\n\nCovers `Edit`, `Write`, `MultiEdit`, and `Bash` install commands (`npm install`, `pip install`, `poetry add`, `uv add`, `cargo add`, `dotnet add package`).\n\n## Install\n\n```\n/plugin marketplace add https://github.com/KSEGIT/Version-Sentinel.git\n/plugin install version-sentinel@version-sentinel-marketplace\n```\n\n> The `owner/repo` shorthand (`KSEGIT/Version-Sentinel`) resolves to an SSH clone URL and requires GitHub SSH keys. Use the full HTTPS URL above to clone anonymously.\n\n## Multi-agent support\n\nOne repo, six agent platforms. The same hook scripts and sidecar state back every integration; each platform gets its own thin adapter (manifest, hook wiring, commands).\n\n| Platform | Install / enable |\n|----------|------------------|\n| Claude Code | `/plugin marketplace add https://github.com/KSEGIT/Version-Sentinel.git` → `/plugin install version-sentinel@version-sentinel-marketplace` |\n| z.ai (GLM Coding Plan / ZCode) | Uses the Claude Code plugin format — same install as Claude Code above (ZCode embeds the Claude Code runtime; GLM Coding Plan runs inside Claude Code) |\n| Kimi Code | `/plugins install https://github.com/KSEGIT/Version-Sentinel` (or a local path) |\n| GitHub Copilot in VS Code | Files under `.github/` + `.agents/skills/` — works when this repo is the workspace, or copy them into yours |\n| Gemini CLI | `gemini extensions install https://github.com/KSEGIT/Version-Sentinel`, then `bash ~/.gemini/extensions/version-sentinel/platforms/gemini/setup.sh` to activate hooks (see `docs/e2e-checklist.md`) |\n| OpenAI Codex | `codex plugin marketplace add KSEGIT/Version-Sentinel` → `codex plugin add version-sentinel` (or legacy `.claude-plugin` marketplace compat) |\n| Zed | Manual: `AGENTS.md` + `.agents/skills/` + `docs/zed.md` — static-permissions approximation; **no hook support**, so blocking is best-effort |\n\nPlatform-specific layout:\n\n```\nplugin.json, .claude-plugin/ Claude Code plugin + marketplace metadata\nkimi.plugin.json, platforms/kimi/ Kimi Code plugin manifest + adapter\ngemini-extension.json, GEMINI.md Gemini CLI extension manifest + context\nplatforms/gemini/setup.sh Gemini hook activation (run inside the installed extension)\ncommands/*.toml Gemini CLI slash commands (/vs-record, /check-versions)\n.codex-plugin/ OpenAI Codex plugin metadata\n.github/hooks|agents|prompts/ GitHub Copilot hooks, agents, prompts\n.agents/skills/ Cross-tool skills (Copilot, Zed, ...)\nAGENTS.md Cross-tool agent instructions\n```\n\nFor marketplace listings and submission status per platform (what's ready, what needs an owner-submitted form), see `docs/marketplaces.md`.\n\n## Prerequisites\n\n- `bash`, `jq`, `curl`, `python3` (3.11+, for `tomllib`) on `PATH`\n- Windows: Git Bash bundles `bash`/`jq`/`curl`; install Python 3.13 separately.\n\n## How it works\n\n1. Claude tries to add/bump a dep (`Edit package.json`, `npm install X@Y`, ...)\n2. PreToolUse hook fires, exits 2 with stderr:\n ```\n BLOCKED: version-sentinel.\n Package: lodash (npm). Version: 4.17.21.\n No fresh version check on record.\n ```\n3. Claude runs `WebSearch \"lodash latest version site:npmjs.com\"`\n4. Claude invokes `/vs-record npm lodash 4.17.21 https://www.npmjs.com/package/lodash`\n5. Claude retries — hook finds fresh entry, lets the call through.\n\n## Commands\n\n- `/vs-record