Kabot 🐺

Resilient Memory. Methodical Execution. Native Reasoning.

---

Kabot is a personal AI assistant engineered for resilience, complex task execution, and long-term memory. It isn't just a chatbot; it's an autonomous agent that runs on your own hardware, remembering context across restarts and methodically planning its actions.

It bridges the gap between simple chatbots and autonomous software engineers. While typical agents operate blindly, Kabot implements a Methodical Engineering Workflow (Brainstorm → Plan → Execute) and relies on a proprietary Hybrid Memory Architecture (SQLite + BM25 + vector embeddings + reranking) to handle long-running projects with hyper-efficient token usage and zero "amnesia".

If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.

Website · Docs · How-To-Use · Getting Started · Telegram · FAQ

---

What's New In v0.6.7

• OpenRouter normalization for model identifiers and provider routing to reduce invalid requests.
• Telegram slash command handling now supports bot mention suffixes and /model directives.
• Setup wizard fallback ordering now supports selecting and reordering fallback chains.
• Failover classification hardening with expanded patterns and tests.

If you are upgrading from 0.6.6, the two most important changes are:

• OpenRouter model identifiers and provider routing are now normalized to reduce invalid requests.
• Telegram slash commands now support bot mention suffixes and /model directives.

---

📑 Table of Contents

• 🚀 Quick Start
• 🤖 Multi-Agent Orchestration
• 🔌 Multi-Channel Instances
• 🛠️ Operations & Plugin Lifecycle
• 🏗️ Architecture
• 🤖 Supported Models
• ⚙️ Configuration Reference
• ⚡ Slash Commands & Directives
• 🎛️ Model Management Tutorial
• 🔒 Security
• 🤝 Development & Contributing
• 📜 Star History
• 🙌 Community

---

🚀 Quick Start

Runtime: Python 3.11+
Tested on Windows, macOS, Linux (Ubuntu/Debian), and Termux.

Beginner Quick Path (Recommended)

If you are new, follow this exact flow:

1. Install Kabot
2. Run setup wizard (kabot config)
3. Start Kabot (kabot gateway)
4. Test chat (kabot agent -m "Hello")

No need to clone repo for normal usage.

Recommended optional step for v0.6.6:

5. Inspect MCP availability (kabot mcp status)

1) Install Kabot

Universal (recommended for most users):

pip install kabot

If pip is not found, run with Python:

python -m pip install kabot

If you already installed Kabot before and want to upgrade:

pip install -U kabot

1b) One-Command Auto Installer (Optional)

Use this if you want automatic environment setup.
Installer scripts auto-detect runtime profile (macOS/Linux/WSL/Windows/Termux/headless) and prepare sane defaults.

Linux / macOS / WSL2

curl -fsSL https://raw.githubusercontent.com/kaivyy/kabot/main/install.sh | bash

On Linux/macOS, the one-command installer also bootstraps common runtime extras automatically:

• verifies beautifulsoup4 inside Kabot's virtualenv,
• installs the Python playwright package if needed,
• runs python -m playwright install chromium.

If you want to skip browser bootstrap on headless/minimal hosts, set:

KABOT_SKIP_BROWSER_BOOTSTRAP=1 curl -fsSL https://raw.githubusercontent.com/kaivyy/kabot/main/install.sh | bash

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/kaivyy/kabot/main/install.ps1 | iex

2) First Setup (Required Once)

kabot config

In wizard:

• choose your AI provider,
• paste API key/token,
• save config.

Notes:

• Google Suite in setup wizard is Kabot's native Google auth path. It does not require npm, Node.js, or gog.
• Skills in setup wizard manages skill config, env keys, and manual dependency install plans. It does not auto-run npm/brew installs for you.
• MCP is now a first-class runtime capability. Use config plus kabot mcp ... commands to inspect what is really available instead of relying on prompt-only assumptions.
• When setup wizard syncs built-in skills, it is copying skill definitions (SKILL.md) into the workspace. That is separate from installing third-party runtimes or logging into external services.

3) Start Kabot

kabot gateway

4) Test Quickly

kabot agent -m "Hello Kabot"

4 Commands You Should Remember

kabot config       # open setup wizard
kabot gateway      # run the bot gateway
kabot doctor --fix # auto-diagnose and repair common issues
kabot doctor routing # validate routing/guard sanity before deploy
kabot mcp status   # inspect configured MCP servers

Python-Native MCP Quickstart

Kabot 0.6.6 ships a Python-native MCP runtime. That means MCP is no longer just an instruction trick; Kabot can attach real MCP servers per session and expose only the capabilities that actually exist.

Useful commands:

kabot mcp status
kabot mcp example-config
kabot mcp inspect local_echo

Minimal config shape:

{
  "mcp": {
    "enabled": true,
    "servers": {
      "local_echo": {
        "transport": "stdio",
        "command": "python",
        "args": ["-m", "kabot.mcp.dev.echo_server"]
      }
    }
  }
}

Why this matters:

• Kabot now knows which MCP tools are real for the current session.
• MCP resources and prompts can be pulled into a turn without pretending they are ordinary files.
• follow-up continuity stays stronger, so MCP context is reused when helpful but does not override a newer clear user request.

