agentkthx

⚛️ AgentKthx R07.34

Status: Alpha

A minimal, modular, python stdlib, agentic framework for tool calling AI agents. Runs locally with BitNet, Ollama, TurboQuant, and stable-diffusion.cpp (image generation), in the cloud with Cloudflare, Google, HuggingFace, Mistral, NVIDIA, OpenAI, OpenRouter, OrcaRouter, Pollinations, SiliconFlow, TokenHarbor and ZAI. Extensible via a manifest-based plugin system for additional backends and features.

Inspired by the architecture of OpenClaw, rebuilt from scratch for local-first operation.

Written by VTSTech · GitHub Discord

Installation

# Latest Development Release
pip install git+https://github.com/VTSTech/AgentKthx.git --force-reinstall

# Last Stable (as stable as Alpha can be) Release
pip install agentkthx

📚 Documentation

Features

• Zero dependencies — Uses Python stdlib only (urllib for HTTP)
• Plugin system — Manifest-based plugin discovery, lazy loading, dependency resolution (R05.0), plugin spec v0.2 lifecycle hooks (on_init/on_run_start/on_run_end/on_error/on_shutdown), plugin-provided tools, external plugin roots (~/.agentkthx/plugins/, $AGENTKTHX_PLUGIN_PATH), optional sha256 content pinning (R07.05 SEC-06), plugins --load/--unload/--reload/--json/--verbose management
• Native + plugin backends — Ollama + TurboQuant built-in; Cloudflare, NVIDIA, OpenRouter, BitNet, ZAI, ACP, Gemini, OrcaRouter, Mistral, HuggingFace, OpenAI, Pollinations, SiliconFlow, and Stable Diffusion (image generation) as plugins. (The TurboQuant backend uses llama.cpp's llama-server binary under the hood — --backend turboquant is the primary name; --backend llama-server remains as a backward-compat alias. Stable Diffusion follows the same pattern: --backend stable-diffusion is the primary name, --backend sd the alias.)
• Image generation (R07.31) — --backend sd turns each chat turn into ONE image via an external stable-diffusion.cpp server (sd-server -m <model> --listen-port 1234 — Ollama pattern: AgentKthx never manages the process). The flattened conversation becomes the prompt (harness system prompt suppressed, DDG-style), and the returned PNG is written to the artifacts dir (AGENTKTHX_ARTIFACTS_DIR, default ./generated/) — the reply carries [image saved: <path>]. R07.32: --max-steps N --backend sd remaps to diffusion sample steps (validated 1–100, applied per request via the server's sd_cpp_extra_args — no restart) and the session header shows Sample Steps instead of Max Steps.
• Backend support tiers (R07.25) — ZAI, OpenRouter, HuggingFace, Gemini, Mistral, NVIDIA NIM, Cloudflare Workers AI, and the R07.31 TokenHarbor scaffold are Fully Supported (maintainer-tested before every release — Cloudflare promoted R07.27 and TokenHarbor promoted R07.34, each after a 5/5 end-to-end smoke test; TokenHarbor runs $0 on its :free tier); Pollinations, OrcaRouter, OpenAI, and the R07.29 SiliconFlow scaffold are Limited Support (code-quality identical, but the maintainer's API key access has been unavailable for an extended period — SiliconFlow passed its live catalog probe (79 models, R07.29) and its 2026-10-09 smoke attempt verified auth, the catalog, and one --think generation before the account balance drained; both tool-call steps returned 402 insufficient-balance, so it awaits a topped-up 5/5 run). See docs/SUPPORT.md for the full policy + what "Limited Support" means in practice. Local backends (TurboQuant, Ollama, BitNet, Stable Diffusion) are always Fully Supported (no external API key needed).
• Multi-cloud support — Access to 500+ models from OpenRouter, OpenAI, Anthropic, Google (Gemini + Gemma), Cohere, plus 80+ models from NVIDIA NIM, 20+ open models (Llama, Mistral, Qwen, DeepSeek, Phi, Gemma, GPT-OSS) from Cloudflare Workers AI, 80+ live models (DeepSeek, Qwen, GLM, Kimi, MiniMax, Hunyuan, Gemma, gpt-oss) from SiliconFlow, and 11 upstream providers via OrcaRouter's zero-markup gateway
• Dual API support — OpenResponses (--api openre) and OpenAI Chat-Completions (--api openai)
• JEV decision mode — System-One decisions via any free LLM (--api jev) — Jev-compatible shape, no TypeSafe API key required
• Thinking controls — --thinking off|auto|low|medium|high to control model reasoning effort, --think flag to display reasoning_content (chain-of-thought) in CLI output. R07.26: streaming spinner starts even during streaming and stops on first chunk (thinking models that take 60-90+ seconds before the first token no longer look hung)
• Tool support — Native or ReAct, auto-detected from the server's own capabilities (a would-be none falls back to ReAct — no models classified none) plus a think column for thinking/reasoning support
• Small model optimized — Fuzzy matching, argument normalization, string-literal-aware Python-literal substitution (R07.07 MAINT-14 — True/False/None inside string values no longer mangled)
• Built-in security — Path validation, command blocklist (incl. shells + heredocs since R07.05), SSRF protection (DNS-resolving since R07.05), plugin sha256 pinning (R07.05), tool-output sanitization (R07.05), persistent-memory perms 0o700/0o600 (R07.05). Toggleable via --security max|off.
• Multi-agent orchestration — Router, pipeline, and parallel modes
• Soul Spec v0.5 — Persona packages with progressive disclosure
• AgentSkills spec — Skill loading with SPDX license validation
• Thinking models support — Automatic handling of qwen3, deepseek-r1 thinking mode
• Ctrl+C cancellation — Graceful interrupt at backend, tool, and agent loop levels (R05.0; R07.06 ROB-01: half-cancelled run bug fixed)
• Persistent memory — SQLite-backed conversation persistence with session management (--session); writes are thread-safe (R07.05 ROB-03)
• /model switch re-derives per-model state (R07.06 ROB-14) — num_ctx, num_predict, model_config, model_family all follow the new model; values pinned via --num-ctx/--num-predict//param survive the switch
• 7 built-in tools — Calculator, shell, HTTP, web search, JSON parse, Python REPL, todo list. File operations (read/write/edit/list) come from the MCP filesystem server (--mcp filesystem); date/time comes from the MCP time server (@infoinlet/mcp-time, pre-configured by agentkthx mcp init). Load mid-session via /tool calculator,shell
• MCP client support (R07.22) — Connect to external Model Context Protocol servers via stdio JSON-RPC; their tools are bridged into the agent's registry with <server>__<tool> namespacing. The filesystem server covers read/write/edit/list operations. See docs/USAGE.md#mcp-model-context-protocol for the full guide (mcp init / mcp probe / mcp search / mcp install / chat --mcp [server...]).
• Dangerous tool confirmation — --confirm flag for interactive approval of destructive operations (shell)
• Audit logging — Automatic JSON-lines logging of shell operations
• Argument normalization — ~100+ tool argument aliases for small model compatibility
• JSON structured output — --response-format json for structured JSON responses
• Self-update — agentkthx update to update to latest version from GitHub
• Update check — Startup + post-run notice for both release tracks: stable (new package on PyPI) and development (new commits on GitHub main); agentkthx version shows both too; always live (no cache — every run queries PyPI + GitHub main directly), fails silently offline, opt out with AGENTKTHX_NO_UPDATE_CHECK=1
• Persistent status footer — 2-line terminal footer with live model/backend/token info (R05.4, scroll-region based)
• Tool-call visibility — Tool calls and results displayed in chat mode (R05.4); per-response stats (⏱️ N steps, M tool calls, Xms + tools used) in both chat and agent modes (R07.15)
• Audit-tracked development — every release since R07.04 documents findings in audit/audit.md with stable IDs (SEC / ROB / MAINT / PERF / FEAT / ARCH / TEST / MCP) and closure deltas. 101 CLOSED + 10 WONTFIX of 125 findings archived (~89%). See the audit dashboard for the live register.

Usage

All usage instructions have moved to docs/USAGE.md — CLI commands, backend configurations, Python API, persistent memory, dangerous-tool confirmation, JSON structured output, TurboQuant server management, tool support, model families, security modes, environment variables, MCP client setup, and the full CLI options table.

Quick reference:

# Single prompt
agentkthx run "What is 2+2?"

# Interactive chat
agentkthx chat

# Autonomous agent mode
agentkthx agent "Research the latest AgentKthx release"

# Image generation (requires a local sd-server: sd-server -m <model> --listen-port 1234)
agentkthx run "a lovely cat" --backend sd

# Set API keys (interactive picker, persists to ~/.agentkthx/.env)
agentkthx auth

# MCP (Model Context Protocol) — see docs/USAGE.md#mcp-model-context-protocol
agentkthx mcp init
agentkthx chat --mcp filesystem

For backend configs, security modes, environment variables, MCP setup, and the complete CLI options table, see docs/USAGE.md.

Tests & Examples

AgentKthx ships a comprehensive suite of regression tests + 12 example scripts covering reasoning, knowledge, and tool usage. See docs/TESTS.md for the example scripts, test categories, and benchmark results.

# Regression test suite (3498 passed / 20 skipped in ~26s)
pytest

# Quick 5-question diagnostic example
python -m agentkthx.examples.01_quick_diagnostic

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run unit tests (3498 passed / 20 skipped in ~26s)
pytest

# Format code (CI gates on ruff + black over agentkthx/ and tests/)
black agentkthx tests
ruff check agentkthx tests

Audit Trail

AgentKthx is developed with an audit-tracked discipline: every release since R07.04 documents findings in audit/audit.md with stable IDs (SEC-XX, ROB-XX, MAINT-XX, PERF-XX, FEAT-XX, ARCH-XX, TEST-XX, MCP-XX) and closure deltas.

• audit/brief.md — condensed intelligence brief for the current codebase (≤16K tokens; load this first when contributing)
• audit/audit.md — detailed findings report with severity, recommendations, and closure status per release
• audit/deltas.md — CLOSED + WONTFIX archive with closure prose per finding
• The codebase-audit skill ships with the repo at agentkthx/skills/codebase-audit/ — invoke via /skill codebase-audit in chat mode to regenerate the brief against the current codebase.
• The audit dashboard is regenerated by audit/generate_audit_dash.py (run manually before GitHub/CI per owner policy).

Cumulative closure state: 101 CLOSED + 10 WONTFIX of 125 findings (111 archived, ~89%) across R07.00 → R07.26; test suite at 3055 passed / 20 skipped.

License

MIT License - See LICENSE file for details.

Author

VTSTech — https://www.vts-tech.org

Contributing

Contributions welcome!

Changelog

See docs/CHANGELOG.md for detailed version history and release notes.

Why "AgentKthx"?

The name honors the IRC-era slang "kthx" (OK, thanks) — a callback to early internet culture. It's distinctive, memorable, and (most importantly) completely unused by any other AI agent project as of September 2026. The CLI binary agentkthx is short and easy to type.