watchdog

---

What it's for

npm audit, Snyk, and Dependabot all inspect manifest edits in your repository. They don't see the install command an agent types at a prompt. They also don't see a plugin that drops a hostile skill into ~/.claude/ or wherever your host stores extensions.

Watchdog sits in front of that. Two surfaces, two tools:

1. Dep CVEs → OSV.dev. Cached, parallel, no LLM involved. An LLM can't beat OSV + Snyk/Socket at known-vuln detection, so Watchdog doesn't try.
2. Natural-language attack surface → LLM. Install hooks (preinstall / postinstall scripts, setup.py, build.rs, gem extconf.rb / Rakefile, Homebrew formula scriptlets) and Claude Code agent artifacts (skills, commands, hooks, plugins). These are text, not compiled code; no CVE database covers them. The model looks for typosquats, exfil patterns, credential-stealing skills, prompt-injection bait, install-time persistence.

A published package with no install hooks short-circuits to allow after OSV — Watchdog does not re-scan source files that Snyk/Socket already cover. Worst verdict across the packages in a command wins. If OSV is unreachable, the LLM CLI isn't installed, or the analyzer times out, the default is ask. There's no path where Watchdog silently allows something it couldn't check.

Beyond the verdict, an Ed25519-signed integrity manifest detects tampering with Watchdog's own state — binaries, shim wrappers, decision tokens. The hook wrappers fail-closed on tamper instead of silently passing. See Tamper resistance.

If you already have something covering manifest edits in PRs, this isn't a replacement for that. It covers the surface those tools weren't built for.

---

Quick start

Three commands:

# 1. Install the binaries.
curl -fsSL https://raw.githubusercontent.com/Maxlemore97/Watchdog/main/install.sh | sh

# 2. If the installer warned about PATH, fix it. Then install the
#    package-manager shims. On a TTY, this also generates the local
#    Ed25519 signing keypair and prompts to wire up any detected
#    MCP-aware hosts (Claude Desktop, Cursor, Continue, Cline, Zed).
#    Use --no-register to skip the prompt; --register (or -y) to
#    accept without prompting.
export PATH="$HOME/.local/bin:$PATH"
watchdog-shim install

# 3. Put the shim dir at the FRONT of your PATH (the previous step
#    prints the exact line), open a new shell, then check.
export PATH="$HOME/.watchdog/bin:$PATH"
watchdog-shim doctor

Healthy doctor output:

watchdog-shim doctor:
  ok  shim dir is first on PATH
  ok  watchdog-shim-exec found on PATH
  ok  at least one LLM provider CLI on PATH
  ok  cache dir writable (/home/you/.cache/watchdog)
  ok  integrity manifest matches (/home/you/.watchdog/manifest.json)
  ok  cursor: watchdog-mcp registered (/home/you/.cursor/mcp.json)

doctor is the single source of truth across every layer: PATH, the shim binaries, the integrity manifest + signature (see Tamper resistance), and any MCP-aware host you have installed. Run it after install and any time something looks off.

If doctor warns that no LLM provider CLI is on PATH, that's fine. Watchdog will still run OSV checks; the LLM review just gets skipped. Install claude, gemini, openai, or ollama if you want it back (see LLM providers).

doctor only checks that the CLI is on PATH, not that it actually answers. If you suspect a broken setup (expired auth, exhausted quota, model name typo), add --llm-smoke to send a one-token challenge:

watchdog-shim doctor --llm-smoke                  # 5s timeout, costs ~10 tokens
watchdog-shim doctor --llm-smoke --llm-smoke-timeout=15s

---

Install

Pick whichever applies.

A. Install script (Linux / macOS)