Runtime Token Mode (Boros vs Hemat)

Default is boros (richer context, higher token usage).

Quick toggle without opening full wizard:

kabot config --token-mode boros
kabot config --token-mode hemat

Shortcut toggle:

kabot config --token-saver     # ON  -> hemat
kabot config --no-token-saver  # OFF -> boros

You can also set this from setup wizard: kabot config -> Tools & Sandbox -> Runtime Token Mode.

Core-Only Manual Install (Minimal Footprint)

If you prefer isolated venv install:

python3 -m venv ~/.kabot/venv
source ~/.kabot/venv/bin/activate
pip install -U pip
pip install kabot
kabot config
kabot gateway

Notes:

• kabot from PyPI is enough for runtime operation.
• WhatsApp bridge and node-based skill installers still require Node.js + npm.
• Bridge source is bundled and prepared under ~/.kabot/bridge on first local bridge setup.

Termux (Android)

pkg update && pkg upgrade
pkg install python git clang make libjpeg-turbo freetype rust
termux-setup-storage
pip install -U pip
pip install kabot
kabot config
kabot gateway

Developer Install (Optional)

Use this only if you want to modify source code:

git clone https://github.com/kaivyy/kabot.git
cd kabot
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .
kabot config
kabot gateway

Gateway runtime notes:

• kabot gateway now defaults to config.gateway.port from setup/config.
• Use kabot gateway --port <N> to override for one run.
• If gateway bind mode is set to tailscale, Kabot activates Tailscale Serve at startup and keeps gateway bind on loopback for safer exposure.
• If gateway.tailscale=true (with non-tailscale bind mode), Kabot activates Tailscale Funnel at startup.
• Lightweight dashboard is available at /dashboard (SSR + HTMX, low-RAM friendly).
  • richer operator panels are now available in the same surface:
    • Chat panel (runtime prompt send + live log auto-refresh, now with SSE stream), with per-message model controls:
      • provider selector (all registered providers),
      • model override input (provider/model or alias),
      • model suggestions now auto-refresh by selected provider (from runtime model registry snapshot),
      • fallback builder UI (add/remove chips) with provider-aware suggestions,
      • channel/chat target passthrough for advanced operator routing.
    • Sessions panel (recent session list + clear/delete actions, instant panel refresh after action),
    • Nodes panel (runtime/channel node view + start/stop/restart actions, state-aware button disable, instant panel refresh after action),
    • Config panel (safe token-mode quick edit + config snapshot),
    • Control panel (runtime control actions).
  • JSON endpoints:
    • /dashboard/api/status
    • /dashboard/api/chat/history
    • /dashboard/api/chat/stream (SSE)
    • /dashboard/api/sessions
    • POST /dashboard/api/sessions (sessions.clear / sessions.delete)
    • /dashboard/api/nodes
    • POST /dashboard/api/nodes (nodes.start / nodes.stop / nodes.restart)
    • /dashboard/api/config
  • POST /dashboard/api/chat accepts optional model routing args:
    • provider
    • model
    • fallbacks (comma-separated string or list)
    • channel
    • chat_id
• gateway.auth_token supports scoped mode:
  • Plain: my-token (legacy full access)
  • Scoped: my-token|operator.read,operator.write,ingress.write
  • operator.read is required for dashboard/status routes.
  • operator.write is required for dashboard control routes (/dashboard/api/control, /dashboard/partials/control POST).
  • ingress.write is required for webhook ingress routes.
  • Scope shortcuts are supported: operator.*, ingress.*, <family>.admin, *.
  • operator.write also grants read-only dashboard access.
• Dashboard access:
  • No gateway auth token: open http://127.0.0.1:<port>/dashboard
  • With gateway auth token: open http://127.0.0.1:<port>/dashboard?token=<your-token>
  • For API clients, you can still use header auth: Authorization: Bearer <your-token>
  • Query-token auth is intentionally limited to /dashboard* routes (not webhook ingress).

Chatting

Once the gateway is running, you can talk to Kabot via:

• CLI: kabot agent -m "Hello" (Fastest for testing)
• Telegram: DM your bot.
• Discord: Mention the bot in a channel.

AI-Driven, But Grounded

Recent runtime work makes Kabot behave more like a serious coding/operator agent:

• if the user asks a normal question, Kabot should answer directly,
• if the user asks for a real side effect, Kabot should choose tools or skills,
• if the user follows up with yes continue or lanjut, Kabot should continue the pending task instead of guessing a new tool,
• if delivery or execution cannot be verified, Kabot should fail honestly instead of pretending the task is already done.

That balance matters more than "always use tools" or "never use tools". Kabot is designed to stay AI-driven while still being evidence-based.

---

• Persistent Subagents: Delegate tasks like "Research this library" to background agents. These subagents persist their state to disk (.json registry), so they survive system reboots and can be queried days later.

💾 Hybrid Memory Architecture

Unlike typical stateless agents, Kabot is completely stateful and amnesia-proof, employing a military-grade memory system that exceeds standard solutions like Mem0.

