**New in v0.9.9.19:** Integrated **Hugging Face `smolagents`** code-first execution into the persistent kernel (`/py`). Models can now batch multi-step tasks across files using native Python loops, cleanly signal completion with `final_answer()`, and execute safely under a 30-second `SIGALRM` runaway loop breaker.
gguf llama-server gemini huggingface openrouter
Lightweight Python orchestration (rich + requests + sqlite-vec + uvloop) controlling a C++ backend llama-server. Optimized for fine-tuned quantized local models (Qwen3.5-2B+ / LFM2.5-8B+ for chat & fast single-task tool execution, Qwen3.6-35B / Qwen3.8-27B for full autonomous agents) and cloud providers—supporting native JSON tool calling, and IPython kernel (/py).
🟢 Active: Official Hugging Face Router endpoints (Qwen/Qwen3.8-27B, moonshotai/Kimi-K3, zai-org/GLM-5.3-Flash, DeepSeek-V4-Flash-0731, Qwen/Qwen3.8-2.4T-A95B).
💡 Use
model selectto auto-configure free community HF Spaces.
- Direct Shell (
<plugins>): Sub-millisecond intent routing for shortcuts and diagnostic tools inai-context.md. - Single-Turn Query (
ai <query>): Instant response piped directly back to the active shell prompt. - Multi-Turn Chat (
ai): Interactive terminal session with persistent memory context. - Workspace Agent (
ai init <path>): Full codebase graph indexing, surgical AST file editing, and sub-agent concurrency. - llama.cpp WebAgent (
/webui): Autonomous tool-enabled web gateway on officialllama-serverUI (:3000) with Gemini search grounding and vision image-processing for text-only local models.
| Feature System | Foundation & Architectural Roots | Interface Command / Link |
|---|---|---|
| Memory (TPM) | Reconciles personal identity & workspace habits using Weaviate Engram concepts + Noema Markdown files. | .agent/tpm.md |
| Codebase Graph & Index-Map | Structural codebase maps (Graphify) + relational queries (codebase-memory-mcp) + sqlite-vec vector RAG. | index-map <dir> |
| Autonomous Task Loop | Self-directed iteration loop (Ralph Wiggum) executing tasks against project specs (TASK.md) with failure decomposition. |
/task [goal] |
| NOOA IPython Kernel Harness | NVIDIA Object-Oriented Agent (NOOA + Prime Agent) stateful Python kernel with bounded previews (preview()), model-callable memory/graph APIs, and in-kernel delegate() sub-agents. |
/py |
| Surgical Edits | Whitespace-tolerant replacements (edit_file) + AST skeleton guards (>250 lines) + overwrite protection (write_file) inspired by SmallCoder. |
edit_file <path> |
| 3-Zone Context Compactor | Token preservation compactor inspired by Pi Coding Agent—condenses older tool outputs while preserving completed task progress anchors. | /compact (or /com) |
| 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 | 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 PyTUI | Full-screen Textual TUI workspace with JSON-RPC 2.0 socket IPC powered by a C-speed uvloop event loop. |
/tui |
| PyCode Desktop IDE | Customized T3 Code fork connected via Agent Client Protocol (ACP) over stdio JSON-RPC 2.0 with live token & thought streaming. | /pyc (or /pyc web) |
| llama.cpp WebAgent Gateway | Full autonomous agent tool execution (list_dir, write_file, AST graph) + Gemini multimodal vision for text-only local models. |
/webui |
| Adapters | Sub-27B Healer | Self-healing tool format adapters (agent_adapters.py) resolving Hermes XML, DSML, Mistral, and raw planning JSON out-of-band for 2B–8B models. |
| 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") sandboxes. |
| Safety | Zero-Trust Fallback | Mandatory non-bypassable [Y/n] confirmation for out-of-bounds workspace paths, mutating system actions (systemctl start/stop), and package managers (sudo, pacman -S, pip) across both CLI tools and in-kernel Python execution. |
| Integrity | Type-Safe & AST Guard | Pydantic AI schemas + AST-validated Python file writes with live diff previews. |
| Resilience | Self-Healing Tools | Unsloth-inspired JSON argument healer re-serializing valid schemas to prevent server HTTP 500 errors. |
| Optimization | Token-Slasher | Custom tools/ and skills/ integration built for minimal token consumption. |
| Grounding | Web Search Engine | Real-time factual search retrieval (/gnd) with Gemini Grounding and DuckDuckGo safety fallback in CLI, TUI & WEB/PYC. |
| Voice-to-Text | Tablet/Phone Bridge | Zero-latency HTTPS voice bridge with Gemini cloud transcription and native Wayland virtual typing (wtype) directly into PyCode IDE and CLI (/v [auto]). |
| Text-to-Speech | Neural Kokoro TTS | Local PipeWire audio reader (/tts) using koko with silent code/thinking filtering and concise status announcements. |
Customize box themes with
/box [1-8]. For detailed multi-agent workflows, read the Workspace Manual.
~ ❯ ai
╭─ ∿ Py Agent ────────────────────╮
│ model: Qwen3.6-35B-A3B.gguf │
│ directory: ~ │
│ skill: chat │
│ database: stateless │
╰────────────────── Ctrl+C to exit ─╯
Startup context: 103 tokens
❯ Py-Agent is surface-agnostic. Switch seamlessly between the terminal, web gateway, and desktop IDE:
/pyc · /pyc web
Local-first React IDE with ACP stdio JSON-RPC 2.0, live thought streaming & ambient aurora glow. |
/tui
Full-screen terminal interface with uvloop async event loop, socket IPC & live reasoning steps.
|
/webui · /web
Autonomous tool reverse proxy for official llama-server (:3000) with Gemini Flash vision.
|
/v Voice-to-Text (:9999) •
/tts Neural Kokoro Audio •
/pybot Web Assistant (Roadmap)
# 1. Install system dependencies & clone
sudo pacman -S python-rich python-requests
git clone https://github.com/j5onrf/py-agent.git ~/.config/py-agent
# 2. Register shell hook (bash / zsh)
echo '[ -f "$HOME/.config/py-agent/ai-hook.sh" ] && \
source "$HOME/.config/py-agent/ai-hook.sh"' >> ~/.bashrc
source ~/.bashrc# Option A: Interactive TUI Selector
model select
# Option B: Manual Configuration
cp ~/.config/py-agent/.env.example ~/.config/py-agent/.env
nano ~/.config/py-agent/.env📋 View Example ~/.config/py-agent/.env (Click to Expand)
# ==============================================================================
# Py-Agent Environment Configuration Template
# Top-Down Priority: The first active (uncommented) provider key is used.
# ==============================================================================
# ── 1. Custom Endpoints / Hugging Face Router ─────────────────────────────────
# CUSTOM_API_KEY="not-needed"
CUSTOM_URL="https://router.huggingface.co/v1/chat/completions"
CUSTOM_MODEL="Qwen/Qwen3.8-27B"
# ── 2. Google Gemini (Free daily tier via Google AI Studio) ───────────────────
# GEMINI_API_KEY="AIzaSyYourGeminiApiKeyHere"
GEMINI_MODEL="gemini-3.8-flash"
# ── 3. OpenRouter (Free community models & Universal paid gateway) ────────────
# OPENROUTER_API_KEY="sk-or-v1-YourOpenRouterKeyHere"
OPENROUTER_MODEL="openrouter/free"
# ── Google Search Grounding (/gnd) (Optional) ────────────────────────────────
# GND_KEY="AIzaSyYourGeminiApiKeyHere"
# GND_MODEL="gemini-2.0-flash"
# ── Voice Bridge Transcription (Optional) ────────────────────────────────────
# GEM_VOICE="AIzaSyYourGeminiApiKeyHere"
# GEM_MODEL="gemini-3.5-flash-lite"
# ── Multimodal for text only models (Optional) ───────────────────────────────
# IMG_VOICE="AIzaSyYourGeminiApiKeyHere"
# IMG_MODEL="gemini-3.5-flash-lite"
# ── Context Window Budget ────────────────────────────────────────────────────
AI_MAX_TOKENS="8192"| Surface | Setup / Command | Requirements |
|---|---|---|
| Desktop IDE (PyCode) | install-pycode(or ~/.config/py-agent/plugins/pycode/setup.sh) |
Node.js 20+, pnpm |
| Textual PyTUI | sudo pacman -S python-textual python-uvloop && yay -S python-sqlite-vec |
uvloop & sqlite-vec |
| Voice-to-Text Bridge | /v (or /v auto on :9999) |
sudo pacman -S wtype openssl & GEM_VOICE in .env |
| Neural Kokoro TTS | /tts(or Audio Plugin) |
yay -S koko-bin pw-play wl-clipboard |
- Core Engine Optimization: Production pass on streaming, token counting, and sub-agent concurrency.
- Thinking UI Controls: Real-time thinking TPS metrics and
/t show|hidepanel 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 PyTUI: Sub-millisecond
uvloopevent loop integration, Unix socket sub-agent hub, and live workspace watchers. - Reasonix Cognitive Step: Real-time reasoning cognitive transition extraction and streaming step formatting.
- Ralph Autonomous Task Loop: Self-directed iteration engine (
/task,TASK.md) with failure-state decomposition. - Voice to Text: Low-latency HTTPS voice bridge, Gemini 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 & Smolagents IPython Kernel Harness: Single-tool Python kernel execution engine (
/py) combining NVIDIA NOOA bounded previews (preview()) with Hugging Facesmolagentscode-first batching (final_answer(),search_code()), 30sSIGALRMloop breakers, model-callablememory/graphAPIs, and in-kerneldelegate()sub-agents. - DeepSeek Session Audit & IPC: Real-time JSONL event logging (
.agent/session.jsonl), JSON-RPC 2.0 socket IPC, and YAML skill profile frontmatter headers. - Modular Sub-27B Adapters & Self-Healing Parser: Dedicated
agent_adapters.pyhandling Hermes XML, DSML, Mistral, and raw function call extraction for small quantized models. - SmallCoder Surgical Edits & AST Skeleton: Whitespace/indentation tolerance in
edit_file, overwrite protection onwrite_file, and AST outline reading for large files (>250 lines). - 3-Zone Context Compactor with Progress Anchor: Pi-inspired context compaction (
/com) preserving completed milestone summaries across context purges. - PyCode Cross-Platform GUI (T3 Fork): Local-first React desktop and WebUI workspace connected via ACP stdio JSON-RPC bridge (
/pyc,/pyc web). - llama.cpp WebAgent Gateway: Real-time tool execution, Gemini vision pre-processing, and streaming proxy for the official
llama.cppWebUI (/webui). - Google Search Grounding (/gnd): Live web grounding via Gemini Search tool with automatic DuckDuckGo keyless fallback across CLI, TUI, WebUI, and PyCode.
- Zero-Trust Hardened Containment: Non-bypassable interactive
[Y/n]fallback gate for out-of-bounds access and package management tools (pip,pacman,sudo). - PyBot Integration (OpenBot Plugin): Embedded web assistant & customizable agent widget plugin.
- v1.0.0 Production Release Tag!
- License: Licensed under the permissive MODIFIED MIT LICENSE.
- Community: Contributions are always welcome!