Architecture

Name: Lacy Shell
Availability: OnlineOnly
Author: Lacy Morrow

Lacy Shell is a pure bash/zsh plugin with a Node.js installer package. All core logic lives in ~/.lacy/. No runtime dependencies in the shell path.

File tree

text

~/.lacy/
├── lacy.plugin.zsh          # Entry point (ZSH)
├── lacy.plugin.bash         # Entry point (Bash 4+)
├── config.yaml              # User configuration
├── install.sh               # Installer (bash + npx fallback)
├── uninstall.sh             # Uninstaller
├── bin/
│   └── lacy                 # Standalone CLI (no Node required)
└── lib/
    ├── core/                    # Shared modules (Bash 4+ and ZSH)
    │   ├── constants.sh         # Colors, timeouts, paths, detection arrays
    │   ├── config.sh            # YAML config, API key management
    │   ├── modes.sh             # Mode state (shell/agent/auto)
    │   ├── spinner.sh           # Loading spinner with shimmer text effect
    │   ├── mcp.sh               # Multi-tool routing (LACY_TOOL_CMD registry)
    │   ├── preheat.sh           # Background server + session reuse
    │   ├── context.sh           # Delta-based terminal context
    │   ├── detection.sh         # classify_input(), detect_natural_language()
    │   └── commands.sh          # Shared commands: mode, tool, session, quit
    ├── zsh/
    │   ├── keybindings.zsh      # Ctrl+Space toggle, indicator, region_highlight
    │   ├── prompt.zsh           # Prompt with indicator, mode in RPS1
    │   └── execute.zsh          # Execution routing, reroute, slash-command interception
    └── bash/
        ├── init.bash            # Bash adapter init
        ├── keybindings.bash     # Macro-based Enter override, Ctrl+Space toggle
        ├── prompt.bash          # Mode badge in PS1
        └── execute.bash         # Execution routing

Key modules

File	Purpose
`lib/core/detection.sh`	Single source of truth for input classification. `lacy_shell_classify_input()` is the canonical function.
`lib/core/constants.sh`	All detection arrays: `LACY_AGENT_WORDS`, `LACY_SHELL_RESERVED_WORDS`, `LACY_NL_MARKERS`, `LACY_SHELL_ERROR_PATTERNS`.
`lib/core/mcp.sh`	Tool command registry and `lacy_shell_query_agent()` routing.
`lib/core/context.sh`	Delta-based terminal context injection. `_lacy_build_query_context()`.
`lib/zsh/keybindings.zsh`	Real-time indicator, first-word `region_highlight`, plugin coexistence.
`lib/zsh/execute.zsh`	Execution routing, reroute candidates, slash-command interception.

Data flow

text

User types input
    │
    ▼
lacy_shell_classify_input()  ← lib/core/detection.sh
    │
    ├─ "shell"  → execute in shell
    │               │
    │               ▼
    │           exit code non-zero?
    │               │ yes
    │               ▼
    │           lacy_shell_detect_natural_language()
    │               │ match
    │               ▼
    │           reroute to agent ──────────────────┐
    │                                              │
    └─ "agent"  → _lacy_build_query_context()      │
                    │                              │
                    ▼                              │
                lacy_shell_query_agent() ◄─────────┘
                    │
                    ▼
                Run LACY_TOOL_CMD with context-prefixed query

npm package

The lacy npm package (packages/lacy/) is only the interactive Node.js installer/setup UI, built with @clack/prompts. It is not loaded in the shell path — it runs via npx lacy@latest when needed and falls back to bash automatically.