shellish

English | 中文

---

English

Type natural language at your shell prompt — AI handles the rest. Any language your model understands works; the examples below are just English.

$ shrink every png in this folder

$ fix the last git conflict

$ why is my docker build so slow

(If a request starts with a word that's also a real command — find, sort, compress … — your shell runs that instead. Wrap it in quotes or call shellish "…". See Usage.)

Typos are caught and corrected, never executed:

$ gti status
  did you mean:  git status

File deletions move to trash instead of running rm directly:

$ delete the build directory

  ⚠️  rm -rf build
  → will move to trash, not permanently delete

  [y] allow once  [a] allow all (this session)  [N] deny

Install

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/XiXian42/shellish/main/install.sh | bash

Windows (PowerShell, beta)

irm https://raw.githubusercontent.com/XiXian42/shellish/main/install.ps1 | iex

Use PowerShell 7 or Windows PowerShell 5.1 as the main Windows shell. The installer adds shellish.cmd to PATH and installs a PowerShell profile hook; once the hook is loaded, PowerShell calls shellish through Node directly, avoiding CMD argument parsing for natural-language input.

If PowerShell blocks the hook with "running scripts is disabled", enable user scripts once:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

If your Windows home directory is restricted, set a writable data directory before running shellish:

$env:SHELLISH_HOME = "$env:APPDATA\shellish"

The installer will:

1. Detect available AI agents on your system (pi / omp / claude / codex)
2. Ask you to pick a default
3. Write the hook into your shell profile

Restart your shell to activate.

Prerequisite: at least one supported AI agent must already be installed.

Supported Agents

Agent	Install
pi	npm i -g @earendil-works/pi-coding-agent
omp	npm i -g @earendil-works/omp
Claude Code	npm i -g @anthropic-ai/claude-code
Codex CLI	npm i -g @openai/codex

shellish uses whatever is already on your system — it won't install agents for you.

Before first use: complete login / authentication for your agent outside of shellish (e.g. run claude once and finish the browser OAuth flow, or codex login). shellish's agent health check in shellish status will surface this; an un-authenticated agent fails with a confusing error if you skip this step.

Usage

After installing the hook, just type natural language at the prompt:

shrink all png files in this directory

fix the last git conflict

deploy the app with production config

why is my build failing?

If a request happens to start with a word that is also a real shell command, your shell may run that command instead of handing the line to shellish. In those rare command-name conflicts, on zsh / bash wrap the sentence in quotes so the shell treats it as one unknown command and shellish can handle it:

"find all TODO comments in this repo and summarize them"
"sort these files by size and summarize the largest ones"

This quoting trick does not work in PowerShell (a quoted string is just an expression there) — on Windows, call shellish explicitly instead:

shellish "find all TODO comments in this repo and summarize them"

You can also call shellish "..." explicitly on any platform if you prefer.

Memory

shellish remembers personal facts you mention and carries them into future sessions:

$ remember I'm based in London and use neovim

  ⚙  bash  echo "- User is based in London" >> ~/.shellish/memory.md
  ⚙  bash  echo "- User uses neovim" >> ~/.shellish/memory.md
Got it.

Memory lives in ~/.shellish/memory.md on macOS/Linux and %APPDATA%\shellish\memory.md on Windows. You can override it with SHELLISH_HOME.

Commands

shellish config          # switch agent, configure delete behaviour
shellish status          # show current config and available agents
shellish install-hook    # manually install shell hook
shellish uninstall-hook  # remove shell hook

Uninstall

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/XiXian42/shellish/main/uninstall.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/XiXian42/shellish/main/uninstall.ps1 | iex

How it works

shell prompt
  ↓
command_not_found_handler (zsh / bash)
  ↓
shellish --from-shell
  ↓
LLM classifies: typo → show correction  |  natural language → proceed
  ↓
build prompt (rules + memory + history + current time)
  ↓
call agent (pi / omp / claude / codex)
  ↓
stream-render output
  ↓
save to shellish data history/ (`~/.shellish` or `%APPDATA%\shellish`)

On delete: rm is replaced by safe-rm which moves files to trash.
macOS uses the trash CLI; Linux follows the freedesktop Trash spec.

Security — read this before you install

Be honest with yourself about what this is: shellish takes your natural-language line, sends it to an LLM, and runs the shell commands that come back.

• Commands run without a per-command confirmation. shellish launches the underlying agent with its approval prompts turned off (Claude Code with --dangerously-skip-permissions, Codex with --dangerously-bypass-approvals-and-sandbox). The agent can read, write, and execute freely in your shell. There is no sandbox.
• The one guardrail is deletion. rm is rerouted to safe-rm, which moves targets to the trash/Recycle Bin and (in ask mode) prompts you first. That is the only operation gated this way — curl … | bash, git push --force, sudo …, overwriting files, and anything else run with no extra prompt.
• Your input leaves your machine. Each request sends the LLM your prompt, the current working directory, recent history for that directory (last ~24h, up to 10 entries), and your memory.md. Where that goes is governed by whichever agent you configured and its privacy terms — shellish itself has no server and stores nothing remotely.

Sensible use: run it in directories you trust, on a machine where you'd already let a coding agent operate, and read the streamed commands as they execute. If you want a hard sandbox or mandatory per-command approval, this tool is not that — use your agent directly with its own approval flow.

Platforms

Platform	Status
macOS	✅
Linux	✅
Windows	🧪 beta

Shell: zsh / bash / PowerShell

---

中文

在终端里直接说话，AI 帮你干活。任何模型能理解的语言都行，下面的例子只是举例。

$ 帮我把当前目录所有 png 压缩一下

$ fix the last git conflict

$ 查一下北京今天天气

打错命令时自动纠正，不执行：

$ gti status
  did you mean:  git status

删除文件时移入回收站，不会直接 rm：

$ 删除 build 目录

  ⚠️  rm -rf build
  → will move to trash, not permanently delete

  [y] allow once  [a] allow all (this session)  [N] deny

安装

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/XiXian42/shellish/main/install.sh | bash

Windows（PowerShell，beta）

irm https://raw.githubusercontent.com/XiXian42/shellish/main/install.ps1 | iex

Windows 建议使用 PowerShell 7 或 Windows PowerShell 5.1。安装器会把 shellish.cmd 加入 PATH，并安装 PowerShell profile hook；hook 加载后，PowerShell 会直接通过 Node 调用 shellish，避免自然语言输入经过 CMD 参数解析。

如果 PowerShell 提示 running scripts is disabled，需要为当前用户开启脚本执行：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

如果 Windows 用户目录受限，可以先指定一个可写的数据目录：

$env:SHELLISH_HOME = "$env:APPDATA\shellish"

安装过程会自动：

1. 检测系统上已有的 AI agent（pi / omp / claude / codex）
2. 让你选一个默认 agent
3. 把 hook 写入 shell 配置文件

重启终端后即可使用。

前提：需要已安装至少一个支持的 AI agent。

支持的 Agent

Agent	安装
pi	npm i -g @earendil-works/pi-coding-agent
omp	npm i -g @earendil-works/omp
Claude Code	npm i -g @anthropic-ai/claude-code
Codex CLI	npm i -g @openai/codex

只使用系统上已有的 agent，shellish 不会帮你安装。

用法

安装 hook 后，直接在终端输入自然语言：

帮我找出当前目录最大的 10 个文件

fix the last git conflict

deploy the app, 用 production 配置

why is my build failing?

如果某个请求刚好以真实 shell 命令名开头，shell 可能会直接执行该命令，而不是交给 shellish。遇到这类少数命令名冲突时，在 zsh / bash 下推荐把整句话用引号包起来，让 shell 把它当成一个未知命令交给 shellish：

"find all TODO comments in this repo and summarize them"
"sort these files by size and summarize the largest ones"

这个引号技巧在 PowerShell 下无效（带引号的字符串在 PS 里只是一个表达式，会原样回显）——Windows 上请显式调用：

shellish "find all TODO comments in this repo and summarize them"

任何平台上也都可以显式调用 shellish "..."。

Memory

shellish 会自动记住你说过的个人信息，下次对话自动带入：

$ 记住我在北京，用 vim

  ⚙  bash  echo "- 用户在北京" >> ~/.shellish/memory.md
  ⚙  bash  echo "- 用户使用 vim" >> ~/.shellish/memory.md
已记住。

memory 在 macOS/Linux 存在 ~/.shellish/memory.md，Windows 存在 %APPDATA%\shellish\memory.md。也可以用 SHELLISH_HOME 指定位置。

命令

shellish config          # 切换 agent，配置删除行为
shellish status          # 查看当前配置和可用 agent
shellish install-hook    # 手动安装 shell hook
shellish uninstall-hook  # 移除 shell hook

卸载

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/XiXian42/shellish/main/uninstall.sh | bash

Windows（PowerShell）

irm https://raw.githubusercontent.com/XiXian42/shellish/main/uninstall.ps1 | iex

工作原理

终端输入
  ↓
command_not_found_handler (zsh / bash)
  ↓
shellish --from-shell
  ↓
LLM 判断：typo → 显示纠正  /  自然语言 → 继续
  ↓
构建 prompt（system rules + memory + 历史 + 当前时间）
  ↓
调用 agent（pi / omp / claude / codex）
  ↓
流式渲染输出
  ↓
保存历史到 shellish 数据目录 history/（`~/.shellish` 或 `%APPDATA%\shellish`）

删除文件时：rm 被替换为 safe-rm，移入回收站而非直接删除。macOS 用 trash CLI，Linux 遵循 freedesktop Trash spec。

安全说明 — 安装前请先读

请清楚这个工具的本质：shellish 把你的自然语言交给 LLM，再执行它返回的 shell 命令。

• 命令执行没有逐条确认。 shellish 启动底层 agent 时关掉了它自己的审批提示（Claude Code 用 --dangerously-skip-permissions，Codex 用 --dangerously-bypass-approvals-and-sandbox）。agent 可以在你的 shell 里自由读写和执行，没有沙箱。
• 唯一的护栏是删除。 rm 被改道到 safe-rm，移入回收站，并在 ask 模式下先弹确认。这是唯一被这样拦截的操作——curl … | bash、git push --force、sudo …、覆盖文件等等，都不会额外确认。
• 输入会离开你的机器。 每次请求会把你的输入、当前工作目录、该目录最近的历史（约 24 小时内、最多 10 条）以及你的 memory.md 发给 LLM。这些数据最终去哪由你配置的 agent 及其隐私条款决定——shellish 自己没有服务器，不在远端存任何东西。

合理的用法：在你信任的目录里用，在你本来就愿意让 coding agent 操作的机器上用，并且边执行边看流式输出的命令。如果你需要硬沙箱或强制逐条审批，这个工具做不到——那就直接用你的 agent、走它自己的审批流程。

平台

平台	状态
macOS	✅
Linux	✅
Windows	🧪 beta

Shell：zsh / bash / PowerShell

---

License

MIT — see LICENSE.