Local-AI Agent v0.8.8.11-beta

Gemini-3.1-Flash-Lite   Openrouter/free   Local-Ai Model

---

How the Agent Works

All configurations are managed through your master blueprint: ai-context.md.

Routing Logic: The agent automatically determines the optimal execution path based on your input pattern, ensuring zero wasted tokens.

• No Session (Direct selections): Uses a fast Jaccard Similarity engine (jaccard_search) with prefix-matching to instantly route custom commands and shortcuts to your local terminal.
• Single-Turn Agent (ai <query>): Answers a single question and returns you to Bash, executing explicitly mapped diagnostic tools and skills only when requested.
• Workspace Agents (ai init <path>): Compiles a path-specific structural tree directly inside your active workspace using index-map, launching a dedicated, codebase-aware agent session primed with your chosen skill file.

---

Core Pillars & Capabilities

Pillar	Capability	Description
Performance	Zero-Daemon	0% idle CPU/RAM. Ultra-lite execution.
Search Engine	Jaccard Similarity	Sub-millisecond keyword and partial-word matching.
Resiliency	Fallbacks	Automatically cascades: Gemini → OpenRouter → Local.
Safety	Zero-Trust Guardrails	Intercepts destructive commands before shell execution.
Integration	Dynamic Context	On-demand compilation of system specs and file contents.
Optimization	Token-Slasher	Custom tool and skill integration built for minimal token use.
Interface	Conversational TUI	Rich, multi-turn chat sessions directly in the terminal.
Auditability	Zero-Dependency	Under 450 lines of standard-library Python.

---

TUI Carousel Controls

• Up / Down Arrow Keys: Cycle through available ranked selections.
• Enter: Execute the highlighted command (or initialize a workspace if the selection is a directory path).
• Esc / Ctrl+C / Any Key: Cancel the menu.

~ ❯ weather
[01/02] ❯ [weather full] curl -s wttr.in | cat
:: ↵ run  Esc:

Command Reference

Command	Description
ai	Launch interactive, multi-turn chat session.
ai <query>	Instant answer; returns directly to Bash prompt.
ai init <path>	Index directory & launch codebase-aware agent.
hs	On-demand keyword search of workspace history.
hist	View workspace history log (history.md).

Command	Description
/s <query> / /skill	Search and load dynamic department skills on-the-fly.
view file <path>	Dynamically read local files on-the-fly into model context.
-save <tag>	Snapshot current conversation directly to local SQLite database.
-timeline / -load	Rollback active memory to a past SQLite checkpoint.
/f /t /b /a	Trigger Follow-up, Thinking, Brainstorm, or all.

---

Agent Blueprint

Add your shortcuts, commands, and workspaces to ai-context.md.

# --- Weather & Live Networking ---
[TOOL] curl -s wttr.in --cat ---> weather full, wttr, weather
[TOOL] curl -s "wttr.in/?format=3" --cat ---> weather simple, wttr, weather

# --- Local-Ai Agent Blueprint (CheatSheet) ---
~/.config/local-ai/tools/blueprint --leaf ---> cheatsheet, blueprint, bp, cs

---

Setup & Prerequisites

# 1. Optional: Install mdcat for native terminal Markdown rendering
yay mdcat

# 2. Clone the repository locally
git clone https://github.com/j5onrf/local-ai.git ~/.config/local-ai

# 3. Inject the environment hook into Bash & reload your profile
AI_SRC='$HOME/.config/local-ai/ai-hook.sh'
printf '[ -f "%s" ] && source "%s"\n' "$AI_SRC" "$AI_SRC" >> ~/.bashrc
source ~/.bashrc

# 4. Optional: Export cloud API keys to enable remote fallback routing
export GEMINI_API_KEY="AIzaSyYourFullGeminiApiKeyHere"
export CLOUD_MODEL="gemini-3.1-flash-lite"
export OPENROUTER_API_KEY="sk-or-v1-YourFullOpenRouterKeyHere"
export OPENROUTER_MODEL="openrouter/free"