# Lacy Shell

> Talk to your shell. Commands run. Questions go to AI. No prefixes. No context switching. You just type.

## What is Lacy?
Lacy is a ZSH/Bash plugin that adds AI to your existing terminal. Type commands normally and they run in your shell. Type natural language and it routes to your AI agent (Claude Code, Gemini, Codex, etc). Real-time color indicators show what will happen before you press enter.

Works with ZSH and Bash 4+ on macOS, Linux, and WSL.

## Why Lacy?
- No new tools to learn. Lacy works with your existing AI CLI (Claude Code, Gemini, OpenCode, Codex, Lash). It complements, not replaces.
- Zero friction. No slash commands, no hotkeys, no separate terminal. Type naturally and Lacy routes it. A real-time color indicator shows you what will happen before you press enter.
- Smart detection. Lacy classifies input using word analysis, not AI. It's instant. Commands like `ls -la` stay green (shell). Questions like `what files are here` turn magenta (AI). If a command fails with natural language patterns, it silently reroutes to AI.

## Install

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

### Other methods

Homebrew:
  brew install lacymorrow/tap/lacy

npx (interactive):
  npx lacy

Manual:
  git clone https://github.com/lacymorrow/lacy.git ~/.lacy
  echo 'source ~/.lacy/lacy.plugin.zsh' >> ~/.zshrc   # ZSH
  echo 'source ~/.lacy/lacy.plugin.zsh' >> ~/.bashrc   # Bash

### Uninstall

  lacy uninstall
  # or
  npx lacy --uninstall
  # or
  curl -fsSL https://lacy.sh/install | bash -s -- --uninstall

## How It Works

Real-time visual feedback shows what will happen before you hit enter. Commands execute in your shell. Natural language goes to your AI agent. No prefixes, no context switching.

The first word of your input is syntax-highlighted in real-time: green for shell commands, magenta for AI queries.

## Routing Table

| Input                          | Routes to  | Why                                         |
| ------------------------------ | ---------- | ------------------------------------------- |
| ls -la                         | Shell      | Valid command                               |
| what files are here            | AI         | Natural language                            |
| git status                     | Shell      | Valid command                               |
| do we have a way to install?   | AI         | Reserved word, never a real command          |
| fix the bug                    | AI         | Multi-word, not a command                   |
| kill the process on 3000       | Shell > AI | Valid command, but fails; rerouted           |
| go ahead and fix it            | Shell > AI | "go" is valid, but "ahead" triggers reroute |
| !rm -rf *                      | Shell      | ! prefix forces shell                       |

## Smart Rerouting (Auto Mode)

When a valid command contains natural language patterns (3+ bare words with articles, pronouns, etc.) and fails, Lacy shows a hint and automatically re-sends it to the AI agent. Shell reserved words like `do`, `then`, `in`, `else` are routed directly to the agent since they pass `command -v` but are never standalone commands.

## Modes

| Mode   | Behavior                | Activate                     |
| ------ | ----------------------- | ---------------------------- |
| Auto   | Smart routing (default) | mode auto                    |
| Shell  | Everything to shell     | mode shell or Ctrl+Space     |
| Agent  | Everything to AI        | mode agent or Ctrl+Space     |

Press Ctrl+Space to toggle between Shell and Agent modes. Use `mode auto` to return to smart routing.

## Supported AI Tools

Lacy auto-detects your installed AI CLI. All tools handle their own auth; no API keys needed in Lacy.

Supported tools: Claude Code, Gemini CLI, Codex, OpenCode, Lash, Pi.

### Setting the active tool

  tool set claude    # Use Claude Code
  tool set lash      # Use Lash
  tool set auto      # Auto-detect (first available)

Or edit ~/.lacy/config.yaml:

  agent_tools:
    active: claude  # lash, claude, opencode, gemini, codex, custom, or empty for auto

## Commands

| Command                      | Description          |
| ---------------------------- | -------------------- |
| mode                         | Show current mode    |
| mode [shell|agent|auto]      | Switch mode          |
| tool                         | Show active AI tool  |
| tool set <name>              | Set AI tool          |
| ask "query"                  | Direct query to AI   |
| Ctrl+Space                   | Toggle between modes |

## CLI

After installation, the `lacy` command is available (no Node required):

  lacy setup        # Interactive settings (tool, mode, config)
  lacy status       # Show installation status
  lacy doctor       # Diagnose common issues
  lacy update       # Pull latest changes
  lacy config edit  # Open config in $EDITOR
  lacy uninstall    # Remove Lacy Shell
  lacy help         # Show all commands

## Configuration

Config file: ~/.lacy/config.yaml

  agent_tools:
    active: claude  # lash, claude, opencode, gemini, codex, or empty for auto

  modes:
    default: auto  # shell, agent, auto

  api_keys:
    openai: "sk-..."       # Only needed if no CLI tool installed
    anthropic: "sk-ant-..."

## Troubleshooting

No AI response: Check `tool` to see if a tool is detected. Install one: `npm i -g lashcode` or `brew install claude`.

Colors not showing: Ensure your terminal supports 256 colors (green=34, magenta=200, blue=75).

Command rerouted unexpectedly: In auto mode, commands with natural language patterns that fail are re-sent to the AI. Switch to `mode shell` to disable this, or prefix with `!`.

Emergency bypass: Prefix any command with `!` to force shell execution: `!rm -rf node_modules`

## Links
- Website: https://lacy.sh
- GitHub: https://github.com/lacymorrow/lacy
- npm: https://www.npmjs.com/package/lacy
- Twitter: https://twitter.com/lacybuilds
- License: MIT