HumanSH

HumanSH is a free, MIT-licensed command-line tool built by agenticlab-ai that lets you describe what you want to do in plain English at your shell prompt and receive a real, reviewable shell command in return. It integrates at the ZLE/Readline layer of Zsh and Bash, so it works inside your existing terminal without a wrapper shell, REPL, or separate app. The project is open source, hosted on GitHub, and reached its v0.1.4 release in August 2026.

What It Is

HumanSH is a shell-native AI translation layer for developers who forget exact command syntax but don't want to leave their terminal to look it up. Instead of switching to a chatbot tab, rebuilding context, copying a command, and pasting it back, you type a natural-language description at the prompt and HumanSH inserts the generated command into your editable command line for review. Nothing runs until you press Enter yourself. The tool is written in Go and targets macOS and Linux on arm64 and amd64.

How the Review-First Workflow Works

The core interaction is a deliberate two-Enter flow:

• Describe: Type what you want in plain English, e.g. show me which process is listening on port 3000
• Review: HumanSH inserts the generated command (lsof -nP -iTCP:3000 -sTCP:LISTEN) into your editable prompt — nothing has run yet
• Run: Press Enter when the command looks right, or edit or cancel it

Commands with destructive patterns require a second, deliberate key sequence (Ctrl-X Enter) rather than an ordinary Enter, adding a risk gate for higher-stakes operations. Zsh gets a "Smart Enter" mode that classifies each line automatically; Bash uses an explicit Ctrl-G shortcut for translation because Readline cannot safely make Enter conditionally replace the buffer.

Local Classification Before Any Provider Call

HumanSH classifies intent locally before making any provider request. Every line gets one of three outcomes: literal (runs normally, no provider call), natural_language (translated and inserted for review), or ambiguous (left untouched, no provider call). The classifier is scoring-based and inspectable via humansh classify, and it uses the resolved executable's own --help output to understand subcommands and options — there is no per-command catalog baked into the binary. This means git status runs immediately without consuming any model quota, while git is failing please authenticate is correctly left ambiguous.

Provider Model and Privacy Design

HumanSH connects to AI providers the user already has access to rather than requiring a new paid API:

• ChatGPT subscription via Codex CLI
• Claude subscription via Claude Code CLI
• Cursor subscription via Cursor CLI
• OpenRouter metered API as an explicit, opt-in fourth path — never a silent fallback

Each translation runs in an isolated, empty temporary directory with a minimal environment. What leaves the machine is limited to: the English request, shell type, OS, architecture, a privacy-normalized directory label, and a fixed list of detected tools. Shell history, environment variables, file contents, credentials, and usernames are never sent.

Architecture and Setup Path

HumanSH is distributed as a single Go binary installed via a one-line curl script that verifies a SHA-256 checksum before writing to ~/.local/bin — no sudo required. A guided humansh setup command detects every supported shell, shows the exact startup-file patches it will apply, and writes nothing until the user confirms. Configuration lives under $XDG_CONFIG_HOME/humansh/; secrets are stored in the OS keychain and never written to config.toml. Diagnostics are available via humansh doctor, and humansh uninstall --purge cleanly removes all configuration and credentials after explicit confirmation.

Update: v0.1.4

The latest release is v0.1.4, published on August 26, 2026. The repository was created on August 20, 2026, making this a very early-stage project with active development. The GitHub repository shows 5 stars and 5 open issues as of late August 2026, with the primary language being Go and the license being MIT.