feat: add caching, shell integration, aliases, script/recipe mode, streaming animation, and more

Performance:
- Skip tool extraction for coreutils-only prompts (eliminates LLM call)
- Prompt→command cache (hash-based JSONL at ~/.cache/eai/)
- Auto-retry on 429 rate limit (3s wait)

Accuracy:
- Few-shot examples in system prompt (3 diverse examples)
- Project context detection (Cargo.toml, package.json, go.mod, Dockerfile, etc.)
- Post-generation validation (warns if binary not in PATH)

New modes:
- --script: generate full shell scripts instead of one-liners
- --recipe: generate numbered step-by-step workflows
- --demo: curated examples without API key

UX:
- Typewriter animation on first command display
- Shell integration via Ctrl+E (zsh/bash/fish) — `eai init <shell>`
- Shell completions via clap_complete — `eai completions <shell>`
- Command bookmarks — `eai save`, `eai @alias`, `eai aliases`, `eai unsave`
- Fuzzy history search with scoring
- Pipe mode auto-detects content type (JSON, CSV, error output, HTML, Markdown)

Made-with: Cursor

Author: feliperun

AGENTS.md

@@ -9,18 +9,20 @@ Rust CLI that converts natural language to shell commands using LLMs. Single bin
 ```
 src/
   main.rs          — entry point, tokio runtime
-  cli.rs           — clap arg definitions (Cli, Commands)
-  app.rs           — orchestration: prompt → generate → confirm → execute loop
+  cli.rs           — clap arg definitions (Cli, Commands, shell completions)
+  app.rs           — orchestration: prompt → generate → confirm → execute loop, modes (script/recipe/explain/demo)
   config.rs        — TOML config at ~/.config/eai/config.toml
   setup.rs         — interactive onboarding wizard (eai setup) + optional Tavily setup
-  ui.rs            — all terminal rendering: banner, gradient box, action bar, spinners, tool suggestions
+  ui.rs            — all terminal rendering: banner, gradient box, action bar, spinners, typewriter animation
   types.rs         — shared types: BackendKind, ShellKind, CommandRequest, GeneratedCommand
   tool_context.rs  — tool detection, discovery, package registry verification, install flow
   tldr.rs          — embedded tldr-pages lookup (7000+ commands, zstd-compressed, O(1) HashMap)
+  cache.rs         — file-based prompt→command cache at ~/.cache/eai/cache.jsonl
+  aliases.rs       — command bookmarks at ~/.config/eai/aliases.json
   search.rs        — web search: Tavily (preferred) or DuckDuckGo (fallback)
   history.rs       — append-only JSONL history at ~/.local/share/eai/history.jsonl
   llm/
-    mod.rs         — Backend trait, prompt building, response parsing, backend resolution, shell profile fallback
+    mod.rs         — Backend trait, prompt building, response parsing, OS flag correction, backend resolution
     openai.rs      — OpenAI-compatible client (also used for Groq, OpenRouter)
     ollama.rs      — Ollama local client
     claude.rs      — Claude CLI wrapper
@@ -32,15 +34,20 @@ build.rs           — downloads tldr-pages at build time, parses markdown, seri
 - All UI output goes to **stderr** (`eprintln!`). Only command execution output goes to stdout.
 - RGB gradients use raw ANSI escapes (`\x1b[38;2;R;G;Bm`) with `colors_enabled_stderr()` fallback.
 - `GeneratedCommand` has `.command` (the shell command) and `.explanation` (optional `//` comment from LLM).
-- `parse_response` in `llm/mod.rs` extracts command + explanation from LLM output. Tolerant of markdown fences.
-- Tool extraction uses a separate LLM call. Filter: ASCII-only, `is_noise_word()` blocklist, max 5 tools.
-- Pipe mode: `read_stdin_if_piped()` reads up to 4K chars from stdin when not a terminal.
+- `parse_response` in `llm/mod.rs` extracts command + explanation from LLM output. Tolerant of markdown fences. Applies OS-specific flag corrections.
+- Tool extraction uses a separate LLM call. Filter: ASCII-only, `is_noise_word()` blocklist, max 5 tools. Skipped for coreutils-only prompts.
+- Pipe mode: `read_stdin_if_piped()` reads up to 4K chars from stdin; auto-detects content type (JSON, CSV, error output, etc.).
 - The `build_openai_compat()` helper in `llm/mod.rs` handles both Groq and OpenAI backends.
 - API keys read from env vars; `env_var()` in `llm/mod.rs` falls back to reading from shell profile.
 - Tool docs resolution: embedded tldr-pages (instant O(1) lookup) + `--help` output combined. Even tools not installed get tldr docs.
 - Tool discovery: when all extracted tools are missing, searches web + LLM suggests alternatives, verifies against package registries (brew, PyPI, npm, crates.io), offers interactive install.
 - Search hierarchy: Tavily (if `TAVILY_API_KEY` set) → DuckDuckGo (fallback). Configured via `search.engine` in config.
 - Setup hides API key input (Password prompt) and validates keys with retry on 401.
+- Prompt→command cache (hash-based) avoids repeated LLM calls for identical prompts.
+- Post-generation validation checks if the main binary exists in PATH and warns if not.
+- Project context detection (Cargo.toml, package.json, go.mod, etc.) enriches the LLM prompt.
+- 429 rate-limit auto-retry (3s wait) before surfacing the error.
+- Typewriter animation on first command display (TTY only).
 
 ## Conventions
 

Cargo.lock

@@ -17,6 +17,7 @@ async-trait = "0.1"
 bincode = "2"
 chrono = { version = "0.4", features = ["serde"] }
 clap = { version = "4.5", features = ["derive"] }
+clap_complete = "4.6.2"
 console = "0.15"
 dialoguer = "0.11"
 dirs = "6.0"

Cargo.toml

@@ -131,12 +131,57 @@ When you ask for a tool that isn't installed, eai searches the web, finds real a
   ╰──────────────────────────────────────────────╯
 ```
 
+### Script mode — full scripts instead of one-liners
+
+```bash
+eai --script "backup my database and compress it" > backup.sh
+eai --script "setup a new Node.js project with TypeScript" > setup.sh
+```
+
+### Recipe mode — step-by-step workflows
+
+```bash
+eai --recipe "deploy a docker container to production"
+# Step 1: Build the image
+#   ❯ docker build -t myapp .
+# Step 2: Tag for registry
+#   ❯ docker tag myapp registry.example.com/myapp:latest
+# ...
+```
+
+### Command aliases — save & reuse
+
+```bash
+eai save deploy "git push origin main" --desc "push to production"
+eai @deploy               # runs the saved command directly
+eai aliases               # list all saved aliases
+eai unsave deploy          # remove an alias
+```
+
+### Shell integration — Ctrl+E
+
+```bash
+eval "$(eai init zsh)"    # add to .zshrc
+eval "$(eai init bash)"   # add to .bashrc
+eai init fish | source    # add to config.fish
+# Then press Ctrl+E to translate the current line into a command
+```
+
+### Demo mode — try without API key
+
+```bash
+eai --demo                # shows curated examples, no LLM needed
+```
+
 ### Flags
 
 ```bash
 eai --dry "..."          # show command, don't run
 eai --explain "..."      # explain a command (alias: --wtf)
+eai --script "..."       # generate a full shell script
+eai --recipe "..."       # generate a multi-step workflow
 eai --search "..."       # force web search before generating
+eai --demo               # offline demo with sample commands
 eai -b groq "..."        # force a specific backend
 eai -m llama-3.3-70b-versatile "..."  # force a specific model
 eai --no-confirm "..."   # skip confirmation (yolo)
@@ -150,6 +195,11 @@ eai setup                # interactive provider setup wizard
 eai config               # open config in $EDITOR
 eai history              # show recent commands
 eai history --search docker
+eai completions zsh      # generate shell completions
+eai init zsh             # output Ctrl+E shell integration
+eai save <name> <cmd>    # bookmark a command
+eai aliases              # list bookmarks
+eai unsave <name>        # remove bookmark
 ```
 
 ## How it works
@@ -234,13 +284,19 @@ The suite uses a mocked `claude` CLI and validates end-to-end flows for:
 
 | Feature | eai | llm | aichat | shell-gpt |
 |---|---|---|---|---|
-| **Pipe context (stdin)** | ✓ | ✓ | ✓ | ✓ |
+| **Pipe context (stdin)** | ✓ (auto-detects JSON/CSV/error) | ✓ | ✓ | ✓ |
 | **Explain mode** | ✓ (`--wtf`) | ✗ | ✗ | partial |
+| **Script/recipe generation** | ✓ (`--script`, `--recipe`) | ✗ | ✗ | ✗ |
+| **Command caching** | ✓ (instant repeat queries) | ✗ | ✗ | ✗ |
+| **Shell integration (Ctrl+E)** | ✓ (zsh/bash/fish) | ✗ | ✗ | ✗ |
+| **Command bookmarks** | ✓ (`save`/`@alias`) | ✗ | ✗ | ✗ |
+| **Project-aware** | ✓ (auto-detects Cargo/npm/Go/Docker) | ✗ | ✗ | ✗ |
 | **Free by default** | ✓ (Gemini/Groq/Ollama) | ✗ (OpenAI) | ✗ (Needs API) | ✗ (OpenAI) |
 | **Auto-retry on error** | ✓ (feeds stderr back) | ✗ | ✗ | ✗ |
 | **Web search** | ✓ (Tavily/DDG) | ✗ (plugins) | partial | ✗ (plugins) |
 | **Tool doc detection** | ✓ (7000+ embedded + --help) | ✗ | ✗ | ✗ |
 | **Tool discovery + install** | ✓ (registry-verified) | ✗ | ✗ | ✗ |
+| **Shell completions** | ✓ (zsh/bash/fish) | ✗ | ✗ | ✗ |
 | **Setup wizard** | ✓ (30s) | ✗ | ✓ | ✗ |
 | **Single binary** | ✓ (Rust) | Python | ✓ (Rust) | Python |
 

README.md

@@ -0,0 +1,75 @@
+use std::collections::HashMap;
+use std::fs;
+use std::path::PathBuf;
+
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize, Default)]
+struct AliasStore {
+    aliases: HashMap<String, AliasEntry>,
+}
+
+#[derive(Serialize, Deserialize, Clone)]
+pub struct AliasEntry {
+    pub command: String,
+    pub description: Option<String>,
+}
+
+fn aliases_path() -> Result<PathBuf> {
+    let dir = dirs::config_dir()
+        .context("cannot find config dir")?
+        .join("eai");
+    fs::create_dir_all(&dir)?;
+    Ok(dir.join("aliases.json"))
+}
+
+fn load_store() -> Result<AliasStore> {
+    let path = aliases_path()?;
+    if !path.exists() {
+        return Ok(AliasStore::default());
+    }
+    let data = fs::read_to_string(&path)?;
+    Ok(serde_json::from_str(&data).unwrap_or_default())
+}
+
+fn save_store(store: &AliasStore) -> Result<()> {
+    let path = aliases_path()?;
+    let data = serde_json::to_string_pretty(store)?;
+    fs::write(&path, data)?;
+    Ok(())
+}
+
+pub fn save(name: &str, command: &str, description: Option<&str>) -> Result<()> {
+    let mut store = load_store()?;
+    store.aliases.insert(
+        name.to_string(),
+        AliasEntry {
+            command: command.to_string(),
+            description: description.map(|s| s.to_string()),
+        },
+    );
+    save_store(&store)?;
+    Ok(())
+}
+
+pub fn get(name: &str) -> Result<Option<AliasEntry>> {
+    let store = load_store()?;
+    Ok(store.aliases.get(name).cloned())
+}
+
+pub fn list() -> Result<Vec<(String, AliasEntry)>> {
+    let store = load_store()?;
+    let mut entries: Vec<_> = store.aliases.into_iter().collect();
+    entries.sort_by(|a, b| a.0.cmp(&b.0));
+    Ok(entries)
+}
+
+pub fn remove(name: &str) -> Result<bool> {
+    let mut store = load_store()?;
+    let removed = store.aliases.remove(name).is_some();
+    if removed {
+        save_store(&store)?;
+    }
+    Ok(removed)
+}