Context Limit
August 21, 2026 · View on GitHub
Py 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 models (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 (
<plugins>): Sub-millisecond fuzzy intent routing for shell shortcuts, diagnostic tools, and custom plugins mapped inai-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. - Native GUI IDE (
/pyc): Fast Electron and browser IDE surface powered by PyCode.
Key Systems & Integrations
| Feature System | Foundation & Architectural Roots | Interface Command / Link |
|---|---|---|
| PyCode Native Desktop GUI | Customized T3 Code fork connected via native Agent Client Protocol (ACP) over stdio JSON-RPC 2.0 with live token & thought streaming. | /pyc (or /pyc web) |
| 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. |
| Integrity | Type-Safe & AST Guard | Pydantic AI schemas + OpenAI Agents-style self-correcting .py/.json file writes. |
| Resilience | Self-Healing Tool Calls | Unsloth-inspired heuristic parser fixing malformed JSON/XML arguments on the fly before tool execution. |
| 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
╭─ ∿ Py Agent ────────────────────╮
│ model: Qwen3.6-35B-A3B.gguf │
│ directory: ~ │
│ skill: chat │
│ database: stateless │
╰────────────────── Ctrl+C to exit ─╯
Startup context: 103 tokens
❯
Plugin Extensions
Setup & Installation
1. Install py-agent
# 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
2. Configure Providers (.env)
Configure providers automatically via the interactive selector or copy the template:
# 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)
# Top-Down Priority (First Active Key is Used)
# Cloud Providers
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"
# Context Limit
AI_MAX_TOKENS="8192"
3. Optional Client Surfaces
| Surface | Installation Command | Requirement |
|---|---|---|
| Desktop GUI (PyCode) | install-pycode(or ~/.config/py-agent/plugins/pycode/setup.sh) | Node.js 20+, pnpm |
| Textual TUI Speedups | sudo pacman -S python-textual python-uvloop && yay -S python-sqlite-vec | uvloop & sqlite-vec |
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|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 TUI: Sub-millisecond
uvloopevent 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
whileloop 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-callablememory/graphAPIs, in-kerneldelegate()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. - Self-Healing Tool Parser: Unsloth-inspired resilient JSON argument healer auto-balancing brackets, stripping leaked XML tokens, and repairing unescaped newlines for small local models.
- PyCode Native Desktop GUI (T3 Fork): Local-first Electron IDE and WebUI connected via ACP (Agent Client Protocol) stdio JSON-RPC bridge (
/pyc,/pyc web)—featuring real-time token/thought streaming, custom vector branding, and automatic workspace AST indexing. - PyBot Integration (OpenBot Plugin): Embedded web assistant & customizable agent widget plugin to bring
py-agentintelligence to browser overlays and multi-surface chat bots. - 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!
License
- License: Licensed under the permissive MODIFIED MIT LICENSE.
- Community: Contributions are always welcome!