xiaoO

English | 中文

Open-source intelligence hub for AgentOS.

What is xiaoO?

xiaoO is the intelligence hub of AgentOS. It provides a self-governing agent runtime for system management, agent orchestration, tool execution, memory, context compression, and multi-channel access.

At its core, xiaoO turns the operating system into a practical home for agents: files, shell commands, Git, web access, LSP diagnostics, skills, hooks, channels, and runtime telemetry are exposed through one coordinated agent loop.

The runtime also includes a layered memory and adaptive context-compression system, so long conversations, tool-heavy tasks, and multi-agent collaboration can remain stable without being overwhelmed by raw history growth.

Key Features

• Agent runtime hub: CLI, TUI, daemon, HTTP API, and channel integrations.
• Full tool suite: file operations, shell execution, Git, web search/browse, patch application, sub-agents, and extensible tool manifests.
• Adaptive context management: token-budget tracking, configured compaction, forced recovery after context-limit errors, and prefix-cache telemetry.
• Streaming reasoning: provider reasoning/thinking deltas can be surfaced while the model works.
• Reasoning-effort tiers: switch among off, high, and max; the TUI cycles them with Ctrl+T.
• Session management: save and resume long-running work.
• LSP diagnostics: inline errors and warnings after edits through servers such as rust-analyzer, pyright, typescript-language-server, gopls, and clangd.
• Skills system: installable instruction packs loaded from local directories or Git sources.
• Hook and plugin system: lifecycle hook points around agent creation, LLM calls, and tool calls for audit, policy, traceability, and custom extensions.
• Observability: live token/cost tracking and trace storage through noop, stdout, or moirai-sqlite.
• Scheduled and triggered tasks: long-running automation workflows can be attached to the runtime.
• Localized UI: a clean terminal interface designed for daily agent work.

Prerequisites

• Rust toolchain with Cargo installed.
• A supported LLM provider account or a local model endpoint.
• Provider credentials available through environment variables or the xiaoO configuration file.

Installation From Source

git clone https://gitcode.com/openeuler/xiaoO.git
cd xiaoO
cargo install --path apps/xiaoo-app

This installs the application binaries into ~/.cargo/bin and attempts to install builtin skills. Make sure ~/.cargo/bin is in your PATH.

Note: cargo build does NOT install skills. Only cargo install triggers skill installation.

Installation Behavior:

• First attempts to install builtin skills to system-level directory: /usr/lib/.xiaoo/skills/ (requires root privileges)
• If system-level installation fails (e.g., permission denied), automatically falls back to user-level directory: ~/.xiaoo/skills/
• Builtin skills include xiaoo-guardian (security policy enforcement) and other built-in capabilities
• Without these skills, security features may be unavailable.

For system-wide installation (recommended for multi-user environments):

• Run cargo install with root privileges: sudo cargo install --path apps/xiaoo-app

Uninstallation

# Uninstall binaries
cargo uninstall xiaoo-app

# Remove the guardian skill (system level requires root)
sudo rm -rf /usr/lib/.xiaoo/skills/xiaoo-guardian

Skill Directory Priority (Four Levels - Runtime Search Only)

./build.sh --release

The build wrapper can install the audit_agent hooker, which audits tool execution for risky operations. Plugin installation details are available in docs/plugins.md.

Quick Start

Create ~/.config/xiaoo/config.toml:

[llm]
provider = "openrouter"              # openai, anthropic, ollama, openrouter, deepseek, zai, minimax, kimi, minimax-coding-plan, kimi-coding-plan, ...
model = "z-ai/glm-5"
api_key_env = "OPENROUTER_API_KEY"   # Read the API key from this environment variable
max_tokens = 128000                  # Optional, max output tokens per response
context_window = 128000              # Optional, explicit total context budget override
reasoning_effort = "off"             # Optional: off, high, or max

