README.md

⚛️ AgentKthx R07.25

Status: Alpha

A minimal, modular, python stdlib, agentic framework for tool calling AI agents. Runs locally with BitNet, Ollama, TurboQuant, in the cloud with Google Gemini, HuggingFace, Mistral, OpenAI, OpenRouter, OrcaRouter, Pollinations 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

📚 Documentation

Document	Description
ARCH.md	Technical documentation for developers (directory structure, core design, orchestrator modes)
CHANGELOG.md	Version history and release notes (includes LocalClaw history)
CREDITS.md	Acknowledges every project, inspiration, API, model creator, and specification that makes AgentKthx possible
docs/api/	API Technical References — one deep-dive per provider, all in one folder: ZAI, OpenRouter, Gemini, Hugging Face Router, OpenAI, Mistral, Pollinations, OrcaRouter (auth & endpoints, request/response schemas, model catalogs, function calling, streaming, error codes & recovery, rate limits, free-tier behavior, AgentKthx Backend + plugin.json blueprints, troubleshooting matrices)
JEV_API_MODE.md	JEV API mode — System-One decisions via any free LLM (Jev-compatible shape)
mcp/ROADMAP.md	MCP support — Phase 1 (client mode, stdio) status + Phase 2 (kthx-audit MCP server) + Phase 3 (generic mcp serve) plan
PLUGIN_SPEC_v0.2.md	Plugin spec v0.2 — lifecycle hooks, plugin tools API, external plugin roots, dual-form manifests, migration guide from v0.1
SUPPORT.md	Backend support tiers — Fully Supported vs Limited Support per-backend policy (R07.25)
USAGE.md	Usage guide — CLI commands, backend configurations (OpenRouter/Gemini/HuggingFace/ZAI/TurboQuant), Python API, persistent memory, security modes, environment variables, MCP client setup, full CLI options table
TESTS.md	Example scripts, test categories, benchmark results, and per-test deep-dive results

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; OpenRouter, BitNet, ZAI, ACP, Gemini, OrcaRouter, Mistral, HuggingFace, OpenAI, Pollinations 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.)
• Backend support tiers (R07.25) — ZAI, OpenRouter, HuggingFace, Gemini, Mistral are Fully Supported (maintainer-tested before every release); Pollinations, OrcaRouter, OpenAI are Limited Support (code-quality identical, but the maintainer's API key access has been unavailable for an extended period). See docs/SUPPORT.md for the full policy + what "Limited Support" means in practice. Local backends (TurboQuant, Ollama, BitNet) 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 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
• 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
• 17 built-in tools — Calculator, shell, file ops (read/write/edit/list/find), HTTP, web search, JSON parse, Python REPL, todo list, datetime, word/char count. Load mid-session via /tool shell,read_file
• 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. 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
• Audit logging — Automatic JSON-lines logging of shell, write, and edit 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.

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

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"

# 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.

LocalClaw Redirect

The localclaw command is provided for backward compatibility:

# Both work identically
localclaw run "What is 2+2?"
agentkthx run "What is 2+2?"

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 (2966 passed / 20 skipped in ~21s)
pytest

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

Development

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

# Run unit tests (2966 passed / 20 skipped in ~21s)
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.25; test suite at 2966 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.

Migration from AgentNova

R06.0 renamed the project from AgentNova → AgentKthx. The rename was driven by name collisions in the AI agent space (multiple projects, Instagram accounts, etc. were using the AgentNova name).

What changed

Old	New
PyPI package: agentnova	agentkthx
CLI command: agentnova	agentkthx
Python import: import agentnova	import agentkthx
GitHub repo: VTSTech/AgentNova	VTSTech/AgentKthx

What stays the same (backward compat)

• ✅ The agentnova CLI command still works (redirects to agentkthx)
• ✅ import agentnova still works (re-exports from agentkthx, emits DeprecationWarning)
• ✅ All AGENTKTHX_* env vars still work unchanged
• ✅ localclaw CLI command still works (redirects through to agentkthx)
• ✅ All existing skills, souls, plugins, and configs continue to work
• ✅ SQLite persistent memory sessions remain compatible

Migration steps (recommended but not required)

# Uninstall old package (optional — both can coexist)
pip uninstall agentnova

# Install new package
pip install agentkthx

# Update your scripts (optional — old imports still work with a warning)
# Old: from agentnova import Agent
# New: from agentkthx import Agent

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.