• Two-Tier Persistence: Blends a relational SQLite database for exact conversation chains, extracted facts, lessons, and metadata with a ChromaDB vector store for semantic retrieval.
• Full Hybrid Retrieval: Hybrid mode keeps semantic embeddings, BM25 lexical search, reciprocal-rank fusion, temporal decay, and reranking active for every query instead of relying on keyword buckets to decide which half of memory to use.
• Configurable Modes: Switch between hybrid for full semantic memory or sqlite_only for lightweight exact search, depending on your hardware and latency budget.
• Reranker & Token Guard: Employs a rigorous three-stage filtering pipeline (Threshold ≥0.6, Top-K, and Hard Token Limit) to reduce context window bloat by up to 72% and eliminate hallucinations.
• Subprocess Embeddings: The default all-MiniLM-L6-v2 embedding model runs in a separate worker process, so RAM is actually returned to the OS after unload instead of lingering inside the main Python process.

🔌 Universal Connectivity

One brain, many bodies. Kabot acts as a central control plane.

Platform	Features	Setup Guide
Telegram	Full rich chat, voice notes, file sharing	Setup Guide
Discord	Channel/DM support, detailed embeds	Setup Guide
Slack	Workspace integration, thread support	Setup Guide
WhatsApp	(Beta) Via local bridge	Setup Guide
CLI	Real-time terminal chat for local debugging	Built-in

---

🤖 Multi-Agent Orchestration

Click to expand

Kabot supports two advanced multi-agent systems that can work independently or together, enabling sophisticated task execution and context separation.

System 1: Standard Multi-Agent (Context Separation)

Multiple independent agents with separate contexts, each specialized for different domains or purposes.

Key Features:

• Separate Contexts: Each agent maintains its own conversation history and memory
• Per-Agent Configuration: Custom model, workspace, and tool restrictions per agent
• Message Routing: Automatic routing based on channel/platform via bindings
• Session Isolation: Each agent has isolated session storage

Use Cases:

• Separate work/personal/family contexts
• Domain-specific agents (coding/research/writing)
• Multi-user scenarios with different access levels
• Testing different models for the same task

CLI Commands:

# List all configured agents
kabot agents list

# Add a new agent
kabot agents add work --model anthropic/claude-3-5-sonnet-20241022 --workspace ~/work

# Delete an agent
kabot agents delete work

# Bind agent to specific channel
# Edit config.json to add bindings:
{
  "agents": {
    "bindings": [
      {"agent_id": "work", "channel": "telegram", "chat_id": "123456"},
      {"agent_id": "personal", "channel": "discord"}
    ]
  }
}

Example Configuration:

{
  "agents": {
    "list": [
      {
        "id": "work",
        "name": "Work Assistant",
        "model": "anthropic/claude-3-5-sonnet-20241022",
        "workspace": "~/work",
        "default": false
      },
      {
        "id": "personal",
        "name": "Personal Assistant",
        "model": "openai/gpt-4o",
        "workspace": "~/personal",
        "default": true
      }
    ],
    "bindings": [
      {"agent_id": "work", "channel": "telegram", "chat_id": "work_chat_id"},
      {"agent_id": "personal", "channel": "discord"}
    ]
  }
}

Per-Agent Model Switching:

Kabot now supports per-agent model assignment, allowing you to:

• Use one model for multiple agents (cost-effective for similar tasks)
• Use different models for different agents (optimize for specific use cases)

Example 1: One Model for Multiple Agents

{
  "agents": {
    "list": [
      {"id": "work", "model": null, "default": false},
      {"id": "personal", "model": null, "default": false},
      {"id": "family", "model": null, "default": true}
    ]
  }
}

All three agents will use the global default model (e.g., Claude Sonnet), but maintain separate conversation histories.

Example 2: Different Models for Different Agents

{
  "agents": {
    "list": [
      {"id": "coding", "model": "anthropic/claude-3-5-sonnet-20241022", "default": false},
      {"id": "writing", "model": "openai/gpt-4o", "default": false},
      {"id": "quick", "model": "groq/llama3-70b", "default": true}
    ],
    "bindings": [
      {"agent_id": "coding", "channel": "telegram", "chat_id": "coding_chat"},
      {"agent_id": "writing", "channel": "telegram", "chat_id": "writing_chat"},
      {"agent_id": "quick", "channel": "telegram", "chat_id": "quick_chat"}
    ]
  }
}

Each agent uses a model optimized for its purpose: Claude for coding, GPT-4o for writing, Llama3 for quick queries.

How It Works:

• When a message arrives, Kabot resolves which agent should handle it via bindings
• If the agent has a model override, that model is used
• If model is null or not set, the global default model is used
• Model switching happens automatically per message

System 2: Collaborative Orchestration (Role-Based Collaboration)

Multiple agents with specialized roles work together on a single task, combining their strengths for complex problem-solving.

Roles:

• Master: Coordinates tasks and makes high-level decisions (default: GPT-4o)
• Brainstorming: Generates ideas and explores approaches (default: Claude Sonnet)
• Executor: Executes code and performs operations (default: Kimi K2.5)
• Verifier: Reviews code and validates results (default: Claude Sonnet)

Key Features:

