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

01

Ask naturally

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

02

Use your shortcut

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

03

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

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

01 / 06

Disk space

Ask in plain words 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 / 06

Port conflicts

Commands that change things are flagged. Killing processes is rated MEDIUM, so you see it 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
lsof -ti :3000 | xargs kill
Risk: MEDIUM · Check: No known issues
  risk: terminates processes
03 / 06

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 / 06

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
❯gti log --oneline -5
zsh: command not found: gti
❯hsf
Enterhsf fixes your last failed command
Suggested fix · review before running
git log --oneline -5
The command had a typo: gti should be git.
Risk: none recognized · Check: No known issues
05 / 06

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 that commit's changes staged, so you can recommit them. It only works if the last commit is not yet pushed; if it is, pushing again will require a force push.
Risk: MEDIUM · Check: No known issues
  risk: changes git history or a remote
06 / 06

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

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

Private by default

Nothing is logged unless you turn history on, and then only for you. Your folder is sent as ~/project, without your user name.

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.