lacy.sh/docs
GitHub

Introduction

Lacy Shell is a ZSH and Bash 4+ plugin that adds AI to your terminal — without replacing it. Type commands normally. Ask questions naturally. Everything runs in your existing shell.

What it does

When you press Enter, Lacy detects whether you typed a shell command or natural language. Shell commands execute as usual. Natural language routes to your preferred AI CLI tool — Claude, Gemini, lash, opencode, codex, or anything you configure.

No prefix. No mode switching. No new terminal. Just type.

$ls -lashell
$what files are hereagent
$git statusshell
$fix the build error in src/index.tsagent

How routing works

In Auto mode, Lacy applies a six-rule cascade to classify your input before executing:

  1. Matches an agent word (like what, why, fix, explain) → Agent
  2. Starts with a shell reserved word (do, in, then) → Agent
  3. First word is a valid command → Shell
  4. Single word, not a command → Shell (typo, let it error)
  5. Multiple words, first not a command → Agent (natural language)
  6. Valid command fails with NL-style arguments → Shell first, then Agent silently

See How Detection Works for the full specification.

Visual feedback

A real-time indicator to the left of your prompt changes color as you type:

  • Green — will execute in shell
  • Magenta — will go to AI agent
  • Gray — neutral / no input yet

ZSH users also get first-word syntax highlighting and a right-prompt mode badge.

Supported shells

  • ZSH — full feature set: real-time indicator, first-word highlighting, ghost text suggestions, right-prompt mode badge
  • Bash 4+ — core routing, mode badge in PS1, Ctrl+Space toggle. macOS ships Bash 3.2 — upgrade via Homebrew.
Note

macOS ships with Bash 3.2 (GPL2). Install Bash 4+ via Homebrew: brew install bash

Supported AI tools

Lacy works with any AI CLI that accepts a query argument. Supported out of the box: lash (recommended), claude, opencode, gemini, codex, hermes, and custom commands. All tools handle their own authentication — no API keys needed from Lacy.

See Supported AI Tools for the full list and configuration.

Quick install

bash
curl -fsSL https://lacy.sh/install | bash

Then reload your shell and type naturally. Continue to Installation for all install methods and prerequisites.

Next →Installation