firstrun

module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 18, 2026 License: MIT

README

🛡️ firstrun

See what a command will do to your machine — before you run it.

firstrun wraps any unfamiliar command or script in a safe explain → preview → run flow. It tells you in plain English what the command does, shows you a preview of the exact changes it would make — every file it would write, delete, rename, chmod, or connect to — and only runs it once you confirm.

On Linux it does this for real: it executes the command under a syscall tracer that neutralizes every state-changing operation, so the preview is exactly what would have happened, with nothing actually touching your machine.

CI Release Go Reference Go Report Card

Try it in one line — no install, no signup, nothing runs:

go run github.com/agenticraptor/firstrun/cmd/firstrun@latest explain -- rm -rf ./build

$ curl -fsSL https://get.example.sh | firstrun

firstrun · curl -fsSL https://get.example.sh | sh

This pipes a downloaded script straight into a shell. It will create 1 directory,
connect to 1 network target, write 2 files, and change permissions on 1 file.
Heads up: you'd run code you never get to read.

What it does
  • curl -fsSL https://get.example.sh   Transfer data from or to a URL
      network   https://get.example.sh  (fetches over the network)
  • sh                                  Interpret a shell script
      exec      sh  (interprets arbitrary shell code)

Risks
  [HIGH] remote-code-execution — Pipes downloaded content straight into sh.
  [WARN] insecure-fetch        — verify the source before trusting it.

Live preview — what it actually tried to do
  exec      /usr/bin/sh
  mkdir     /home/you/.example/bin              (blocked)
  create    /home/you/.example/bin/example      (blocked)
  chmod     /home/you/.example/bin/example      (blocked)
  create    /home/you/.bashrc                   (blocked)   ← appends to your shell profile!

What now?
▸ Run it for real     [r]
  Preview again       [p]   run it safely — every change is blocked and recorded
  Cancel              [q]

Nothing above touched the disk. You saw the installer write into ~/.bashrc before deciding whether to trust it.

The "I'm scared to run this" problem

We've all done it: pasted a curl … | bash from a README, run a Makefile target we didn't read, or fired off an rm -rf and felt our stomach drop a half-second too late. The tools that exist explain a command's syntax (tldr, explainshell) — none of them show you the effect on your actual machine before it happens.

firstrun is that missing step. Put it in front of any command:

firstrun rm -rf ./build          # analyze it, then offer to run it
firstrun -c 'curl … | sh'        # analyze a one-liner / pipeline
curl -fsSL https://get.x | firstrun   # pipe a script in, inspect it, then decide
firstrun explain npm install     # just explain — never runs

Why you'll like it

  • A real preview, not a guess. On linux/amd64, firstrun runs the command under a ptrace tracer in block mode: the command executes, but every state-changing syscall (unlink, openat-for-write, rename, chmod, connect, kill, mount, …) is neutralized. You see the complete list of changes it would make — and your machine is untouched.
  • It reads the command first. A static pass parses the shell (pipelines, redirections, &&/||), recognizes a broad catalog of commands, and predicts what each will read, write, delete, download, or run — instantly, on every OS.
  • It flags the scary stuff. curl … | bash, rm -rf /, dd to a disk, sudo, world-writable chmod 777, plain-HTTP downloads, and writes into /etc or /usr are called out with a reason.
  • Plain-English narration. Offline by default; bring an Anthropic, OpenAI, or local Ollama model if you want a friendlier paragraph. Your files never leave your machine.
  • Runs on confirm — or never. The interactive menu lets you run for real, re-preview, or cancel. firstrun explain only ever analyzes.
  • One static binary. No runtime, no daemon, no telemetry. macOS, Linux, and Windows (live tracing on linux/amd64; static preview everywhere else).

Install

go install
go install github.com/agenticraptor/firstrun/cmd/firstrun@latest
Pre-built binaries

Grab a binary for your OS/arch from the Releases page.

Homebrew (macOS / Linux)
brew install agenticraptor/tap/firstrun

Available once the Homebrew tap is published — see the note in .goreleaser.yaml to enable it.

From source
git clone https://github.com/agenticraptor/firstrun
cd firstrun
make install

Quickstart

# 1. Wrap any command. firstrun explains it, previews it, then asks.
firstrun rm -rf ./build

# 2. Inspect a one-liner without your shell interpreting the pipe:
firstrun -c 'curl -fsSL https://get.example.sh | sh'

# 3. The classic: pipe an installer in and read it before trusting it.
curl -fsSL https://get.example.sh | firstrun

# 4. Just explain — never run — and get it as JSON for scripts/CI:
firstrun explain -f json -- npm install

# 5. See what firstrun can do on your machine:
firstrun doctor

Full flags, output formats, and the JSON schema live in docs/usage.md.

How it works

                       ┌───────────────────────────────────────────┐
  command / script ──► │  parse shell  →  predict effects  →  flag  │ ── static preview
   (argv, -c, stdin)   │  (mvdan.cc/sh)   (catalog)         risks   │    (every platform)
                       └───────────────────────────────────────────┘
                                          │
                          confirm? ◄──────┤
                                          │  "preview under the tracer"
                                          ▼
                       ┌───────────────────────────────────────────┐
                       │  run under ptrace, Block mode:             │ ── live preview
                       │   • record open-for-write / unlink /       │    (linux/amd64)
                       │     rename / chmod / connect / kill / …     │
                       │   • neutralize each one (redirect to a      │
                       │     harmless getuid; nothing happens)       │
                       └───────────────────────────────────────────┘
                                          │
                          confirm? ──────►│  "run it for real"
                                          ▼
                                  execute normally

