YOLO-Shell sits between the Enter key and your shell. It reads the command you just typed, weighs it against where you are — working directory, Git branch, AWS_PROFILE, KUBE_CONTEXT — and decides whether to get out of the way, ask for confirmation, or refuse.

$ rm -rf /

⛔ YOLO-Shell blocked  risk 10/10  rm -rf /
   recursive delete of the filesystem root or home directory
   override: prefix the command with `yolo `

🤔 Why Standard Shell Aliases Fail

The Rule Explosion Problem

The usual defence is an alias or a wrapper function:

alias rm='rm -i'

Then you need one for git push --force. And kubectl delete. And terraform destroy, aws s3 rm --recursive, DROP DATABASE, dd of=/dev/…. Each tool brings its own flags, each flag its own edge cases, and every rule has to know which of them are dangerous in this directory, on this branch, against this cluster.

That is a combinatorial explosion of fragile regex, and it fails in both directions at once: too noisy to keep enabled, too sparse to actually catch the command that ruins your afternoon. rm -rf / is easy. zsh -c 'rm -rf /' is the same command wearing a hat, and your alias never sees it.

The Latency Problem

Handing the question to a general-purpose LLM solves the rule explosion and creates a worse problem: 2–3 seconds of think-time on every command. A shell that pauses before ls is a shell you will uninstall by lunchtime.

The budget for a gatekeeper is not "fast enough to be useful." It is fast enough to be invisible.

⚡ The Solution: a System 1 AI Engine

YOLO-Shell splits the problem in two, the way you do.

System 1 — reflex. A local fast-path filter recognises commands that only read or navigate (ls, cd, cat, git status) and lets them through with no network call at all. This is a sorted-table lookup over the command's tokens: 178ns in-process, ~2ms including process spawn. It is the path the overwhelming majority of your commands take.

System 2 — judgement. Anything else goes to TypeSafe Jev, a typed decision engine. YOLO-Shell asks it three named questions in a single POST /v1/systemone pass:

No token generation, no prose — structured output rather than a chat completion, which is what makes a sub-second round trip possible at all.

Jev gets a wall-clock deadline enforced on the calling side rather than trusted to the HTTP stack. Miss it, and a deterministic local rule engine answers instead. You are never waiting on a network you cannot reach.

The connection daemon

The hook spawns a fresh yolo per command, so the naive path repeats DNS, TCP and TLS every single time. Against us-west-2 that measured ~455ms of handshake to wrap ~350ms of actual inference — most of your wait was setup, paid again and again.

yolo daemon holds one warm connection and answers over a unix socket:

The shell hooks start it for you when JEV_API_KEY is set. It exits when idle, a second instance exits immediately, and the socket is 0600 because the daemon holds your key. It is strictly an accelerator — if it is missing, stale or slow, the CLI falls back to an in-process call and then to local heuristics, so it can never stop a decision being made.

yolo daemon --idle-timeout 3600   # run it yourself
YOLO_NO_DAEMON=1                  # opt out

🏗️ Architecture & Workflow

flowchart TD
    A[Terminal Command Input] --> B{Local Fast-Path Filter}
    B -->|allowlisted: ls, cd, git status| C[Execute · ~2ms, no network]
    B -->|everything else| D[Scrub secrets from payload]
    D --> E{Jev Decision Engine<br/>200ms deadline}
    E -->|answers in time| F[is_destructive · risk_score · action]
    E -->|timeout / offline / no key| G[Local heuristic engine]
    G --> F
    F --> H{Action}
    H -->|allow_immediately| I[Execute natively · exit 0]
    H -->|warn_and_confirm| J[Yellow banner + y/N · exit 0 or 126]
    H -->|block_completely| K[Red alert · exit 126]

Context sent to Jev on every evaluated command:

{
  "command": "psql postgres://admin:[REDACTED]@prod-db.internal/billing -c 'DROP TABLE users'",
  "pwd": "/Users/dev/projects/billing-service",
  "git_branch": "main",
  "env_context": { "NODE_ENV": "production", "AWS_PROFILE": "prod-account" }
}

