Local-AI Agent

gpt claude grok gemini openrouter hf gguf

Overview & Execution Modes

Lightweight Python orchestration (rich + requests + sqlite-vec + uvloop) controlling a C++ backend llama-server. Built for extreme efficiency on quantized local engines (LFM2.5-8B-A1B, Qwen-3.5-2B, Qwen3.6-35B-A3B, Qwen3.8-27B) and cloud providers.

🟢 Active: Dedicated Huggingface endpoints: (Qwen/Qwen3.8-27B, DeepSeek-V4-Flash).

Direct Shell Jaccard (<shortcut>): Sub-millisecond keyword routing to local shell scripts via ai-context.md.
Single-Turn Query (ai <query>): Instant response piped straight back to your active shell prompt.
Multi-Turn Chat (ai): Persistent interactive terminal session with memory context.
Workspace Agent (ai init <path>): Full codebase graph indexing, path-healing file editing, and sub-agent concurrency.

Key Systems & Integrations

Feature System	Foundation & Architectural Roots	Interface Command / Link
Temporal Personality Memory (TPM)	Reconciles personal identity & workspace habits using Weaviate Engram concepts + Noema Markdown files.	`.agent/tpm.md`
Codebase Graph & Relational Index	Structural codebase maps (Graphify) + relational queries (codebase-memory-mcp) + sqlite-vec vector RAG with class inheritance graph mapping.	`index-map <dir>`
Ralph Autonomous Task Loop	Self-directed iteration loop (Ralph Wiggum) executing tasks against project specs (`TASK.md`) until verified complete.	`/task [goal]`
NOOA IPython Kernel Harness	NVIDIA Object-Oriented Agent (NOOA + Prime Agent) stateful Python kernel with pass-by-reference bounded previews (`preview()`), model-callable `memory`/`graph` APIs, and in-kernel `delegate()` sub-agents.	`/py`
DeepSeek Session Audit & IPC	Structured JSONL session event logs + JSON-RPC 2.0 socket IPC + YAML skill frontmatter overlays inspired by DeepSeek Harness.	`.agent/session.jsonl`
Reasonix Cognitive Engine	Real-time reasoning trace step extraction (Reasonix) + cognitive phase formatting inside thinking stream.	`/t [N\|show\|hide]`
System Admin & Diagnostics	Live health monitoring, AUR/security audits, system optimization, status routing, and git commit hooks.	`tools/agentic/system/`
Model Select TUI	Real-time Cloud Connection TUI, key toggles, and endpoint selector.	`model select`
Interactive Textual TUI	Full-screen Textual TUI workspace with JSON-RPC 2.0 sub-agent socket IPC powered by a C-speed `uvloop` event loop.	`/tui`

Core Capabilities

Core Module	Capability	Description
Engine	Zero-Daemon	0% idle CPU/RAM usage. Native Python standard-library execution.
Providers	Active Provider	Direct `.env` configuration: Custom Endpoints / HF, Gemini, OpenRouter, OpenAI, Claude, Grok, or Local GGUF.
Multi-Agent	Subagents	Vercel Eve-style sub-agents with herdr multiplexing (`-save`/`-load`) + in-kernel `delegate("goal")` sub-loops.
Safety	Zero-Trust Gates	Mandatory approval prompts for commands and out-of-bounds file access.
Validation	Type-Safe & AST Guard	Pydantic AI schemas + OpenAI Agents-style self-correcting `.py`/`.json` writes.
Optimization	Token-Slasher	Custom `tools/` and `skills/` integration built for minimal token consumption.
Voice-to-Text	Tablet/Phone Bridge	Zero-latency HTTPS voice bridge with Gemini cloud audio transcription (`/v [auto]`).
Text-to-Speech	Neural Kokoro TTS	Local PipeWire audio reader (`/tts`) using `koko` with automatic code/thinking filtering.

CLI Launch Interface

Customize box themes with /box [1-5]. For detailed multi-agent workflows, read the Workspace Manual.

1. Interactive Multi-Turn Chat (`ai`)

~ ❯ ai
╭─  >_ Local-AI Agent  ─────────────╮
│     model:  Qwen3.6-35B-A3B.gguf  │
│ directory:  ~                     │
│     skill:  chat                  │
│  database:  stateless             │
╰────────────────── Ctrl+C to exit ─╯
 Startup context: 103 tokens
