# Enternovate: llms-full.txt Concatenated core documentation for LLM ingestion. Page order mirrors the site. # Enternovate (Pty) Ltd AI agents, software, cybersecurity and IT hardware supply for South African business and government. CIPC 2025/911173/07 · 100% black-owned EME Level 1. The open-source ecosystem: Xavani (AI agent gateway), Nyarhi (open knowledge), Gavaza (POPIA compliance), Mhangani (web security audit).

Xavani Agent

Xavani Agent

The open-source AI agent gateway.
Local-first. Private by design. Cross-platform. Zero product telemetry.
Built by Enternovate — Open Source.
Pronounced: shahr-vaa-nee
Photo by Andy McClanahan on Unsplash

Quick Start MIT Stars

--- ## Welcome to Xavani > **Attribution:** Xavani Agent is derived from [Hermes Agent by Nous Research](https://github.com/NousResearch/hermes-agent) ([MIT License](https://github.com/NousResearch/hermes-agent/blob/main/LICENSE)). > All original code, design, and architecture are the work of the Nous Research team and contributors. > Xavani Agent is maintained independently by [Enternovate](https://enternovate.co.za). Xavani is an **open-source AI agent** that runs from your machine and connects the tools and model providers you choose. Connect to any AI model — OpenAI, Anthropic, Google Gemini, DeepSeek, GLM, Qwen, Yi, MiniMax, Kimi, Baichuan, Step, Doubao, or local models via Ollama — all through a single CLI. With a built-in MCP proxy, policy engine, protocol bridge, memory system, observability stack, and a growing skills library. Xavani sends no product telemetry. Local state stays under `~/.xavani`. Requests sent to remote models or integrations follow the provider you configure. Built by [Enternovate](https://enternovate.co.za). --- ## Quick Start ### One-Command Install ```bash # macOS / Linux curl -fsSL https://raw.githubusercontent.com/enternovate/xavani-agent/main/install.sh | bash # Windows (PowerShell) iwr -Uri https://raw.githubusercontent.com/enternovate/xavani-agent/main/install.ps1 | iex ``` ### Via pip ```bash git clone https://github.com/enternovate/xavani-agent.git cd xavani-agent pip install -e . xavani ``` ### Set Your API Key ```bash # Edit ~/.xavani/.env, add your provider key: echo 'OPENAI_API_KEY=***' >> ~/.xavani/.env ``` Then run `xavani` and start typing. ### Prefer a desktop app? Xavani Desktop uses the same agent engine and `~/.xavani` state as the CLI. Download the current macOS Apple Silicon or Windows x64 preview from: https://enternovate.co.za/xavani-desktop --- ## Supported AI Providers Xavani works with virtually every major AI provider — global and Chinese. ### Global Providers | Provider | Env Variable | Models | Sign Up | |----------|-------------|--------|---------| | OpenAI | `OPENAI_API_KEY` | GPT-4o, GPT-4.5, o-series | platform.openai.com | | Anthropic | `ANTHROPIC_API_KEY` | Claude Opus 4.6, Sonnet 4, Haiku | console.anthropic.com | | Google Gemini | `GOOGLE_API_KEY` | Gemini 2.5 Flash, Gemini 2.5 Pro | aistudio.google.com | | OpenRouter | `OPENROUTER_API_KEY` | 200+ models across all providers | openrouter.ai/keys | | xAI Grok | `XAI_API_KEY` | Grok 3, Grok 3 Mini | console.x.ai | | Groq | `GROQ_API_KEY` | Llama 3, Mixtral, Whisper (fast) | console.groq.com | | NVIDIA NIM | `NVIDIA_API_KEY` | Llama 3.1 Nemotron, Mistral, +40 models | build.nvidia.com | | HuggingFace | `HF_TOKEN` | 20+ open-source models | huggingface.co/settings/tokens | | Ollama (local) | None needed | Llama 4, Qwen, Mistral, DeepSeek | ollama.com | | LM Studio (local) | None needed | Any local model | lmstudio.ai | ### Chinese AI Providers | Provider | Env Variable | Models | Sign Up | |----------|-------------|--------|---------| | DeepSeek | `DEEPSEEK_API_KEY` | DeepSeek-V3, DeepSeek-R1 | platform.deepseek.com | | Alibaba Qwen | `QWEN_API_KEY` | Qwen3, QwQ, Qwen2.5 | aliyun.com | | ZhipuAI GLM | `GLM_API_KEY` | GLM-5, GLM-4-Plus | z.ai / open.bigmodel.cn | | Moonshot Kimi | `KIMI_API_KEY` | Kimi K2.5, K2 | platform.kimi.ai | | MiniMax | `MINIMAX_API_KEY` | MiniMax M2.5, T2.5 | minimax.io | | 01.AI Yi | `YI_API_KEY` | Yi-Lightning, Yi-Large | 01.ai | | ByteDance Doubao | `DOUBAO_API_KEY` | Doubao-Pro, Doubao-Lite | volcengine.com | | Baidu ERNIE | `BAIDU_API_KEY` | ERNIE 4.5, ERNIE 3.5 | yiyan.baidu.com | | Baichuan AI | `BAICHUAN_API_KEY` | Baichuan4, Baichuan3 | baichuan-ai.com | | StepFun | `STEP_API_KEY` | Step-2, Step-1 | stepfun.com | | SenseTime | `SENSETIME_API_KEY` | SenseNova 5.5 | sensetime.com | | OpenCode Go | `OPENCODE_GO_API_KEY` | OpenCode Go models | opencode.ai | | OpenCode Zen | `OPENCODE_ZEN_API_KEY` | Curated global models | opencode.ai | | Qwen OAuth | OAuth login | Qwen models | qwen portal | ### Other Providers | Provider | Env Variable | Notes | |----------|-------------|-------| | Arcee AI | `ARCEEAI_API_KEY` | Trinity models — chat.arcee.ai | | NovitaAI | `NOVITA_API_KEY` | 90+ models — novita.ai | | Azure Foundry | `AZURE_API_KEY` | Azure OpenAI — portal.azure.com | | AWS Bedrock | `AWS_ACCESS_KEY_ID` | Bedrock models — aws.amazon.com | | GitHub Models | `GITHUB_TOKEN` | Models via Copilot — github.com | | KiloCode | `KILOCODE_API_KEY` | KiloCode gateway | | Vercel AI Gateway | `AI_GATEWAY_API_KEY` | Vercel AI proxy | To use a provider, set the env variable in `~/.xavani/.env` and either configure in `~/.xavani/config.yaml` or use `/model ` in the CLI: ```bash # In ~/.xavani/.env DEEPSEEK_API_KEY=sk-... GLM_API_KEY=... QWEN_API_KEY=... # In the Xavani CLI /model deepseek/deepseek-r1 /model glm-5 /model qwen/qwen3 ``` --- ## Getting the Most Out of Xavani Xavani is not just a CLI. It's a full-stack AI agent platform with six integrated systems. Use all of them to unlock its full potential. ### Mode 1: Interactive Agent (Daily Driver) ```bash xavani ``` Built-in skills, provider choice, and persistent memory are available across sessions. Enricher analyzes every input to understand intent, load relevant skills, and confirm understanding before executing. **Pro tip:** Xavani learns your style over ~10 sessions — your humor, expertise level, favorite project types, and communication preferences. ### Slash Commands | Command | Description | Example | |---------|-------------|---------| | `/model ` | Switch AI model mid-session | `/model gpt-4o` | | `/reasoning ` | Set reasoning effort (low/medium/high) | `/reasoning high` | | `/fast` | Toggle priority processing | `/fast` | | `/steer ` | Add context without interrupting | `/steer don't touch prod` | | `/goal ` | Set a standing goal across turns | `/goal finish this PR` | | `/subgoal ` | Add criteria to active goal | `/subgoal add tests` | | `/personality ` | Switch personality | `/personality pirate` | | `/install ` | Install an MCP server | `/install postgres` | | `/gateway-up` | Start the MCP proxy | `/gateway-up` | | `/gateway-down` | Stop the gateway | `/gateway-down` | | `/registry-status` | Show installed servers | `/registry-status` | | `/policy-add ` | Add security policy | `/policy-add strict.yaml` | | `/audit [--since N]` | View audit log | `/audit --since 24h` | | `/status` | Show session info | `/status` | | `/help` | Show all commands | `/help` | ### Connect via Telegram Xavani has a built-in Telegram bot gateway. You can control Xavani from your phone — send messages, run commands, receive responses — all through Telegram: ```bash # 1. Get a bot token from @BotFather on Telegram # 2. Set it in ~/.xavani/.env: echo 'TELEGRAM_BOT_TOKEN=***' >> ~/.xavani/.env echo 'TELEGRAM_ALLOWED_USERS=your_telegram_id' >> ~/.xavani/.env # 3. Start the gateway (runs bot + MCP proxy) xavani --gateway ``` Now message your bot on Telegram. Every slash command works — `/model`, `/reasoning`, `/gateway-up`, `/install`, `/audit`, `/help`. Same Xavani, now in your pocket. Also supported: Discord, Slack, WhatsApp, Signal, Matrix, Email, SMS, and 20+ other messaging platforms. Configure them in `~/.xavani/config.yaml`. ### Mode 2: The MCP Gateway ```bash xavani --gateway ``` Starts a secure MCP proxy on `localhost:8080` that sits between any AI client and your tool servers, enforcing policies, rate limits, auth, and audit on every call. **How to set up and use the gateway:** 1. **Start the gateway:** `xavani --gateway` (or `/gateway-up` in CLI) 2. **Connect any MCP client** to `http://localhost:8080/mcp` 3. **Secure it with your API key:** The gateway generates a token on first run 4. **Install tool servers:** `/install postgres`, `/install brave-search` 5. **Add policies:** `/policy-add my-rules.yaml` 6. **View audit trail:** `/audit --since 24h` 7. **Stop the gateway:** `/gateway-down` **What the gateway enforces:** - Rate limits: 30 calls/min per user (configurable) - Policies: allow/deny specific tools and resources - Auth: API key or JWT required for access - Audit: every request logged with full trace to SQLite ### Mode 3: The Protocol Bridge Translate between MCP, A2A, and OpenAPI — so any tool works with any protocol. ```bash # Use an MCP tool from an A2A agent curl -X POST http://localhost:8080/bridge/mcp-to-a2a \ -H "Content-Type: application/json" \ -d '{"mcp_tool": "postgres:query", "params": {"query": "SELECT 1"}}' # Convert any OpenAPI spec to callable MCP tools curl -X POST http://localhost:8080/bridge/openapi/convert \ -H "Content-Type: application/json" \ -d '{"spec_url": "https://api.example.com/openapi.json"}' ``` ### Mode 4: The Memory Layer Two types of persistent memory, all stored locally: | Type | What It Stores | Retention | |------|---------------|-----------| | Episodic | Full conversations, decisions, outcomes | 90 days (auto-archived) | | Procedural | Learned patterns, successful approaches | Indefinite (gets smarter) | Episodic memory is FTS5-indexed for natural language recall: ``` /in the conversation last week about the database migration, what was the final schema we decided on? ``` Cross-agent context sharing: multiple agents share memory with automatic conflict resolution. ### Mode 5: The Observability Stack ```bash open http://localhost:8081 # Live dashboard /audit --since 7d # CLI audit viewer ``` - Live dashboard with real-time metrics, latency charts, token usage - OpenTelemetry-native traces on every tool call, LLM call, and agent step - CLI audit viewer with filtering by user, tool, or errors ### Mode 6: The Agent Runtime Package any agent configuration as a portable `.agent.toml` file: ```bash xavani --runtime create my-reviewer xavani --runtime export my-reviewer ./my-reviewer.agent.toml xavani --runtime run ./my-reviewer.agent.toml ``` ```toml [agent] name = "code-reviewer" version = "1.0.0" description = "Automated code review agent" [model] provider = "anthropic" model = "claude-sonnet-4-6" [skills] enabled = ["github-code-review", "github-pr-workflow"] [memory] type = "episodic" ttl_days = 30 [policies] rate_limit = "30/min" allowed_tools = ["read_file", "search_files", "patch"] audit = true ``` ### Mode 7: The Package Manager ```bash /install postgres # Install PostgreSQL MCP server /install brave-search # Install web search /registry-list # See all available servers /security-scan postgres # Scan server for vulnerabilities ``` Every server is security-scanned on install. Policies auto-applied. Audit trail tracks every tool call. --- ## The Deep Learning Layer Xavani has a **Context Enricher** that sits between you and the AI: 1. **Receives** your raw message 2. **Analyzes** against your UserProfile (style, knowledge, preferences) 3. **Enriches** with implicit context the AI needs 4. **Matches skills** — detects relevant procedures from the installed skill library 5. **Reiterates** — confirms understanding before executing 6. **Forwards** the enriched message to the LLM After ~10 sessions, Xavani adapts to your communication style, humor preferences, expertise level in different domains, favorite project types, and work schedule. --- ## Power User Workflows ### Code Review Pipeline ```bash /install filesystem /install github xavani --gateway & xavani --message "Review the last 3 commits for security issues" ``` ### Research + Memory ```bash / "Research the current state of WebAssembly in 2026" # Next session — no context needed / "Continuing from where I left off on Wasm research" ``` ### Dashboard Monitoring ```bash xavani # In one terminal open http://localhost:8081 # In another — live metrics ``` --- ## Configuration Xavani stores everything in `~/.xavani/`: ``` ~/.xavani/ config.yaml # Main configuration (provider, model, terminal, etc.) .env # API keys (never uploaded anywhere) logs/ # Session logs + traces + metrics traces.jsonl # OpenTelemetry trace spans metrics.json # Performance metrics agents/ # Per-agent runtime logs skills/ # Loaded skills policies/ # Policy rules (YAML) installed/ # Installed MCP server configs data/ # Memory store (SQLite) memory/ # Episodic + procedural memory bridge/ # Protocol bridge state agent-images/ # Portable agent image registry ``` --- ## Architecture ``` ┌──────────────┐ │ YOU │ │ (CLI / TUI) │ └──────┬───────┘ │ ┌───────────────────────────────┴───────────────────────────────┐ │ XAVANI AGENT │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ CONTEXT ENRICHER (Deep Learning Layer) │ │ │ │ 1. RECEIVE → 2. ANALYZE → 3. ENRICH → 4. CHECK SKILLS │ │ │ │ 5. REITERATE → 6. FORWARD │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────┐ ┌───────────────┐ ┌────────────────────┐ │ │ │ REPL / CLI │ │ SKILLS ENGINE │ │ MCP GATEWAY │ │ │ │ (prompt │ │ (on demand) │ │ (localhost:8080) │ │ │ │ toolkit) │ │ SkillOrch. │ │ PolicyEngine │ │ │ └────────────┘ └───────────────┘ │ Auth + RateLimit │ │ │ │ Audit Trail + Logs │ │ │ ┌───────────────────────────────────┴────────────────────┐ │ │ │ PROTOCOL BRIDGE │ │ │ │ MCP ↔ A2A ↔ OpenAPI bidirectional translation │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ MEMORY LAYER │ │ │ │ Episodic (FTS5 SQLite) + Procedural (Pattern Learning) │ │ │ │ Cross-Agent Context Sharing + Auto-Archiving │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ OBSERVABILITY STACK │ │ │ │ OpenTelemetry Traces · Metrics · Dashboard (:8081) │ │ │ │ CLI Audit Viewer · Trace Export │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ AGENT RUNTIME │ │ │ │ Portable .agent.toml · Lifecycle Manager · Isolation │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ PROVIDER ABSTRACTION LAYER │ │ │ │ OpenAI · Anthropic · Gemini · DeepSeek · GLM · Qwen │ │ │ │ Yi · MiniMax · Kimi · Baichuan · Step · Doubao · │ │ │ │ Ernie · SenseTime · Ollama · OpenRouter · xAI · Groq │ │ │ │ HuggingFace · NVIDIA · Arcee · Azure · AWS · + more │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ LOCAL STORAGE │ │ │ │ SQLite · FTS5 · File System · JSONL Traces │ │ │ │ ~/.xavani/ — never leaves your machine │ │ │ └────────────────────────────────────────────────────────┘ │ └───────────────────────────────────────────────────────────────┘ ``` --- ## What's New ### v0.3.0 — "Everyday Carry" (2026-08-23) - **Desktop workflow** — persistent tasks, reminders, profile switching, richer settings, imports, skills marketplace and two-way visual preview editing. - **Real skills hub** — GitHub, skills.sh, well-known, ClawHub and bundled sources with taps, parallel search and trust-ranked deduplication. - **Persistent work state** — todos and the outstanding-work ledger survive sessions. - **Document generation** — styled PPTX, XLSX and DOCX output with quality presets. - **Preview control** — the agent can open and navigate the Xavani Desktop preview dock. ### v0.2.0 — "The Big Bang" (2026-08-22) - **Loop engine** — /loop with stop conditions, reflexion failure notes, runaway guards, and /loop watch: cron-scheduled watchdog passes that stay silent while running and alert on finish. - **Eval harness** — 21 categorized tasks with jsonschema/pytest/exit_code/llm_judge verifiers, per-category medians, p95, flake detection, fingerprinted results, and a config leaderboard. - **Advisor role** — a second model reviews every reply on its own context and appends [high]/[medium]/[low] notes inline (/advisor). - **Agent hub** — live subagent roster with steer, kill, and revive (/hub). - **Approval gate** — write journal with inverse-patch rollback, /revert, /permissions, batch approval preview, dry-run mode. - **RPC mode** — NDJSON-over-stdio protocol with answerable tool cards for embedders (`python3 -m xavani_cli.rpc_mode`). - **Workflow tooling** — atomic commit splitter with cycle rejection, cross-agent config importer with provenance, memory bank (retain/recall/reflect/learn), deterministic /macro steps, SESSION_HANDOFF.md generator. - **CLI polish** — xavani-terminal and xavani-ember skins, strict skin validation, expanded doctor checks. - **Eight workflow packs** — inbox-triage, meeting-notes, invoice-extraction, weekly-review, research-monitor, document-draft, expense-log, crm-lite (189 built-in skills). ### v0.1.2 — "Durability & Capability" (2026-08-21) - **Durable turn-bank state** — version-2 checkpoints bind counts and pending turns with SHA-256 proof across restarts, compression, branches, and stale state. - **Strict memory proof** — malformed results, duplicate content, unmatched requests, and invalid legacy history no longer clear pending turns. - **Faster task harness** — records median time, p90 time, tokens, success rate, and cost per successful task. - **Assistant capability packs** — business operations, personal productivity, game theory, mental models, AI-native UI, Ponytail, and anti-slop TypeScript/JavaScript guidance. - **181 built-in skills** — local skill indexing and append-only manifest generation now include every new pack. ### v0.1.1 — "Reliability & Steer" (2026-08-05) - **/steer reliability** — end-to-end verified steer pipeline (TUI → gateway → AIAgent → drain into the next tool result), with idle fallback to queue and leftover-steer delivery at turn end. - **Python 3.14 compatibility** — memory-manager thread pool fixed against the 3.14 stdlib refactor. - **D01 secret redaction regression** — non-text content parts pass through untouched; vision-model tool results restored. - **D08 subcommand gating** — `deps-provenance` registered in the CLI fast-path. - **Update-path dependency refresh** — `xavani update` refreshes pinned deps with `--upgrade` and refreshes cua-driver. ### 0.1.1.5 — "Harness & Tokens" (2026-08-06) - **Complete update programme** — every planned reliability item ships: turn finalizer, session-store recovery, turn lease, CoT budget, learn prompt pack, episodic memory summarization, reasoning-effort auto-tuning, security-audit command, secrets vault CLI, update lock, PII/egress/tirith/rotation/audit/sandbox hardening, health export, turn timeline, flake dashboard, ACP hardening, Windows portable installer, Nix cache, notifications, daily digest, follow-up queue. - **Eval-gate on steer changes** — golden evals run in CI when steer paths change; a failing eval blocks the merge. - **Tool-call quality metrics** — per-session CSV/JSONL: tool, latency, success, retries; surfaced via `xavani stats`. - **Self-critique pass** — config-gated final-answer review against a rubric, bounded to one fix iteration. - **Context-budget governor UI** — warns at 85%, blocks new tools at 95%. - **Flake dashboard** — `tests/flakiness.json` aggregated into per-release reports. - **Research-backed harness** — the harness upgrade plan drew on public research (Anthropic evals, Red Hat 8-stage framework, Kimi K3, DeepSeek-V4, OpenMLE, TraceCompiler, AgentSLABench). - **Pinned dependencies** — pydantic-settings, jsonschema (direct pins), diskcache, structlog, orjson added, exact-pinned and uv-locked. ### Research Guidelines Enforcement - Expanded mandatory research guidelines from 11 to 21 thinkers. - New thinkers: Chollet, Weng, Huyen, Yan (AI/ML), Beck, Hickey, Fowler, Carmack, Kernighan & Pike, Dijkstra (software craft). - Karpathy guidelines strengthened with 4 operating rules. - **Enforcement engine:** `xavani guidelines list|show|check` — pre-ship verification gate that checks diffs for surgical changes, eval presence, scrub compliance, and more. ### New Tools - **Eval Harness** (`eval_harness`) — define, run, and report evaluation cases. Build the eval first. - **Mixture-of-Agents** (`mixture_of_agents`) — route problems through multiple models collaboratively. - **Computer-Use** (`computer_use`) — drive screen/keyboard/mouse via MCP server. - **Guidelines Gate** (`guidelines_gate`) — pre-ship verification against research principles. - **Budget Governor** — per-session token/cost budget monitoring with threshold warnings. ### 754 Cybersecurity Skills - Full import from [mukul975/Anthropic-Cybersecurity-Skills](https://github.com/mukul975/Anthropic-Cybersecurity-Skills) (Apache-2.0). - Covers: threat hunting, incident response, cloud security, red team, forensics, and more. - Located under `optional-skills/cybersecurity/`. ### 16 Elite Build-and-Ship Skills - TDD, brainstorming, code review, frontend design, MCP builder, security review. - Ship-it preflight, RFC writer, PRD writer, release engineering. - Performance profiling, incident response, observability setup. - Database migration playbook, secure-by-default checklist, verification before completion. ### Skill Auto-Improvement - `xavani_learner/skill_improver.py` — proposes draft SKILL.md from successful trajectories. - Drafts go to `~/.xavani/skill-drafts/` for human review (never auto-written to `skills/`). ### Hibernation Adapters - `tools/environments/hibernation.py` — hibernate/resume lifecycle for long-running sandboxes. ### Budget Governor - Per-session token/cost budget monitoring with threshold warnings. - Enable via env: `XAVANI_TOKEN_BUDGET=1.0` (USD cap) or config: `session_token_budget: 1.0`. --- ## Skills Built-in and optional skills cover software delivery, research, security, infrastructure, media, productivity and integrations. Skills run through the same local-first agent and use external services only when configured. | Category | Skills | Use Cases | |----------|--------|-----------| | Creative | 25 | ASCII art, diagrams, video, music, design | | ML/AI | 36 | Fine-tuning, RAG, embeddings, training | | Research | 16 | Web search, deep research, paper writing | | GitHub | 6 | Code review, PR workflow, repo management | | MCP | 3 | Build, deploy, manage MCP servers | | Software Dev | 12 | TDD, debugging, planning, code review | | Productivity | 16 | Notion, Google Workspace, PDFs, OCR | | Autonomous Agents | 7 | Deploy coding agents | | Finance | 8 | Models, analysis, presentations | | +19 more | 40 | Blockchain, gaming, email, IoT, security | --- ## Privacy Xavani collects **nothing**. Zero telemetry. Zero analytics. Zero phone-home. Zero crash reports. Your API keys stay in `~/.xavani/.env` and are never uploaded. The environment variables `XAVANI_DISABLE_TELEMETRY=1` and `DO_NOT_TRACK=1` are forced at startup. All data — logs, traces, metrics, memory, config — stays in `~/.xavani/` on your machine. --- ## About Enternovate Enternovate builds open-source AI infrastructure. We believe AI tools should be private, local, and accessible to everyone — not locked behind vendor clouds or data-harvesting business models. Xavani Agent is our flagship open-source project. MIT licensed. Free for any use, commercial or personal. ---