• Agent-to-Agent Communication: Peer-to-peer messaging via MessageBus
• Task Delegation: Master agent distributes work to specialized agents
• Result Aggregation: Combines outputs from multiple agents
• Quality Control: Built-in verification and review workflow

Use Cases:

• Complex coding tasks requiring multiple perspectives
• Brainstorming → Implementation → Review workflows
• Tasks benefiting from different model strengths
• Quality-critical projects needing verification

CLI Commands:

# Enable collaborative mode
kabot mode set multi

# Check current mode
kabot mode status

# Disable collaborative mode (back to single-agent)
kabot mode set single

Example Workflow:

User: "Implement user authentication with JWT"
  ↓
Master Agent: Analyzes request, breaks down task
  ↓
Brainstorming Agent: Proposes 3 implementation approaches
  ↓
Master Agent: Selects best approach (JWT with refresh tokens)
  ↓
Executor Agent: Implements code, writes tests
  ↓
Verifier Agent: Reviews code, checks security
  ↓
Master Agent: Aggregates results → Returns to user

System 3: Autonomous Sub-agents (Background Delegation)

Kabot can spawn lightweight, specialized sub-agents to handle long-running or complex background tasks while the main agent remains responsive to your immediate chats.

Key Features:

• Background Execution: Delegate heavy research, coding, or data processing tasks without blocking your main conversation.
• Isolated Context: Each sub-agent runs with a laser-focused objective and its own memory, preventing context pollution in your main chat.
• Persistent Registry: Sub-agent states are saved to disk (.json). If the server restarts, they resume where they left off.
• Safety Limits: Built-in safeguards (maxSpawnDepth, maxChildrenPerAgent) prevent infinite spawning loops and control resource usage.

Use Cases:

• "Research these 5 URLs in the background and give me a summary when done."
• "Start a sub-agent to monitor this error log and figure out what caused the crash."

How It Works: The main agent uses the internal spawn tool to spin up a sub-agent worker. Once the worker finishes the task, it reports the final result back to the main agent's context or directly to your chat.

Combining All Systems

Both systems work together seamlessly:

• Multiple agents (System 1) can each use collaborative mode (System 2)
• Example: "work" agent uses multi-agent mode for complex tasks, "personal" agent uses single-agent mode for simple queries

Configuration Example:

{
  "agents": {
    "list": [
      {"id": "work", "model": "anthropic/claude-3-5-sonnet-20241022", "default": true},
      {"id": "research", "model": "openai/gpt-4o", "default": false}
    ]
  }
}

Then set mode per user:

# Work agent uses collaborative mode
kabot mode set multi --user-id user:telegram:work_chat

# Research agent uses single mode
kabot mode set single --user-id user:telegram:research_chat

When to Use Each System

Scenario	Recommended System
Separate work/personal contexts	Standard (System 1)
Complex multi-step coding tasks	Collaborative (System 2)
Testing different models	Standard (System 1)
Quality-critical projects	Collaborative (System 2)
Multi-user deployment	Standard (System 1)
Brainstorming + Implementation	Collaborative (System 2)
Simple queries	Single-agent (default)

Documentation:

• Multi-Agent System Details
• Collaborative Orchestration Guide

---

🔌 Multi-Channel Instances

Click to expand

Run multiple bot instances per platform with different configurations and agent bindings.

Overview

Kabot supports running multiple bots per platform simultaneously (e.g., 4 Telegram bots, 4 Discord bots). Each instance has:

• Unique ID: Identifies the bot instance (e.g., "work_bot", "personal_bot")
• Type-specific config: Token, credentials, and platform-specific settings
• Agent binding: Optional routing to specific agents for context separation
• Independent operation: Each instance runs as a separate bot with its own connection

Configuration

Via Setup Wizard:

kabot config
# Navigate to: Channels → Manage Channel Instances
# Use Add/Edit/Delete or Quick Add Multiple for batch setup

Via config.json:

{
  "channels": {
    "instances": [
      {
        "id": "work_bot",
        "type": "telegram",
        "enabled": true,
        "config": {
          "token": "123456:ABC-DefGhIjKlMnOpQrStUvWxYz",
          "allow_from": []
        },
        "agent_binding": "work"
      },
      {
        "id": "personal_bot",
        "type": "telegram",
        "enabled": true,
        "config": {
          "token": "789012:XYZ-AbcDefGhIjKlMnOpQrStUv",
          "allow_from": []
        },
        "agent_binding": "personal"
      },
      {
        "id": "team_discord",
        "type": "discord",
        "enabled": true,
        "config": {
          "token": "MTA5...",
          "allow_from": []
        },
        "agent_binding": "work"
      }
    ]
  }
}

Supported Channel Types

Type	Configuration Fields	Notes
telegram	token, allow_from, proxy	Get token from @BotFather
discord	token, allow_from, gateway_url, intents	Get token from Discord Developer Portal
whatsapp	bridge_url, allow_from	Requires WhatsApp bridge setup
slack	bot_token, app_token, mode	Socket mode supported

Use Cases

1. Work/Personal Separation

{
  "instances": [
    {"id": "work_bot", "type": "telegram", "agent_binding": "work"},
    {"id": "personal_bot", "type": "telegram", "agent_binding": "personal"}
  ]
}