Note the [REDACTED]. The password never left the machine; the host, the user and the statement did, because those are what the decision depends on.

✨ Features at a Glance

🚀 Quickstart

Install

curl -fsSL https://raw.githubusercontent.com/riz007/yolo-shell/main/install.sh | sh

git clone https://github.com/riz007/yolo-shell.git ~/.yolo-shell
cd ~/.yolo-shell && cargo build --release

Shell integration

Zsh — add to ~/.zshrc:

source ~/.yolo-shell/hooks/yolo.zsh

Bash — add to ~/.bashrc:

source ~/.yolo-shell/hooks/yolo.bash

Fish — add to ~/.config/fish/config.fish:

source ~/.yolo-shell/hooks/yolo.fish

Open a new terminal. You are protected — on heuristics alone, with no key.

BYOK Setup

To enable Jev's context-aware judgement, export your TypeSafe key:

mkdir -p ~/.config/yolo-shell
printf 'export JEV_API_KEY=%s\n' 'your_key_here' > ~/.config/yolo-shell/env
chmod 600 ~/.config/yolo-shell/env

Then source it from your rc file, before the hook line:

[ -f ~/.config/yolo-shell/env ] && source ~/.config/yolo-shell/env

Confirm it is being used:

YOLO_DEBUG=1 ~/.yolo-shell/target/release/yolo eval "kubectl delete namespace billing"
# yolo: jev decided in 143ms: risk 9/10

local decided in 200ms (no response within 200ms) means the key or endpoint is wrong and you are running on heuristics — decisions are still made, just without Jev's context awareness.

🎬 Demo

Safe — straight through, no network:

$ ls -la
total 48
drwxr-xr-x  12 dev  staff   384 Nov 14 09:22 .
-rw-r--r--   1 dev  staff  1823 Nov 14 09:21 Cargo.toml

Fast-path hit. 178ns filter, ~2ms total. Jev never contacted.

Risky — intercepted with a risk score:

$ git push origin main -f

⚠  YOLO-Shell  risk 9/10  git push origin main -f
   force-push rewrites remote history; on a protected branch
   Run anyway? [y/N]

Answer n and the command is discarded, still on the prompt for editing.

Catastrophic — blocked outright:

$ rm -rf /

⛔ YOLO-Shell blocked  risk 10/10  rm -rf /
   recursive delete of the filesystem root or home directory
   override: prefix the command with `yolo `

Exit code 126. The command never reaches your shell.

⚙️ Configuration

Two escape hatches, for when you know exactly what you are doing:

yolo rm -rf ./node_modules      # bypass this one command
YOLO_BYPASS=1 ./scary-script.sh # bypass for one invocation

Exit codes

Any other code means YOLO-Shell itself misbehaved, and every hook treats it as allow. A gatekeeper that locks you out of your own terminal is a worse bug than the one it was trying to prevent.

🛠️ Development

cargo test                    # 76 tests
cargo bench                   # asserts against the latency budget
cargo clippy -- -D warnings
cargo fmt -- --check

See what the engines think about a command without running it:

yolo explain "git push --force origin main"
yolo explain --json --branch main "rm -rf /"

And check the risk rubric against a corpus spanning every band:

source ~/.config/yolo-shell/env
./scripts/verify-rubric.py

src/
├── fastpath.rs     allowlist filter — no network, no allocation
├── redact.rs       secret scrubbing at the wire boundary
├── heuristics.rs   deterministic offline rule engine
├── jev_client.rs   Jev API client + decision schema
├── daemon.rs       warm-connection daemon and its client
└── main.rs         CLI and action dispatcher
hooks/              zsh, bash, fish integrations

A note on the shell hooks

Zsh's preexec and Fish's fish_preexec both fire after the shell has committed to running the command, and neither can cancel it — a block could be reported but not enforced. YOLO-Shell therefore wraps Zsh's accept-line widget and rebinds Enter in Fish, both of which run while the line is still an editable buffer. Bash's DEBUG trap can cancel, but only with shopt -s extdebug, which the hook sets.

📄 License

MIT. See LICENSE.