https://github.com/lacymorrow/lacy
Talk to your shell — commands run, questions go to AI. No prefixes.
https://github.com/lacymorrow/lacy
ai ai-agent ai-cli ai-coding ai-coding-assistant ai-shell ai-terminal bash claude cli coding-agent developer-tools devtools mcp productivity shell terminal zsh
Last synced: about 7 hours ago
JSON representation
Talk to your shell — commands run, questions go to AI. No prefixes.
- Host: GitHub
- URL: https://github.com/lacymorrow/lacy
- Owner: lacymorrow
- License: other
- Created: 2025-08-18T16:54:55.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-06-14T20:51:05.000Z (22 days ago)
- Last Synced: 2026-06-28T22:07:08.715Z (8 days ago)
- Topics: ai, ai-agent, ai-cli, ai-coding, ai-coding-assistant, ai-shell, ai-terminal, bash, claude, cli, coding-agent, developer-tools, devtools, mcp, productivity, shell, terminal, zsh
- Language: Shell
- Homepage: https://lacy.sh
- Size: 42.1 MB
- Stars: 18
- Watchers: 0
- Forks: 2
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Security: .github/SECURITY.md
Awesome Lists containing this project
- awesome-zsh-plugins - lacy - Detects natural language vs shell commands and routes accordingly. Commands execute normally, questions go to your AI agent (Claude Code, Gemini, OpenCode, Codex). Real-time color indicator and first-word syntax highlighting update on every keystroke. Also supports Bash 4+. (Plugins / ZSH on Windows)
- fucking-awesome-zsh-plugins - lacy - Detects natural language vs shell commands and routes accordingly. Commands execute normally, questions go to your AI agent (Claude Code, Gemini, OpenCode, Codex). Real-time color indicator and first-word syntax highlighting update on every keystroke. Also supports Bash 4+. (Plugins / ZSH on Windows)
README
Talk to your shell. Commands run. Questions go to AI. No prefixes. No context switching. You just type.
## Why Lacy?
- **No new tools to learn** — Lacy works with your existing AI CLI (Claude Code, Gemini, OpenCode, Codex, Lash). It's a complement, not a replacement.
- **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.
> *Works with ZSH and Bash 4+ on macOS, Linux, and WSL.*
## Install
> Supported installation methods: `npm`, `curl`, `homebrew`, `git`
#### Install using `npx`
```bash
npx lacy
```
#### Install using `curl`
```bash
curl -fsSL https://lacy.sh/install | bash
```
Other methods
```bash
# Homebrew
brew tap lacymorrow/tap
brew install lacy
# Manual
git clone https://github.com/lacymorrow/lacy.git ~/.lacy
echo 'source ~/.lacy/lacy.plugin.zsh' >> ~/.zshrc
```
## 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 — you just type.
| 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 |
The first word of your input is also syntax-highlighted in real-time: **green** for shell commands, **magenta** for AI queries.
**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 — they pass `command -v` but are never standalone commands.
**Terminal context**: When you ask the AI a question, lacy automatically includes your current directory, git branch, recent commands, and exit codes, but only what changed since your last query. In supported terminals (tmux, screen, iTerm2, Terminal.app), it also captures the visible screen output so the agent can see error messages and stack traces.
## 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` |
## Supported Tools
Lacy auto-detects your installed AI CLI. All tools handle their own auth — no API keys needed.
```bash
tool set claude # Use Claude Code
tool set lash # Use Lash
tool set auto # Auto-detect (first available)
```
Or edit `~/.lacy/config.yaml`:
```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 ` | 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):
```bash
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
```
## Uninstall
```bash
lacy uninstall
# or
npx lacy --uninstall
# or
curl -fsSL https://lacy.sh/install | bash -s -- --uninstall
```
## Configuration
Config file: `~/.lacy/config.yaml`
```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`
## Releasing
Requires [Bun](https://bun.sh), [gh](https://cli.github.com), and `npm login`.
```bash
bun run release # interactive — prompts for patch/minor/major
bun run release patch # patch bump (1.5.3 → 1.5.4)
bun run release minor # minor bump (1.5.3 → 1.6.0)
bun run release major # major bump (1.5.3 → 2.0.0)
bun run release 2.0.0 # explicit version
```
The script handles the full release flow:
1. Bumps version in both `package.json` files
2. Commits with `release: v` and tags
3. Pushes to GitHub and creates a GitHub release
4. Publishes the npm package (prompts for OTP if required)
## Support This Project
Lacy Shell is free and open source. If it saves you time, consider sponsoring the project:
[](https://github.com/sponsors/lacymorrow)
Your support keeps development active and helps cover infrastructure costs.
## Contributors Welcome
Lacy is open source and contributions are welcome! Whether you're fixing a typo, adding a feature, or improving docs, we'd love your help.
- **[Good First Issues](https://github.com/lacymorrow/lacy/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)** -- great starting points for new contributors
- **[Contributing Guide](CONTRIBUTING.md)** -- dev setup, code style, and PR process
- **[Discussions](https://github.com/lacymorrow/lacy/discussions)** -- questions, ideas, and general chat
## Star History
## License
[FSL-1.1-MIT](LICENSE) — Functional Source License v1.1 with MIT Future License (converts to MIT after 2 years). See [fsl.software](https://fsl.software) for the full text.