zsh-ai-cli

Backend-agnostic Zsh AI assistant. Converts natural language into a shell command and drops it into the current ZLE buffer.

It never executes commands automatically.

• AI suggests.
• Human reviews.
• Human presses Enter.

How it works

User → Ctrl-G (ZLE widget) → zsh-ai-cli CLI → Backend (OpenCode, via @opencode-ai/sdk) → LLM
     → generated shell command → replace ZLE BUFFER

Install

npm install -g zsh-ai-cli

or

brew install trongnghia203/zsh-ai-cli/zsh-ai-cli

or from source (contributors):

git clone https://github.com/trongnghia203/zsh-ai-cli.git
cd zsh-ai-cli
npm install
npm run build
npm link   # exposes `zsh-ai-cli` on PATH

Then run zsh-ai-cli setup — it prints the exact source line to add to your .zshrc for wherever it was installed. Add that line yourself (zsh-ai-cli never edits shell config for you), then press Ctrl-G with a natural language instruction in your prompt buffer.

Daemon mode (optional)

By default every Ctrl-G press is a stateless one-shot call — no setup needed, works out of the box. For conversation continuity across follow-up questions in the same project, opt into daemon mode:

zsh-ai-cli setup     # check-and-print: is everything in place
zsh-ai-cli start      # spawn a persistent opencode server
zsh-ai-cli status     # daemon + per-project session info
zsh-ai-cli refresh    # discard this directory's session, start fresh
zsh-ai-cli stop
zsh-ai-cli uninstall  # stop daemon, remove cache/session state, print manual cleanup steps

See docs/daemon.md for the full design.

Requirements

• Node.js >= 18
• OpenCode CLI on PATH, authenticated (opencode providers list) — the SDK backend (@opencode-ai/sdk) spawns it as a local server per call, still requires the binary itself

Development

npm test    # node --test, via tsx, no build step needed

See docs/development.md for the full dev workflow, zsh-ai-cli --help for the CLI's own command list.

Status

v0.1 (stateless backend) and v0.2's daemon mode both done — see docs/implementation-plan.md for the live checklist, docs/roadmap.md for the high-level shape.

References / prior art

Other tools solving a similar problem, looked at for inspiration and contrast during design (see docs/architecture.md and docs/security.md for the specific comparisons):

• chhlga/zsh-opencode-plugin — closest match to this project's shape: a zsh widget calling OpenCode, spinner while waiting, markdown/backtick/first-line output stripping. Confirmed several of this project's early assumptions.
• savvy-ravvy/opencode-shell-plugin — classifies input complexity and auto-executes "simple" commands on Enter. The opposite of this project's core principle; kept as a cautionary reference, not a model to follow.
• kriserickson/ai-cli — a more mature Go CLI with a genuinely different philosophy: a risk/certainty scoring matrix decides whether to auto-execute, ask, or always-ask, with configurable allowlists. Same "sometimes auto-execute" territory this project rejects, but a much more thought-out version of it than savvy-ravvy's. Worth the read for its other ideas even where the execution philosophy differs: named "memories" injected into prompts, and retrying a failed command with the failure fed back to the model — see docs/context.md for where the memories idea could fit here.