# HumanSH

> HumanSH is an open-source CLI tool that translates plain English into reviewable shell commands directly in your terminal, without switching apps or auto-executing anything.

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.

## Features
- Plain English to shell command translation
- Review-before-execute workflow
- Local intent classification (no provider call for real commands)
- Smart Enter for Zsh (auto-classify on Enter)
- Explicit Ctrl-G force-translation for Bash
- Risk-gated confirmation for destructive commands
- Supports ChatGPT (Codex), Claude, Cursor, and OpenRouter providers
- No telemetry or analytics
- No shell history, env vars, or file contents sent
- Isolated empty temp directory for each translation
- OS keychain credential storage
- Customizable key bindings
- humansh doctor health check and repair
- Custom classifier training for project-specific commands
- SHA-256 verified binary install, no sudo required

## Integrations
Codex CLI (ChatGPT), Claude Code CLI, Cursor CLI, OpenRouter API, Zsh (ZLE layer), Bash 4.3+ (Readline layer), macOS Keychain, Linux secret store

## Platforms
MACOS, LINUX, API, CLI

## Pricing
Open Source

## Version
v0.1.4

## Links
- Website: https://humansh.com
- Documentation: https://github.com/agenticlab-ai/humansh/blob/main/README.md
- Repository: https://github.com/agenticlab-ai/humansh
- EveryDev.ai: https://www.everydev.ai/tools/humansh