• Different Telegram bots for work and personal use
• Each routes to its own agent with separate context
• No conversation mixing between work and personal

2. Multi-Team Deployment

{
  "instances": [
    {"id": "team_a_tele", "type": "telegram", "agent_binding": "team_a"},
    {"id": "team_b_tele", "type": "telegram", "agent_binding": "team_b"},
    {"id": "team_a_discord", "type": "discord", "agent_binding": "team_a"}
  ]
}

• Multiple teams using the same Kabot server
• Each team has dedicated bot instances
• Agent bindings ensure context isolation

3. Testing and Production

{
  "instances": [
    {"id": "prod_bot", "type": "telegram", "enabled": true},
    {"id": "test_bot", "type": "telegram", "enabled": true}
  ]
}

• Separate bots for production and testing
• Test new features without affecting production users
• Easy enable/disable for maintenance

High-Volume Setup (4-6+ Bots)

For fast setup of many bots:

kabot config
# Channels → Manage Channel Instances → Quick Add Multiple

You can:

• Create multiple Telegram/Discord/Slack/WhatsApp instances in one flow
• Auto-create dedicated agent per bot
• Set model override for newly created agents
• Keep one shared default model for all bots if preferred

Channel Instance Routing

Messages are routed using the format: type:id

Example:

• telegram:work_bot → Work Telegram bot instance
• telegram:personal_bot → Personal Telegram bot instance
• discord:team_discord → Team Discord bot instance

Routing notes:

• Base binding channel: telegram matches telegram:<instance_id>
• Exact instance binding channel: telegram:work_bot has higher priority
• Instance agent_binding is enforced at runtime for session/model routing

Backward Compatibility

Legacy single-instance configs continue to work:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "legacy:TOKEN"
    }
  }
}

• Legacy configs are processed after instances
• Both can coexist in the same configuration
• Gradual migration path available

---

🛠️ Operations & Plugin Lifecycle

Environment Check

Use env-check to verify runtime profile and recommended gateway mode:

kabot env-check
kabot env-check --verbose

This reports platform flags (windows/macos/linux/wsl/termux/vps/headless) and whether local or remote mode is recommended.

Remote Bootstrap

Use remote-bootstrap to generate/apply service startup guidance:

# Linux
kabot remote-bootstrap --platform linux --service systemd --dry-run
kabot remote-bootstrap --platform linux --service systemd --apply

# macOS
kabot remote-bootstrap --platform macos --service launchd --dry-run
kabot remote-bootstrap --platform macos --service launchd --apply

# Windows (Task Scheduler)
kabot remote-bootstrap --platform windows --service windows --apply

# Termux
kabot remote-bootstrap --platform termux --service auto --dry-run

Service behavior:

• kabot gateway in terminal is a foreground process (closing terminal stops it).
• For persistent background operation, enable service via wizard (kabot config → Auto-start) or kabot remote-bootstrap --apply.
• After service is installed and started, Kabot keeps running even if your SSH/terminal session closes.

Service Stop/Disable (Quick Reference)

# Linux (systemd user)
systemctl --user stop kabot
systemctl --user disable kabot

# macOS (launchd)
launchctl stop com.kabot.agent
launchctl unload -w ~/Library/LaunchAgents/com.kabot.agent.plist

# Windows (Task Scheduler, CMD/PowerShell)
schtasks /End /TN kabot
schtasks /Change /TN kabot /Disable

# Termux
sv down kabot
sv-disable kabot

Plugin Lifecycle Commands

Kabot now supports full plugin lifecycle operations:

# List installed plugins
kabot plugins list

# Install from local directory
kabot plugins install --source /path/to/plugin

# Install from git with pinned ref (tag/branch/commit)
kabot plugins install --git https://example.com/repo.git --ref v1.2.3

# Update plugin (uses tracked source by default)
kabot plugins update --target my_plugin

# Enable/disable
kabot plugins disable --target my_plugin
kabot plugins enable --target my_plugin

# Diagnose plugin health
kabot plugins doctor
kabot plugins doctor --target my_plugin

# Scaffold a new dynamic plugin
kabot plugins scaffold --target meta_bridge

# Remove plugin
kabot plugins remove --target my_plugin --yes

Update safety:

• Plugin updates use rollback protection.
• If update fails, previous plugin version is automatically restored.

Auth Parity Diagnostics

Use this command to validate OAuth/API handler parity across providers and aliases:

kabot auth parity

Meta Threads and Instagram Integrations

Kabot now supports Meta outbound actions and verified webhook ingress:

• Outbound tool: meta_graph (Threads create/publish, Instagram media create/publish)
• Verified webhook routes: GET /webhooks/meta and POST /webhooks/meta
• Signature validation: X-Hub-Signature-256 with app secret

See full setup and examples in docs/integrations/meta-threads-instagram.md.

Freedom Mode (Trusted Environment)

If you want "do anything" behavior for private/trusted deployments:

• Setup wizard:
  • kabot config
  • Tools & Sandbox
  • Enable Freedom mode

This mode:

• enables exec auto approval,
• disables HTTP target guard restrictions for web_fetch,
• keeps defaults available to switch back to secure mode.

---