Built by Enternovate — Open Source.
Pronounced: shahr-vaa-nee
Buffalo out. ⚡

# Changelog All notable changes to Xavani Agent are documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [0.3.0] - 2026-08-23 — "Everyday Carry" Desktop-first minor release: the desktop app gains a persistent To-Do pane, cross-session reminders, an ambient activity pill, update and event notifications, profile switching from the sidebar, richer settings, expanded import sources, a skills marketplace UI, and two-way visual preview editing that maps on-canvas changes to source files. Engine-side: the skills hub is real again (GitHub, skills.sh, well-known, ClawHub, bundled index sources with taps and parallel search), todos persist in the profile home, an outstanding-work ledger tracks unfinished goals across sessions (/outstanding, /outstanding done), document generation covers pptx/xlsx/docx with quality presets, and the agent can drive the desktop preview dock. A Xavani-branded browser extension (MIT, derived from upstream with attribution) ships separately. ### Added - Skills hub: real GitHubSource, SkillsShSource, WellKnownSkillSource, ClawHubSource, and bundled OptionalSkillSource; TapsManager persistence; parallel_search_sources with per-source timeout; trust-ranked dedupe in unified_search. Description-based ranking across all sources. - Persistent todo store at ~/.xavani/todos.json (atomic writes, 0600). - Outstanding-work ledger at ~/.xavani/outstanding.jsonl with /outstanding and /outstanding done N. - generate_document tool: styled .pptx/.xlsx/.docx via corporate, minimal, and report presets. - preview_control tool: agent-driven desktop preview dock (open, navigate, close, status) gated to desktop sessions. - Desktop: dock To-Do pane with drag prioritization; notification stack; ambient activity pill; outstanding-item reminders; sidebar profile switcher plus settings shortcut; Memory & data and Voice cards; Gemini CLI, OpenCode, and generic-folder import sources; skills marketplace search/install/uninstall UI; cron create form; two-way visual editing with file-mapped edit briefs. ### Fixed - skills browse ImportError crash (parallel_search_sources missing). - Stale version strings in acp manifest and fast-entry expectations. - Slack slash clamp collision: local-only /debug excluded from messaging menus so parity tests hold when new session commands land. ## [0.2.0] - 2026-08-22 — "The Big Bang" Minor release across ten workstreams: approval-gate hardening, the loop engine, an expanded eval harness, harness cost hardening, oh-my-pi ports, an overlooked-feature pack, CLI polish, workflow packs, and release engineering. No breaking changes. ### Added - Pre-flight approval gate: write journal with inverse-patch rollback, /revert, /permissions manager, batch approval preview, dry-run mode. - Loop engine: /loop and /loop watch (cron-scheduled watchdog passes via `xavani -z`), stop conditions, reflexion failure notes, runaway and nested-loop guards, eval loops with rubric scoring, /loops prune. - Eval harness: 21 categorized tasks, jsonschema/pytest/exit_code/ llm_judge verifiers, per-task verifier timeouts, --category filter, p95 and per-category medians, --runs flake detection, fingerprinted --save results, config leaderboard, regression gate. - Harness hardening: model roles (default/smol/slow/plan/advisor) with config overrides; fallback chains, parallel tool execution, cache-hit telemetry, budget governor audited as already present in 0.1.x. - Ports from oh-my-pi, implemented better: advisor reviewer role with inline severity notes (/advisor), agent hub roster with steer/kill/ revive (/hub), atomic commit splitter with cycle rejection, conflict resolver, magic keywords (ultrathink/orchestrate/workflowz), NDJSON RPC mode with answerable tool cards, cross-agent config importer, memory bank tools (retain/recall/reflect/learn/edit). - Overlooked-feature pack: SESSION_HANDOFF.md generator, deterministic /macro steps, activity formatter across loop/eval commands. - CLI polish: xavani-terminal and xavani-ember skins, strict skin validation with clear errors, doctor checks for permissions.json, loops dir, and bench results dir. - Workflow packs: inbox-triage, meeting-notes, invoice-extraction, weekly-review, research-monitor, document-draft, expense-log, crm-lite (skills index grows to 189). ### Migration notes from 0.1.x - No config keys are removed. New optional keys: model.roles., cron.script_timeout_seconds, display.skin accepts the two new skins. - New data directories appear on first use: ~/.xavani/loops/, ~/.xavani/macros/, ~/.xavani/memories/bank/, ~/.xavani/scripts/. - New slash commands are desktop-only where noted; messaging-platform menus stay under Slack's 50-slash cap via curation. - Python 3.11+ remains the floor; no new mandatory dependencies. ## [0.1.2] - 2026-08-21 — "Durability & Capability" Minor release with durable turn-bank recovery, a faster task harness, and new business, personal, design, and code-quality skill packs. No breaking changes. ### Added - Durable version-2 turn-bank state with count-bound SHA-256 checkpoints, pending-sequence proof, compression lineage, and branch isolation. - Strict restart recovery for stale, malformed, future, and legacy state. - Canonical transcript selection that stores raw persisted output instead of transformed display output. - Synthetic control-message filters for compression, continuation, kanban, empty-response, MCP reload, and maximum-iteration paths. - Task benchmark harness with median time, p90 time, token use, success rate, and cost-per-successful-task metrics. - Ponytail minimal-code pack with 6 skills and MIT attribution. - Business assistant, personal assistant, game theory, mental models, AI-native UI, and anti-slop TypeScript/JavaScript skills. ### Changed - Built-in skill indexing now includes local `oag_skills` entries and keeps the skills manifest append-only. - Built-in skill count increased to 181. - Memory-write results now require `success=true` and `staged` absent or exactly `false`. ### Fixed - Legacy state no longer writes memory when history cannot prove its checkpoint. - Repeated identical turns now use occurrence-aware persistence proof. - Session changes clear pending state unless a valid compression lineage proves continuity. - Failed due writes retry on each later completed turn. - Whole-bank proof now binds the header count to the pending base and end. - An unmatched latest request cannot reuse an older identical response. ## [0.1.1.5] - 2026-08-06 — "Harness & Tokens" Release with the research-backed harness upgrade, the token vault, and the completed update programme. No breaking changes. ### Added - **`xavani tokens` CLI** — one credential vault for all Enternovate products: `add`, `list`, `remove`, `show-usage`. Tokens live in `~/.xavani/credentials.json` with 0600 permissions; values are never printed back. `xavani doctor` now validates the vault (permissions, empty entries) in a Token Vault section. - **Eval gate (harness item 1)** — golden steer-path evals run in CI on any PR touching the steer paths (`run_agent.py`, `conversation_loop.py`, `agent_init.py`, `cli.py`, harness modules). A failing eval blocks the merge. Runner: `scripts/run_golden_evals.py`. - **Tool-call metrics (harness item 2)** — `agent/tool_metrics.py` records one row per tool call (tool, latency ms, success, retries, error class) to per-session JSONL/CSV under `~/.xavani/metrics/`. Wired into both dispatch paths (concurrent worker and sequential tail); a metrics failure can never break tool execution. - **Self-critique pass (harness item 3)** — `agent/self_critique.py` runs a bounded model review of the final answer against a rubric (correctness, completeness, citations, STE compliance) and may rewrite it once. Config-gated: `harness: {self_critique: true}` in config.yaml (default off). Wired at end-of-turn; the reviewer routes through the agent's active model configuration; failures keep the original answer. - **Context-budget governor UI (harness item 4)** — `agent/context_budget_ui.py` classifies context usage: warn at 85% with a compaction suggestion, block at 95%. Wired into `/usage` and the status bar (⚠ at warn, ⛔ at block). - **Flake dashboard ingestion (harness item 5)** — `scripts/flake_dashboard.py` + `tests/test_flake_dashboard.py` aggregate flake evidence from fixture runs (Tukey: the data may not contain the answer; a visible flake report turns guesswork into measurement). - **Update programme complete** — every planned reliability item ships with test evidence, including D07 sandbox subcommand gating and C03/C04/C06 completions. - **Harness research** — the improvement plan drew on public research (Anthropic evals, Red Hat 8-stage, OpenMLE, TraceCompiler, AgentSLABench and more) with sources and test plans. ### Changed - **Pinned 5 dependencies**: pydantic-settings 2.14.2, jsonschema 4.26.0, diskcache 5.6.3, structlog 26.1.0, orjson 3.11.9 (locked in uv.lock). - **`xavani update`** refreshes pinned dependencies with `--upgrade`. - **README** — removed the stale v0.3.0 section; release notes now match the real 0.1.1 / 0.1.1.5 history. ### Fixed - **D07 sandbox + subcommand gating** — `sandbox` no longer collides with built-in subcommands; autostash and gating test expectations updated to the `--upgrade` update pipeline (7c6a0ab). - **CI** — `github-script` action pinned to a resolvable commit SHA (v7.1.0). ## [0.1.1] - 2026-08-05 — "Reliability & Steer" Patch release. Fixes, CI hardening, and the first tranche of the update programme. No breaking changes. ### Fixed - **/steer reliability** — end-to-end verification of the steer pipeline (TUI `/steer` → gateway `session.steer` → `AIAgent.steer()` → drain into the next tool result), including idle fallback to queue, leftover-steer delivery at turn end, and a rebuilt TUI bundle. - **Python 3.14 compatibility** — `_DaemonThreadPoolExecutor` in `agent/memory_manager.py` broke against the 3.14 stdlib refactor of `concurrent.futures.thread._worker`; `_adjust_thread_count` is now version-agnostic (6 memory-manager tests restored). - **D01 secret redaction regression** — `_redact_content_parts()` mangled non-text content parts (e.g. `image_url`) by embedding whole parts as nested text; non-text parts now pass through untouched and the identity contract (`content is result["content"]`) is preserved when nothing is redacted (restores vision-model tool results). - **D08 subcommand gating** — `deps-provenance` added to `_BUILTIN_SUBCOMMANDS` so the CLI fast-path skips plugin discovery for it. - **Session export timestamps** — export tests computed expectations in the ambient timezone while the suite pins TZ=UTC; expectations are now UTC (renderer was correct). - **CI — Windows footgun** — `os.kill(pid, 0)` in `tools/long_running.py` replaced with `psutil.pid_exists` (safe on Windows; bpo-14484). - **CI — Nix** — refreshed the stale `ui-tui` npm-deps hash in `nix/tui.nix`. ### Added (update programme, tranches 1 & 2) - **E03 Crash forensics** — watchdog + `shutdown_forensics` extension; on abnormal exit, last log lines and thread stacks are dumped to `~/.xavani/logs/crash-.txt` (with tests). - **E04 Memory/disk watchdog** — warn at 80% memory / 90% disk, auto-rotate logs past 500 MB (`gateway/memory_monitor.py` extension). - **E05 Per-session cost CSV export** — `xavani_cli/session_export_csv.py`; per-session token/cost rows for accounting. - **F02 Homebrew formula refresh automation** — CI workflow (`.github/workflows/homebrew-refresh.yml`) that bumps `packaging/homebrew/xavani-agent.rb` on release. - **F03 Docker healthcheck** — `HEALTHCHECK` instruction + `docker/healthcheck.sh` hitting the gateway `/health` endpoint. - **G03 Autonomous maintenance window** — `xavani_operator/maintenance.py`: idle-time DB VACUUM, log rotation, stale-lock GC (with tests). - **C02 Model cost guard** — `xavani_cli/model_cost_guard.py`; `/model` switches to models above $20/M input tokens now surface a warning via `ModelSwitchResult.warning_message` (shared by CLI and gateway). - **C07 Bang shell** — `!cmd` executes a shell command from the chat line (120s timeout, output + exit code printed, never touches the agent). - **B02 Context breakdown** — `/usage` now shows a per-call breakdown of system/conversation/cache tokens (estimates marked, cache counts exact). - **C08 Prompt stash** — `/stash save|list|show|load|rm`; draft prompts persist across sessions under `~/.xavani/prompt-stash/`. ## [0.1.0] - 2026-08-05 — "First Official Release" The first public release of Xavani Agent. Everything before this date — internal development builds and pre-release version numbers — has been consolidated into this single release. Versioning now starts cleanly at 0.1.0; the next release is 0.1.1 (SemVer patch). Xavani is a fully local, zero-telemetry AI agent gateway: one CLI and TUI to 30+ AI providers, with an MCP gateway, a persistent memory layer, a protocol bridge, observability, a portable agent runtime, cron jobs, webhooks, and messaging gateways for Telegram, Discord, Slack and WhatsApp. ### Core platform - **Agent runtime** — turn-based loop with tool execution, interrupt / redirect / steer semantics, stream single-writer fencing, context compression, and a deterministic-first (R10) architecture: the LLM only *generates*; routing, detection and governance are model-free. - **MCP gateway** — native Model Context Protocol client/server; register external MCP servers as tools; expose the tool registry over MCP. - **Memory layer** — episodic + procedural memory, hybrid vector/full-text search, zero-cloud, durable across sessions (the Nyarhi memory engine). - **Providers** — 30+ OpenAI-compatible and native providers with an intelligent model router (`xavani model --route `). - **Messaging gateways** — Telegram, Discord, Slack, WhatsApp (+ more); slash commands, sessions, approvals, and per-platform auth. - **Cron, webhooks, delegation** — scheduled jobs, inbound webhooks, sub-agent orchestration with context isolation. - **Skill system** — 169+ skills, reusable procedural memory, skill auto-improvement loop, and a skills index. - **Tools** — 90+ tools including `read_document`, `eval_harness`, `mixture_of_agents`, `computer_use`, `guidelines_gate`, `process`, `session_search`, `organize_files`, and a budget governor. ### Sentience & wisdom (deterministic, zero-LLM at the core) - **Quantum Decision Cortex** (`xavani_operator/quantum/`) — decisions held in superposition, outcomes simulated, correlated risks interfered, collapse by Born rule; classical solver always on, optional QPU backends. - **The Oracle** (`xavani_wisdom/`) — consequence projector, downfall detector, self-fault watch-patterns from the 8pm error-log ritual. - **Always-On Companion** — 24/7 daemon (`xavani operator serve`), kill-switch, advisor rituals (morning brief, 8pm error-log, tomorrow plan, hourly task-chase), intelligent model router. - **Mission Control** — deep-navy dashboard with Sentience page, quantum waveform, and Oracle consequence-check. ### The complete update programme (implemented, tested, verified) A Reliability & Correctness (20) · B Intelligence & Reasoning (15) · C Operability & Developer Experience (20) · D Safety & Guardrails (15) · E Observability & Debugging (10) · F Distribution & Ecosystem (10) · G Autonomy & Proactivity (10). Highlights: - Turn leases, session redirect with lock, turn persistence drain, bounded responses, session-store recovery + FTS rebuild, code-skew detection, restart-loop guard, systemd readiness. - Chain-of-thought budget enforcement, context-breakdown widget, learn prompt pack, delegation context isolation, subagent lifecycle API. - Unified provider catalog, model cost guard, `xavani security-audit`, secrets vault CLI, session recovery, update pipeline with lock, bang shell, prompt stash. - Secret redaction on tool output, PII redaction parity, egress policy enforcement, Tirith command-guard, credential rotation reminders, append-only mutation audit, dependency provenance report. - Gateway health export, turn timeline trace, crash forensics, memory/disk watchdog, per-session cost CSV, flake dashboard. - ACP server hardening, Homebrew refresh automation, Docker healthcheck, Windows portable installer, Nix flake cache, skills freshness watchdog. - Smart notifications, daily learning digest, autonomous maintenance, follow-up question queue. ### Security & privacy - Zero telemetry, local-first, keys stay on the machine. - Egress allowlist, sandbox hardening (rlimits, seccomp/Landlock detection), RLS-ready multi-tenant design, encryption at rest/in transit, audit trail on AI actions. - CI security stack: Bandit, Gitleaks, Semgrep, pip-audit, Trivy, OSV scanner, supply-chain audit, dependency provenance, and the R10 deterministic invariant enforced in tests. ### Distribution - PyPI wheel (`pip install xavani-agent`), Homebrew formula, Docker image with HEALTHCHECK, Nix flake + Cachix cache, Windows portable installer, one-line installers (`curl -fsSL https://get.xavani.dev | bash`). - MIT licensed. Derived from Hermes Agent by Nous Research (MIT) with attribution; maintained independently by Enternovate.