v0.2.0

soothsay 0.2.0 makes the agent guard much broader and the analysis more accurate on real installers.

Install

cargo install --locked soothsay

Or download a binary below (macOS and Linux, x86_64 and arm64) and verify it:

sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify soothsay-v0.2.0-<target>.tar.gz --repo rijuld/soothsay

To guard Claude Code:

/plugin marketplace add rijuld/soothsay
/plugin install soothsay@soothsay

Agent guard

• Package runners are checked. npx, npm exec, pnpm dlx, yarn dlx, bunx, uvx, uv tool run, pipx run and deno run are looked up on npm or PyPI first. Packages that don't exist, likely typosquats (npx -y expres) and packages under 14 days old are blocked. A release from the last 48 hours, few downloads, or an unreachable registry makes it ask you. Lookups take about 0.2–0.3 s, are cached for an hour, and never download full package metadata.
• One-step approval. A plain curl … | sh (or bash <(curl …), sh -c "$(curl …)") now becomes a single prompt with the review attached, and the command is rewritten to run exactly the reviewed bytes, keeping installer arguments like -y. sudo and compound commands are still blocked with instructions.
• Nested scripts. If an installer downloads and runs another script, that script is reviewed too (one level deep). A dangerous second stage blocks the whole thing.

Analysis

• Docker's installer is read correctly. The sh_c='sudo -E sh -c' pattern is now followed into the code it runs, as root. get.docker.com goes from "notice" to "warn" (root writes to apt keyrings and sources).
• Less noise. rm -r "${3}/…" inside functions and guarded variables no longer warn about deleting from /; Oh My Zsh and pnpm drop to "notice". Bare rm -rf "$VAR/"* still warns.
• Sudo access checks (sudo -v, sudo -l cmd) are no longer reported as commands.

New commands

• soothsay https://example.com/install.sh: analyze a URL directly; --run runs the fetched bytes.
• soothsay --diff OLD NEW: what changed in an installer's behaviour (files, URLs, findings, verdict), not its text. Exits 1 when behaviour changed.
• soothsay --cloak-check URL: fetches as curl and as a browser and warns if the server sends different scripts.

Quality

• A weekly CI job re-checks 15 popular installers and opens an issue when one's behaviour changes.
• Randomized never-crash tests (about 2.5 million inputs) and fuzz targets.
• Performance budgets enforced in CI: the hook adds about 3–4 ms to ordinary commands.
• Verified on Rust 1.74.

v0.1.0

The first release of soothsay: read the omens before you curl | sh.

soothsay reads a shell install script and tells you, in plain English, what it will do to your machine before you run it: shell profiles it edits, sudo, startup items, nested downloads, hidden payloads, credential access. As a Claude Code hook, it also stops AI coding agents from piping installers into your shell until you've seen what they do.

Install

cargo install --locked soothsay

Or download a binary below (macOS and Linux, x86_64 and arm64) and verify it:

sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify soothsay-v0.1.0-<target>.tar.gz --repo rijuld/soothsay

To guard Claude Code:

/plugin marketplace add rijuld/soothsay
/plugin install soothsay@soothsay

Highlights

• Plain-English reports for any install script: curl -fsSL https://example.com/install.sh | soothsay
• --run runs exactly the bytes it analyzed (never re-downloads); --expect-sha256 pins them across sessions
• CI policy: --deny persistence,remote-exec --fail-on danger install.sh
• Agent guard: soothsay hook blocks commands that run code from the network, reviews the script, pins the bytes, and makes Claude Code ask you before they run. It fails closed.
• Hard to fool: a real tokenizer instead of regexes, escaped output so a script can't rewrite its own report, no "unreachable code" loophole, and code planted in rc files or crontabs is analyzed too
• Zero dependencies, a single small binary, built and attested by GitHub Actions