Local-AI Agent v0.9.1.1-beta

gpt   claude   grok   gemini   openrouter   gguf

---

How the Agent Works

All configurations and custom shortcuts are managed in ai-context.md.

• Direct (No Session): Sub-millisecond Jaccard matching (jaccard_search) instantly routes custom keywords to your local terminal.
• Single-Turn Agent (ai <query>): Returns a single response directly to your shell prompt without loading an active conversation.
• Multi-Turn Chat (ai alone): Starts a persistent terminal session with multi-turn context tracking.
• Workspace Agents (ai init <path>): Indexes your directory into a lightweight codebase graph and boots up a codebase-aware chat.

Click to expand ecosystem diagram

---

CLI Launch Interface

╭──────────────────────────────────────────────╮
│  >_ Local-AI Agent                           │
│                                              │
│  model:     Qwen3.6-35B-A3B.gguf             │
│  directory: ...-ai/projects/session-test     │
│  skill:     init codef                       │
│  database:  active (3 facts, 109 turns)      │
╰──────────────────────────────────────────────╯
[sys] Startup context: 210 tokens | Ctrl+C to exit.

Agent: Workspace loaded. Awaiting instructions.
❯

---

Temporal Personality Memory (TPM)

Evolving with your workspace, learning your habits, and standardizing your identity.

• Weaviate Engram's active reconciliation concepts with Noema's local Markdown file system.

---

Codebase Graph Mapper & Relational Index

Building flat shorthand maps and queryable call graphs.

• Graphify's codebase mapping with codebase-memory-mcp's relationship queries.

---

System Administration & Diagnostics

Inspecting package updates, monitoring system health, and optimizing performance.

• log-checker and system-health live diagnostics with aur-audit, security-audit, update-inspector zero-trust auditing, system-optimizer resource adjustments, ai-status routing, and ai-commit hooks.

---

Core Capabilities

Core	Capability	Description
Performance	Zero-Daemon	0% idle CPU/RAM. Ultra-light execution.
Intelligence	Scalability	Optimized from Qwen3.5-2B up to frontier models.
Resiliency	Fallbacks	Gemini → OpenAI → Claude → xAI → OpenRouter → GGUF.
Safety	Zero-Trust Guardrails	Intercepts out-of-bounds commands and edits for manual approval.
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 500 lines of modular, standard-library Python.

---

TUI Carousel & Input 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 / Right Arrow / Ctrl+C: Cancel/Skip the active menu, memory-recall, or tool authorization prompt cleanly.

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

---

Model Select TUI

Manage your active cloud endpoints, inspect live API rankings, and toggle keys.

• Run model select directly from your terminal to launch the interactive Cloud Connection TUI.

---

Command Reference

1. Global Shell Commands

Executed directly from your terminal prompt.

Command	Description
ai	Launch an interactive, multi-turn chat session.
ai <query>	Get an instant, one-shot answer, straight back to your shell prompt.
ai init <path>	Launch (or create) a codebase-aware workspace agent.
hs / hist	Interactively search or view active workspace history.md.

2. Active Session Commands

Typed directly inside an active chat session.

Command	Description
/skill <query> (or /s)	Search and load dynamic specialist skills.
view file <path> (or read)	Dynamically read local files directly into your model context.
-save <tag> / -load	Save active states or rollback/clone snapshots (with Global Handoff).
/f / /t / /b / /a	Trigger prompt-generating subroutines: Follow-up, Thinking, Brainstorm, or All.

3. Modular Toggle & Diagnostic Switches

Typed inside an active chat session to adjust settings.

Command	Description
/clear / /reset	Reset Session context, local chat history, and the SQLite TPM table.
/d / /e	Disable / Enable the context-aware grammar & spellchecker.
/g	Toggle workspace confirmation gates ON/OFF (autonomous editing mode).
/m	Toggle long-term memory and TPM reconciliation ON/OFF.
/r / /r <tokens>	Toggle reasoning ON/OFF. Supports custom limits (default: 500).
/stats / /tok	Diagnostics: Toggle real-time speed metrics or view live token usage.

---

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 terminal rendering utilities
# (mdcat enables beautiful terminal markdown formatting)
yay -S mdcat

# 2. Install the required requests dependency
# Arch: sudo pacman -S python-requests
# Debian/Ubuntu: sudo apt install python3-requests
# macOS / Other: pip install requests
sudo pacman -S python-requests

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

# 4. Add the environment hook into Bash & reload your profile
echo '[ -f "$HOME/.config/local-ai/ai-hook.sh" ] && source "$HOME/.config/local-ai/ai-hook.sh"' >> ~/.bashrc
source ~/.bashrc

# 5. Create your private configuration file (No global exports needed!)
# Fill in only what you use; the rest defaults safely.
# The agent reads this dynamically on every run with zero terminal restarts.
nano ~/.config/local-ai/.env

Configuration Example (.env):

# ~/.config/local-ai/.env
# use "ai status" and "model select"

# Claude API
CLAUDE_API_KEY="your-claude-api-key-here"
CLAUDE_MODEL="claude-fable-5"

# OpenAI API
OPENAI_API_KEY="your-openai-api-key-here"
OPENAI_MODEL="gpt-5.6"

# x.AI Grok API
XAI_API_KEY="xai-your-grok-api-key-here"
XAI_MODEL="grok-4.5"

# Google Gemini API
GEMINI_API_KEY="AIzaSyYourFullGeminiApiKeyHere"
GEMINI_MODEL="gemini-3.1-flash-lite"

# OpenRouter API
OPENROUTER_API_KEY="sk-or-v1-YourFullOpenRouterKeyHere"
OPENROUTER_MODEL="openrouter/free"

# Context Limits
AI_MAX_TOKENS=8192

---

Roadmap to v1.0.0

The final performance and security passes before the official stable release.

• Dynamic Stress-Testing: Conduct continuous context-window pressure tests across standard (GGUF) and deep reasoning backends.
• Optimization Audits: Run latency profiling and memory alignment passes on connection pooling and stream processing modules.
• Security Validation: Implement automated file boundary testing to verify directory containment and authorization overrides.
• Final Code Optimizations: Use strongest frontier coding model with exclusive finishing coding-skill.md to run a final pass and optimize final production ready product.
• Clean and Condense: Only keep what is needed and useful.
• Finalize Logo: Decide on final logo from concept art.
• Stable Tag Deployment: Publish official v1.0.0 production-stable release!

---

Credits & License

• License: Licensed under the permissive MIT License.
• Contributions: Special thanks to suyadnya for the .env configuration architecture, macOS compatibility investigations, and high-velocity alias designs. Contributions are always welcome.