User Guide

CLI Mode

xbot chat runs one-shot agent conversations. Defaults to the current directory as workspace.

# Initialize project context (creates .xbot/ and XBOT.md)
xbot chat /init

# One-shot task in current directory
xbot chat "refactor the database layer"

# Use explicit workspace
xbot chat --workspace /path/to/project "find bugs"

# Use global workspace for non-project tasks
xbot chat --global "research quantum computing"

# Override model for this task
xbot chat --model anthropic/claude-sonnet-4-20250514 "review my code"

REPL Interactive Mode

Rich terminal UI built with Ratatui — streamed responses, persistent sessions, subagent notifications, and runtime model switching.

xbot repl
xbot repl --workspace /path/to/project
xbot repl --global

Backend Service

xbot run starts the always-on AI assistant backend. It simultaneously launches the Gateway HTTP server, heartbeat service, cron scheduler, and all configured channel backends.

xbot run
xbot run --workspace /path/to/project

Built-in Tools

xbot provides 12 built-in tools that agents can invoke autonomously to complete tasks.

MCP Tool Servers

xbot supports MCP (Model Context Protocol) over stdio. Enabled tools register as native tools with mcp_<server>_<tool> naming.

{
  "tools": {
    "mcpServers": {
      "github": {
        "enabled": true,
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": { "GITHUB_TOKEN": "ghp_..." },
        "enabledTools": ["*"],
        "toolTimeout": 30
      },
      "filesystem": {
        "enabled": true,
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
      }
    }
  }
}

Memory System

xbot implements a dual-file persistent memory architecture ensuring important information persists across sessions.

Memory Consolidation

LLM-driven consolidation auto-triggers when context usage reaches ~75%, compressing older memories. Falls back to raw archive mode after 3 LLM consolidation failures.

Explicit Memory

# In REPL or via channel
/memorize Always use tabs for indentation in this project

Skills System

Skills are modular SKILL.md files in skills/<name>/SKILL.md with YAML frontmatter defining triggers and priority.

xbot skills list             # List all skills
xbot skills init my-skill    # Create a custom skill

Built-in Skills

Subagent System

The main agent can spawn background subagents for parallel subtask execution. Subagents default to 3 max concurrent with 100 max iterations each.

Hybrid Model Routing

Main task on a remote frontier API (e.g., OpenAI GPT-4.1), subagents switch to a local model (e.g., Qwen on vLLM) for parallel work — balancing quality and cost.

{
  "agents": {
    "defaults": {
      "model": "openai/gpt-4.1",
      "provider": "openai"
    },
    "subagents": {
      "model": "qwen2.5-coder:7b",
      "provider": "local-vllm",
      "apiBase": "http://127.0.0.1:8001/v1"
    }
  },
  "providers": {
    "openai": { "apiKey": "sk-..." },
    "local-vllm": {
      "apiKey": "",
      "apiBase": "http://127.0.0.1:8001/v1"
    }
  }
}

Provider Configuration

xbot supports 26 LLM providers with automatic model routing — auto-detecting provider from model name prefixes, API key prefixes, or API base URLs.

Cron Scheduling

Three scheduling modes: one-shot (At), interval (Every), and cron expression (Cron) with timezone support. Jobs persist to .xbot/state/cron/jobs.json.

xbot jobs              # List all scheduled jobs

Gateway Endpoints

The Gateway HTTP server started by xbot run listens on 0.0.0.0:18790 by default.

Full Configuration Reference

Config file at ~/.xbot/config.json. All available settings:

API Reference page.