soothsay is an open-source Rust utility that analyzes shell installation scripts before execution and explains their likely effects in plain English. It can identify shell-profile edits, persistence mechanisms, privilege escalation, security-setting changes, network downloads, credential access, destructive commands, obfuscated payloads, and remote code execution patterns. The tool uses a tokenizer, parser, variable resolution, function and branch analysis, and reachability tracking rather than regular expressions; comments, quoted strings, and data written by heredocs are therefore not treated as commands. It reports blind spots when a script executes a downloaded binary, evaluates dynamic strings, or sources content it cannot inspect, and it never runs a script unless the user explicitly selects --run. With --run, it executes the already analyzed bytes from a private temporary file, using the reviewed SHA-256 hash so the content is not downloaded again. The project also offers CI policies such as --deny, --fail-on, and --expect-sha256 for checking an installer before release. Its Claude Code hook examines Bash commands, fetches and reviews network-delivered scripts, caches approved content by hash, and returns a human-approval decision; dangerous findings or analysis failures block execution. In non-interactive permission modes, it blocks rather than delegating consent to the agent. The hook is designed to fail closed, although the project documents a fail-open case when the hook times out or is unavailable in Claude Code’s normal permission flow. soothsay is advisory static analysis, not a sandbox: it does not inspect downloaded binaries or non-shell code, and “no findings” is not a guarantee of safety. The repository provides prebuilt macOS and Linux binaries, SHA256SUMS, build attestations, a library API, and an MIT license.