🏗️ Architecture

Kabot operates on a Gateway-Agent model, decoupling the "brain" from the "body".

Telegram / Discord / Slack / WhatsApp / CLI
               │
               ▼
┌───────────────────────────────┐
│            Gateway            │
│       (Control Plane)         │
│   localhost:<gateway.port>    │
│   (Event Bus + Adapters)      │
└──────────────┬────────────────┘
               │
               ├─ Agent Loop (Reasoning Engine)
               │   ├─ Planner
               │   ├─ Tool Executor
               │   └─ Critic
               │
               ├─ Hybrid Memory (SQLite + Vector)
               │   ├─ Short Term (Context Window)
               │   └─ Long Term (ChromaDB)
               │
               ├─ Cron Service (Scheduling)
               │   └─ Persistent Job Queue
               │
               └─ Subagent Registry (Background Tasks)

Key Subsystems

1. Gateway (Control Plane)

The central nervous system. It normalizes all incoming messages (regardless of platform) into a standard MsgContext object. It handles routing, rate limiting, and session affinity.

2. Agent Loop (The Brain)

The core execution engine found in kabot/agent/loop.py. It implements a ReAct (Reason + Act) loop:

1. Observe: Read user input + memory.
2. Reason: Generate a thought process (internal monologue).
3. Act: Execute a tool (File IO, Web Search, Code Execution).
4. Reflect: Analyze tool output.
5. Repeat: Until the task is done.

Recent runtime hardening added:

• stronger turn categorization (chat, action, contextual_action, command)
• continuity resolution that prefers recent answer/tool evidence over weak parser guesses
• unified completion evidence so "done" claims are checked against real artifact/delivery proof

3. MCP Session Runtime

Located in kabot/mcp/. This layer lets Kabot attach MCP servers per session, discover real tools/resources/prompts, and expose them through the runtime without hallucinating availability.

Key properties:

• Session-scoped: MCP capabilities are attached to a session, not globally improvised.
• Python-native: Kabot itself does not need Node.js just to act as the MCP client.
• Grounded: tool names are namespaced (mcp.<server>.<tool>) and only available when the server is actually configured and attached.

4. Hybrid Memory

Located in kabot/memory/. It solves the "context window limit" problem.

• Vector Store: Semantic search for fuzzy concepts ("What did we discuss about architecture?").
• SQL Store: Exact matching for facts ("What is the API key for Stripe?").
• Summarizer: Automatically condenses old conversation turns into summaries to save tokens.

5. Doctor (Self-Healing)

Located in kabot/core/doctor.py. A diagnostic engine that runs on startup.

• Checks database integrity.
• Validates API keys.
• Verifies Python environment dependencies.
• Auto-Fix: Can automatically reinstall missing pip packages or rebuild corrupted config files.
• Agent Smoke Matrix: kabot doctor smoke-agent runs multilingual temporal/filesystem smoke probes and can enforce latency gates.

Smoke examples:

# Default multilingual smoke probes
kabot doctor smoke-agent

# JSON output + latency gates for fast one-shot flows
kabot doctor smoke-agent --smoke-json \
  --smoke-max-context-build-ms 1000 \
  --smoke-max-first-response-ms 1000

# Skill-focused smoke in multiple locales
kabot doctor smoke-agent \
  --smoke-skill weather \
  --smoke-skill-locales en,id,zh,ja,th

# Add a local Python MCP echo verification
kabot doctor smoke-agent --smoke-mcp-local-echo

---

🤖 Supported Models

Kabot's ModelRegistry abstracts away the differences between providers. You can switch models instantly via the /switch command without restarting.

Commercial Models (Cloud)

Provider	Models	Best For	Pricing
Anthropic	claude-3-5-sonnet, claude-3-opus, haiku	🥇 Coding & Reasoning	$$$
OpenAI	gpt-4o, gpt-4-turbo, o1-preview, o1-mini	🥈 General Logic	$$$
Google	gemini-1.5-pro, gemini-1.5-flash	🥉 Huge Context (2M)	$
DeepSeek	deepseek-chat, deepseek-coder	💸 Cost Performance	¢
Groq	llama3-70b, mixtral-8x7b	⚡ Instant Speed (500t/s)	🆓

Local Models (Offline)

Kabot supports Ollama and LM Studio out of the box.

• Ollama: llama3, mistral, qwen2.5-coder
• Configuration: Point api_base to http://localhost:11434.

---

⚙️ Configuration Reference

Configuration is stored in config.json in your workspace root. You can edit this manually or use kabot config.

Runtime dictionaries stay outside config.json so the main config stays small. Example: learned weather aliases are written to ~/.kabot/weather_aliases.json after successful native-script weather resolutions such as 東京 -> Tokyo.

1. Telegram Setup

Get Token: Talk to @BotFather on Telegram.

{
  "channels": {
    "telegram": {
      "enabled": true,
      "bot_token": "1234567890:ABC-DefGhIjKlMnOpQrStUvWxYz",
      "allowed_users": [12345678]  // Your User ID (get via @userinfobot)
    }
  }
}

2. Discord Setup

Get Token: Discord Developer Portal. Privileged Intents: Enable "Message Content Intent".

