Install

uv tool install uclone-x        # or: pipx install uclone-x
ucx --help

To try it without installing anything permanently:

uvx --from uclone-x ucx --help

Provider SDKs and the ontology stack are optional extras — install what you use:

pip install "uclone-x[llm]"        # Gemini, Claude, OpenAI SDKs
pip install "uclone-x[ontology]"   # LinkML, rdflib, networkx
pip install "uclone-x[all]"

Python 3.11 or newer is required.

First run

Configure at least one provider, then start a chat session:

cp .env.example .env    # then fill in one API key, or point at a local Ollama
ucx run

ucx run is an interactive terminal REPL with streaming responses, tool calls and slash commands. A local model needs no API key at all:

OLLAMA_FAST_BASE_URL=http://localhost:11434/v1 OLLAMA_FAST_MODEL=qwen3:8b ucx run

The developer dashboard — an agent and event-bus explorer — is a single command:

ucx dev ui

What UClone-X is

An agent runtime built around a non-blocking reactive event loop rather than a blocking request/response cycle. Agents yield when idle and wake on tool returns, interrupts or messages from other agents. The same event bus carries single-agent execution and multi-agent collaboration on one machine, without an external broker.

• Event-driven agent core — a six-stage reactive state machine over an in-memory priority event bus with backpressure policies and immutable event envelopes.
• LLM-agnostic — Gemini, Claude, OpenAI and local models (Ollama, vLLM) behind one interface, with schema translation and fallback routing.
• Dynamic personas and sub-agents — agents create, supervise and terminate child agents with their own prompts and strict tool boundaries.
• Pluggable sandboxing — host, workspace, container or WASM isolation selected per tool rather than globally.
• Ontology grounding — LinkML domain schemas and a semantic graph the agent reasons against instead of inventing structure per prompt.
• OpenTelemetry native — traces, metrics and OTLP export built in.

Implementation status

UClone-X is pre-1.0 and under active development. Read this section before depending on it.

Documentation

• Architecture overview
• Event-driven agent core
• Core principles P0–P9 — the normative rules every part of the runtime is built against
• Product requirements
• CLI specification
• LLM-agnostic interface
• Dynamic persona and sub-agent interface
• Local collaboration engine
• Sandbox execution
• Ontology architecture
• Skill system
• Code intelligence (AST, LSP, SCIP)
• Telemetry
• A2A protocol specification
• Security threat model

Development

git clone https://github.com/UClone-AI/uclone-x.git
cd uclone-x
uv sync --all-extras
./ucx test check      # ruff format + lint, pyright strict, pytest with branch coverage

./ucx test check is the whole gate: zero ruff findings, zero pyright errors in strict mode, and the test suite at or above 70% branch coverage. A change that does not pass it is not ready.

See CONTRIBUTING.md for how patches reach this repository, and docs/local-development-guide.md for the longer setup walkthrough.

About this repository

This repository is the UClone-X runtime and its documentation. It is published from a private development repository, in periodic snapshots rather than as a mirror of that repository's history. The evaluation suites and multi-agent build tooling used to develop it are not part of the published subset; the runtime detects their absence and degrades cleanly, so ucx eval reports that no evaluation backend is installed rather than failing to start.

License

Apache 2.0 — see LICENSE and NOTICE.