❯

2. Workspace & Sub-Agent (`ai init <path>`)

~ ❯ sess
[01/03] ❯ [session test] ai init ~/session-test --init
:: ↵ run  Esc: 
✔ Mapping complete! [session-test index-map & SQLite graph database updated]
╭────────────────────────────────────────────────────────╮
│   >_ Local-AI Agent [sub-agent #1]                     │
│                                                        │
│     model:  Qwen3.6-35B-A3B.gguf                       │
│ directory:  ~/.config/local-ai/projects/session-test   │
│     skill:  hermes/pro                                 │
│  database:  active (0 facts, 2 turns)                  │
╰─────────────────────────────────────── Ctrl+C to exit ─╯
 Startup context: 195 tokens

Agent: Workspace loaded. Awaiting instructions.
❯

Interactive Textual TUI

Setup & Installation

# 1. Install system dependencies
sudo pacman -S python-rich python-requests

# 2. (Optional Extensions) Ultra-fast /tui and vector search
yay -S python-sqlite-vec && sudo pacman -S python-textual python-uvloop

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

# 4. Register shell environment hook
echo '[ -f "$HOME/.config/local-ai/ai-hook.sh" ] && \
source "$HOME/.config/local-ai/ai-hook.sh"' >> ~/.bashrc
source ~/.bashrc

# 5. Create your configuration file
nano ~/.config/local-ai/.env

Configuration Example (`~/.config/local-ai/.env`):

# Configure manually or run: model select # Top-Down (First Active Key is Used) GEMINI_API_KEY="AIzaSyYourGeminiKey" GEMINI_MODEL="gemini-3.5-flash-lite" OPENROUTER_API_KEY="sk-or-v1-YourOpenRouterKey" OPENROUTER_MODEL="openrouter/free" OPENAI_API_KEY="your-openai-key" OPENAI_MODEL="gpt-5.6" CLAUDE_API_KEY="your-claude-key" CLAUDE_MODEL="claude-opus-5" XAI_API_KEY="xai-your-grok-key" XAI_MODEL="grok-4.6" AI_MAX_TOKENS="8192"

Roadmap to v1.0.0

Core Engine Optimization: Production pass on streaming, token counting, and sub-agent concurrency.
Thinking UI Controls: Real-time thinking TPS metrics and /t show|hide panel toggles.
Modular Agent Personas & Tool Loop: Interactive profile selector on ai init (pi, claude, hermes) with automated path-healing file editing & YOLO execution loops.
Textual Async TUI: Sub-millisecond uvloop event loop integration, Unix socket sub-agent hub, and live workspace watchers.
Reasonix Cognitive Step: Real-time reasoning cognitive transition extraction, real-time thinking step formatting, and stream interception.
Ralph Autonomous Task Loop: On-demand while loop engine (/task, TASK.md) with automated completion verification.
Voice to Text: Low-latency HTTPS tablet or phone voice bridge, Gemini cloud transcription, and non-blocking stdin injection loop (/v [auto]).
Kokoro Neural Text-to-Speech: Real-time local neural voice reader (/tts), PipeWire audio integration, and automatic thinking/code block filtering.
NOOA IPython Kernel Harness: Single-tool Python kernel execution engine (/py) with NVIDIA NOOA bounded previews (preview()), model-callable memory/graph APIs, in-kernel delegate() sub-agents, AST safety gates, and stateful context token conservation.
DeepSeek Session Audit & IPC: Real-time JSONL event logging (.agent/session.jsonl), JSON-RPC 2.0 sub-agent socket IPC, and YAML skill profile frontmatter headers.
React Agent WebApp (T3 Fork): Local-first React control surface & desktop WebApp powered by a lightweight WebSocket-to-IPC socket bridge—featuring interactive Monaco side-by-side git diffs, Reasonix collapsible thinking accordions, and visual sub-agent task trees.
Context Stress Testing: Continuous context-window pressure tests across quantized local engines.
Automated File Containment Validation: Zero-trust security verification on traversal boundaries.
v1.0.0 Production Release Tag!

Credits

License: Licensed under the permissive MODIFIED MIT LICENSE.
Community: Contributions are always welcome!