{
  "channels": {
    "discord": {
      "enabled": true,
      "bot_token": "MTA5...",
      "allowed_users": ["YOUR_DISCORD_USER_ID"]
    }
  }
}

3. LLM Setup (Anthropic Example)

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-3-5-sonnet-20240620",
    "api_key": "sk-ant-...",
    "temperature": 0.7,
    "max_tokens": 4096
  }
}

---

⚡ Slash Commands & Directives

Control Kabot's behavior directly from the chat.

System Commands:

• /help - Show available commands.
• /status - Check CPU, RAM, and Agent health.
• /switch <model> - Change the active LLM (e.g., /switch gpt4).
• /doctor - Run self-diagnostics and auto-fix config issues.
• /update - Update Kabot to the latest version (git pull + restart).
• /restart - Restart the agent process.
• /clip <text> - Copy text to the host clipboard (Windows/WSL).
• /sysinfo - Show detailed system information.

Directives (Power User Tags): Unlock hidden capabilities by adding these tags to your message.

• /think - Chain of Thought: Forces the agent to output its reasoning process before acting. Highly recommended for complex coding tasks.
• /verbose - Debug Mode: Shows full tool outputs and token usage stats.
• /elevated - Admin Mode: Bypasses "Are you sure?" confirmations for file edits and shell commands.
• /json - Forces the final response to be valid JSON.
• /notools - Prevents the agent from using any tools (pure chat).

---

🎛️ Model Management Tutorial

Click to expand

Complete guide for switching models, setting up OAuth, and managing multiple AI providers.

Quick Start: Set OpenAI as Default

Method 1: Via CLI (Permanent)

# Set default model globally
kabot models set openai/gpt-4o
kabot models set gpt-4o  # Short form

# Verify the change
kabot models list --current

Method 2: Via Chat Commands (Session)

# In Telegram/Discord/WhatsApp chat
/switch openai/gpt-4o
/switch gpt-4o
/switch  # Check current model

OAuth Setup for OpenAI (ChatGPT Subscription)

Step 1: Run Setup Wizard

kabot config

Step 2: Navigate to OAuth Setup

→ Model / Auth (Providers, Keys, OAuth)
→ Provider Login (Setup API Keys/OAuth)
→ OpenAI - GPT-4o, o1-preview, etc.
→ Browser Login (OAuth) - ChatGPT subscription login

Step 3: Complete Browser Authentication

• Browser opens automatically for OAuth flow
• Login with your ChatGPT account credentials
• Grant permissions when prompted
• Return to terminal when complete

Step 4: Set Default Model

→ Select Default Model (Browse Registry)
→ Filter models by provider: openai
→ Select: gpt-4o (Recommended)

Troubleshooting OAuth:

# If OAuth fails, try manual setup
kabot config
→ Model / Auth → Provider Login → OpenAI → Manual Setup

# Check OAuth token status
kabot doctor  # Validates all credentials

Bot Commands Reference

Model Switching Commands:

# Switch model for current chat session
/switch openai/gpt-4o          # OpenAI GPT-4o
/switch anthropic/claude-sonnet-4-5  # Claude Sonnet
/switch groq/llama-3.1-70b     # Groq Llama (fast)
/switch deepseek/deepseek-coder # DeepSeek Coder

# Per-message model override (doesn't change default)
/model gpt-4o Explain quantum computing
/model groq/llama-3.1-8b Quick question about Python

Model Information Commands:

# List all available models
/models list

# Show current model
/switch

# Model usage statistics
/usage
/usage --days 7
/usage --provider openai

Configuration Commands:

# Set configuration values via chat
/config set agents.defaults.model "openai/gpt-4o"
/config get agents.defaults.model
/config list providers

Multi-Provider Setup

Supported Providers:

Provider	Setup Method	Best For	Cost
OpenAI	OAuth/API Key	General purpose, coding	$$$
Anthropic	API Key	Complex reasoning, analysis	$$$
Groq	API Key	Fast responses (500+ tok/s)	🆓
DeepSeek	API Key	Code generation, math	¢
Google	API Key	Large context (2M tokens)	$
OpenRouter	API Key	100+ models via gateway	$

Configuration Example:

{
  "providers": {
    "openai": {
      "profiles": {
        "default": {
          "oauthToken": "eyJhbGciOiJSUzI1NiIs...",
          "tokenType": "oauth"
        }
      },
      "activeProfile": "default",
      "fallbacks": ["groq/llama-3.1-70b"]
    },
    "groq": {
      "apiKey": "gsk_...",
      "fallbacks": []
    },
    "anthropic": {
      "apiKey": "sk-ant-...",
      "fallbacks": ["openai/gpt-4o"]
    }
  }
}

Use Case Optimization

Task-Specific Model Selection:

# Coding tasks → DeepSeek Coder
/switch deepseek/deepseek-coder
# "Write a Python web scraper"

# Fast responses → Groq
/switch groq/llama-3.1-8b
# "What's 2+2?"

# Complex analysis → Claude
/switch anthropic/claude-opus-4-5
# "Analyze this business strategy document"

# Creative writing → GPT-4o
/switch openai/gpt-4o
# "Write a short story about AI"