The static preview works everywhere and is instant. The live preview is the special part: firstrun launches the command under ptrace, and at each state-changing syscall it records what the program was about to do and then redirects the syscall to a harmless no-op, so the real operation never executes. Because the program keeps running (it believes its changes succeeded), you get the complete set of effects — not just the first one. See docs/how-it-works.md for the gory details.

Platform support
Platform Preview
Linux / amd64 Live syscall trace + static analysis
Linux / other arch, macOS, Windows Static analysis (the live tracer falls back automatically)

Run firstrun doctor to see what's available on your machine. Porting the tracer to linux/arm64 and a macOS backend are on the roadmap — see docs/platforms.md.

Privacy

firstrun runs entirely on your machine and makes no network connections of its own — no telemetry, no update checks. The only time anything leaves your computer is if you opt into a cloud narration model (Anthropic/OpenAI), in which case only the command text (size-capped) is sent to write the explanation — never your files. Want zero egress? Use --no-ai or a local Ollama.

Safety, honestly

The Block-mode tracer is a powerful way to inspect ordinary commands safely — it has never let a write through in our tests, and there's a test that asserts exactly that. But it runs the command's own code (minus the mutations), so it is not a hardened sandbox for executing something you already believe is malicious. Use it to understand the script your coworker sent or the installer in a README — not to "safely" detonate malware. See SECURITY.md for the full threat model.

Contributing

Contributions are very welcome — see CONTRIBUTING.md. Good first issues include adding commands to the catalog, more effect rules (tar, kubectl apply, …), resolving hostnames behind a connect, and porting the tracer to linux/arm64. Please also read our Code of Conduct.

License

MIT © firstrun contributors.

Directories

Path Synopsis
cmd
firstrun command
Command firstrun explains, previews, and then runs an unfamiliar shell command — so you never blindly execute a script you don't understand.
 Command firstrun explains, previews, and then runs an unfamiliar shell command — so you never blindly execute a script you don't understand.
internal
buildinfo
Package buildinfo exposes version metadata injected at build time via -ldflags.
 Package buildinfo exposes version metadata injected at build time via -ldflags.
catalog
Package catalog holds firstrun's human-facing knowledge about common commands: a one-line description of what each does, and whether the command has a native "dry run" mode firstrun can offer instead of executing for real.
 Package catalog holds firstrun's human-facing knowledge about common commands: a one-line description of what each does, and whether the command has a native "dry run" mode firstrun can offer instead of executing for real.
cli
Package cli wires the firstrun command-line interface together.
 Package cli wires the firstrun command-line interface together.
config
Package config loads firstrun's optional TOML configuration.
 Package config loads firstrun's optional TOML configuration.
effect
Package effect turns a single command's argument vector into a set of predicted, neutral effects — what it reads, writes, deletes, downloads, or executes.
 Package effect turns a single command's argument vector into a set of predicted, neutral effects — what it reads, writes, deletes, downloads, or executes.
llm
Package llm provides a tiny, dependency-free client for the chat APIs of Anthropic, OpenAI, and Ollama.
 Package llm provides a tiny, dependency-free client for the chat APIs of Anthropic, OpenAI, and Ollama.
narrate
Package narrate turns an analyzed plan into a short, plain-English explanation.
 Package narrate turns an analyzed plan into a short, plain-English explanation.
plan
Package plan assembles a full, inspectable preview of a command or script: for every step it records what runs, a plain-English summary, the predicted effects, and the risk flags.
 Package plan assembles a full, inspectable preview of a command or script: for every step it records what runs, a plain-English summary, the predicted effects, and the risk flags.
render
Package render formats an analyzed plan (and an optional live syscall trace) for output: a styled terminal view, a plain-text version, Markdown, and stable JSON for scripts.
 Package render formats an analyzed plan (and an optional live syscall trace) for output: a styled terminal view, a plain-text version, Markdown, and stable JSON for scripts.
risk
Package risk applies fast, deterministic heuristics to a command and the effects it is predicted to have, and flags the things a person should look at twice before running: destructive deletions, raw-disk writes, piping a download straight into a shell, privilege escalation, world-writable permissions, and writes into system directories.
 Package risk applies fast, deterministic heuristics to a command and the effects it is predicted to have, and flags the things a person should look at twice before running: destructive deletions, raw-disk writes, piping a download straight into a shell, privilege escalation, world-writable permissions, and writes into system directories.
run
Package run executes commands on the user's behalf — but only after firstrun has shown a preview and the user has confirmed.
 Package run executes commands on the user's behalf — but only after firstrun has shown a preview and the user has confirmed.
shell
Package shell parses a shell command or script into a structured, inspectable form using the mvdan.cc/sh parser.
 Package shell parses a shell command or script into a structured, inspectable form using the mvdan.cc/sh parser.
trace
Package trace runs a command under a syscall tracer so firstrun can show you exactly what it does at the system-call level.
 Package trace runs a command under a syscall tracer so firstrun can show you exactly what it does at the system-call level.
tui
Package tui renders firstrun's interactive confirmation menu.
 Package tui renders firstrun's interactive confirmation menu.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.