# Predefined subagent roles (CLI/TUI/Daemon all support) ⭐
# Note: tools configuration supports two formats - see docs/config_file_guide.md
[subagent.code_reviewer]
description = "Code review specialist"
prompt = "You are a code review specialist focusing on quality and best practices."
max_turns = 5

[subagent.code_reviewer.tools]
bash = true
read = true
glob = true
grep = true

[trace]
storage_backend = "moirai-sqlite"    # noop, stdout, or moirai-sqlite
db_path = "~/.xiaoo/traces.db"       # Used when storage_backend is moirai-sqlite

Set your provider credential:

export OPENROUTER_API_KEY="sk-or-..."

Setup custom api url for local LLM: (e.g. entry point is http://localhost:8080/v1/chat/completions)

[llm]
provider = "local"
model = "deepseek-v4-flash"
api_base = "http://localhost:8080"
api_key_env = "LLM_API_KEY"

Run xiaoO:

# Terminal UI
xiaoo-tui

# Single-shot CLI
xiaoo run -p "Count the characters in hello world"

Example CLI output:

"hello world" has 11 characters.

Configuration Documentation:

• General Configuration Guide - Shared configuration for all modes (llm, subagent, skills, etc.)
• CLI Configuration - CLI basic usage and supported configuration
• TUI Configuration - TUI-specific configuration (remote, LSP, agent roles)
• Daemon Configuration - Daemon-specific configuration (channels, HTTP API)

Context Window

[llm].context_window is optional. It sets an explicit total context budget used by token budgeting and context compression. xiaoO resolves the effective value in this order:

1. Explicit user config: [llm].context_window
2. Dynamic model lookup, currently supported for gemini, anthropic, and ollama
3. Local fallback defaults:
   • OpenAI-compatible, Ollama, and Zhipu families default to 128000
   • Anthropic defaults to 200000
   • Gemini defaults to 1000000

More details are available in Memory & Context Compression.

Reasoning Effort

[llm].reasoning_effort controls provider-side thinking or reasoning where supported.

Value	Meaning	TUI color
off	Disable extra reasoning controls where supported	Gray
high	Use a stronger reasoning/thinking setting	Yellow
max	Use the strongest reasoning/thinking setting	Red

The TUI status bar shows the current value as Think off/high/max. Press Ctrl+T to cycle off -> high -> max -> off for the next turn. In CLI mode, use:

xiaoo run --reasoning-effort high -p "Explain this repository"

Provider mapping is best-effort. OpenAI-compatible providers receive reasoning_effort for high and max; Anthropic receives thinking.budget_tokens; Gemini receives thinkingConfig.thinkingBudget; unsupported providers ignore the setting. off omits provider-specific reasoning fields so default requests keep each provider's native behavior.

Skills

xiaoO loads skills from ~/.xiaoo/skills by default. Each skill is a reusable instruction pack backed by SKILL.md or SKILL.toml.

xiaoo skill list
xiaoo skill show <name>
xiaoo skill audit <path>
xiaoo skill install ./my-skill/
xiaoo skill install https://github.com/user/my-skill.git
xiaoo skill remove <name>

See docs/skill_usage.md for the full skill workflow.

Run as a Daemon

xiaoO can run as a daemon and expose a REST API for external systems such as Feishu, Telegram, or custom services.

# Default address: 0.0.0.0:18080
xiaoo-app daemon

# Specify configuration file, host, and port
xiaoo-app daemon --config /path/to/config.toml --host 127.0.0.1 --port 18080

HTTP requests can select an agent role preset by passing agent in the JSON body:

{
  "text": "Review this patch for security issues",
  "channel": "http",
  "sender_id": "demo-user",
  "conversation_id": "demo-conv",
  "agent": "code-reviewer"
}

More daemon configuration details are in docs/daemon_config.md.

More Documentation

• Memory & Context Compression
• Plugin System
• Skill Usage
• Custom Agents
• Remote TUI
• Feishu Deployment
• Telegram Deployment

License

xiaoO is licensed under MulanPSL-2.0.