Cost Optimization Strategy:

# Development/Testing (Free/Cheap)
/switch groq/llama-3.1-8b        # Free tier
/switch deepseek/deepseek-chat    # Very cheap

# Production (Premium)
/switch openai/gpt-4o            # High quality
/switch anthropic/claude-opus-4-5 # Best reasoning

Advanced Configuration

Fallback Chain Setup:

{
  "agents": {
    "defaults": {
      "model": "openai/gpt-4o",
      "fallbacks": [
        "anthropic/claude-sonnet-4-5",
        "groq/llama-3.1-70b"
      ]
    }
  }
}

Per-Agent Model Assignment:

{
  "agents": {
    "list": [
      {
        "id": "coding",
        "model": "deepseek/deepseek-coder",
        "workspace": "~/code"
      },
      {
        "id": "writing",
        "model": "openai/gpt-4o",
        "workspace": "~/docs"
      },
      {
        "id": "quick",
        "model": "groq/llama-3.1-8b",
        "workspace": "~/temp"
      }
    ],
    "bindings": [
      {"agent_id": "coding", "channel": "telegram", "chat_id": "coding_chat"},
      {"agent_id": "writing", "channel": "discord"},
      {"agent_id": "quick", "channel": "telegram", "chat_id": "quick_chat"}
    ]
  }
}

CLI Model Management

List and Discovery:

# List all available models
kabot models list

# Filter by provider
kabot models list --provider openai
kabot models list --provider anthropic

# Show premium models only
kabot models list --premium

# Get detailed model info
kabot models info gpt-4o
kabot models info claude-sonnet-4-5

# Scan for new models
kabot models scan

Model Configuration:

# Set primary model
kabot models set openai/gpt-4o

# Set with fallbacks
kabot models set anthropic/claude-sonnet-4-5 --fallback groq/llama-3.1-70b

# Reset to default
kabot models reset

Troubleshooting

Common Issues:

1. "No API key configured" Error:

# Check provider configuration
kabot doctor

# Check deterministic routing guard matrix
kabot doctor routing

# Verify OAuth token
kabot config
→ Model / Auth → Provider Login → OpenAI → Check Status

# Manual API key setup
export OPENAI_API_KEY="sk-..."

2. Model Not Found:

# Update model registry
kabot models scan

# Check available models
kabot models list --provider openai

# Use full model name
/switch openai/gpt-4o  # Not just "gpt-4o"

3. OAuth Token Expired:

# Re-authenticate
kabot config
→ Model / Auth → Provider Login → OpenAI → Browser Login

# Check token status
kabot auth status openai

4. Unicode/Emoji Display Issues (Windows):

# Use Windows Terminal or PowerShell
# Or set environment variables:
set PYTHONIOENCODING=utf-8
setx PYTHONIOENCODING utf-8  # Permanent

5. Provider Priority Issues:

# Check current provider matching
kabot models list --current

# Force specific provider
/switch openai/gpt-4o  # Explicit provider prefix

# Clear conflicting API keys
kabot config
→ Model / Auth → Remove unused providers

Best Practices

1. Default Setup Recommendation:

• Primary: OpenAI (OAuth) for general use
• Coding: DeepSeek for programming tasks
• Fast: Groq for quick responses
• Backup: Anthropic for complex reasoning

2. Security:

• Use OAuth when available (no API key exposure)
• Store API keys in environment variables
• Use allowed_users for public channels

3. Cost Management:

• Start with free tiers (Groq, DeepSeek free tier)
• Use cheaper models for testing/development
• Reserve premium models for production

4. Performance:

• Use Groq for speed-critical applications
• Use Claude/GPT-4o for quality-critical tasks
• Set appropriate fallback chains

---

🔒 Security

Kabot is effectively a remote shell wrapped in an LLM. Security is paramount.

Trust Model

• Default: Single-user, trusted mode. The configured user has full access to the file system and shell.
• Allowlisting: You MUST configure allowed_users in config.json for public channels (Telegram/Discord). Messages from unknown users are logged but ignored.

Docker Sandboxing (Recommended)

For maximum security, especially if you plan to let Kabot execute code freely, run it inside Docker.

# Build the image
docker build -t kabot .

# Run with volume mapping
docker run -d \
  --name kabot \
  --restart unless-stopped \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config.json:/app/config.json \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  kabot

Because Kabot is "stateful" (SQLite DB), mapping the /data volume is critical.

---

🤝 Development & Contributing

We welcome contributions! Kabot is open-source and community-driven.

Development Setup:

1. Fork the repository.
2. Install dependencies: pip install -r requirements.txt && pip install -r requirements-dev.txt
3. Run tests: pytest tests/
4. Run linter: ruff check .

Branching Strategy:

• main: Stable releases.
• dev: Active development branch.

Please adhere to the coding style (Black/Ruff) and include tests for new features.

---

📜 Star History

---

🙌 Community

Join the discussion, get support, or show off your subagents.

• GitHub Issues for bug reports.
• Telegram Group for live support.
• Discussions for feature requests.

Special thanks to the open-source community and projects like Kabot that inspired our resilience architecture.

---

Built with ❤️ by @kaivyy