Troubleshooting

Start with lacy doctor — it diagnoses the most common issues automatically.

lacy doctor

bash

lacy doctor

Checks: installation path, shell config sourcing, AI tool availability, PATH, version.

Common issues

Plugin not loading

Verify the source line is in your shell config:

bash

grep "lacy" ~/.zshrc      # ZSH
grep "lacy" ~/.bashrc     # Bash

If missing, re-run the installer or add manually:

bash

echo 'source ~/.lacy/lacy.plugin.zsh' >> ~/.zshrc
source ~/.zshrc

No AI tool found

bash

tool   # shows available tools and what Lacy detected

If no tool is installed, install lash (recommended):

bash

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

Indicator not showing

The indicator requires ZSH with ZLE. Check your shell:

bash

echo $SHELL   # should be /bin/zsh or similar

In Bash, there is no real-time indicator — only a PS1 badge that updates after each command.

Commands routing to wrong destination

Check current mode and toggle if needed:

bash

mode          # check current mode
mode auto     # reset to auto
# Or press Ctrl+Space to cycle modes

Reroute triggering unexpectedly

Post-execution reroute only fires in Auto mode when both error pattern and NL signal match. Check if you're in Auto mode (mode) and whether your command output matches a known error pattern.

zsh-autosuggestions conflicts

Ensure Lacy is sourced after zsh-autosuggestions in your .zshrc. Lacy handles coexistence by tagging its region_highlight entries with memo=lacyand coordinating POSTDISPLAY access.

Bash 3.2 on macOS

Warning

macOS ships Bash 3.2. Lacy requires 4+. Install: brew install bash, then update your shell.

Emergency bypass

If Lacy routes something wrong, prefix with ! to force shell execution:

bash

!your-command-here   # always runs in shell

Still stuck?

Run lacy status and lacy doctor and include the output
Open an issue: github.com/lacymorrow/lacy/issues