Xun

Xun is a lightweight LLM agent runtime. The core is under 5000 lines of Python (src/xun/*.py), yet it ships with tools, commands, a display layer, an extension system, and several session entrypoints. Run it as a whole, or take only the parts you need.

from xun import setup_agent, interactive_session

def weather(city: str) -> str:
    """Query the weather for a given city."""
    return f"Sunny in {city}"

agent = setup_agent(tools=[weather])
interactive_session(agent, task="What is the weather in Paris?")

Key Features

Capability	Description	See
Execution loop and structured output	Multi-round tool calling until convergence; a pydantic model can constrain the final output	Structured Output
Functions as tools	A plain function plus type annotations and a docstring becomes a tool; 33 built-in tools cover the filesystem, commands, the browser, retrieval, and diagnostics	Tool Setup
Display layer	One event stream can be sent to the console, to the web, or to a custom display	Display Extensions
Sub-agents	Built-in derivation policies and a background derivation tool let a parent agent dispatch tasks in parallel	Sub-agent Derivation
Session compaction	Old tool results are reclaimed first; summarization kicks in only if the limit is still exceeded — a two-level fallback	Config
Lifecycle hooks	17 hook points with editable arguments that can take over execution	Hooks
Chained cancellation	Cancelling a parent agent cascades automatically to its sub-agents	Chained Cancellation
Session entrypoints	Five entrypoints: xun / xuns / xunc / xunx / xune	Built-in Session Entrypoints
Extension system	Files dropped into $XUN_HOME/extensions/ take effect at every agent initialization	Plugin Development Guide

Use Cases

• Command-line assistant: xun works interactively in the current directory — reading and writing files, running commands, opening a browser.
• Self-hosted web service: xuns serves a browser UI with a file panel; xunc puts it inside a Docker container; xunx serves many users through one gateway.
• Embedded in your own program: drive the Agent API directly to orchestrate a single call, a batch job, or a custom tool chain, without pulling in any entrypoint layer.
• Capabilities without touching the main program: MCP, Skills, usage accounting, and the like arrive as extensions; the core stays unchanged.

Design Characteristics

• Synchronous API. The bottleneck is the model call itself; async would only add mental overhead. The framework still runs concurrently with threads and semaphores internally, while callers write code that reads top to bottom.
• Type-State. Agent takes its lifecycle state as a type parameter: execute() cannot be called on Uninit, and the prompt can no longer be changed once the state is Final — this class of mistake is caught by static checking. See Lifecycle.
• Event-driven display layer. The agent never prints; it only emits events. The display side owns rendering and interaction, so the same agent can run quietly inside a script or be pushed to a browser.
• Configure once, inherit everywhere. The global config.json is loaded once and cloned per agent; when deriving a sub-agent you can choose to share the workspace, the display layer, and the cancellation chain.
• Extensions are trusted code. An extension runs with full process privileges at import time, as simple and direct as a shell rc file; a load failure raises a warning and never blocks startup.

Structure Overview

flowchart TD
    subgraph entry["Session Entrypoints"]
        CLI["xun / xuns"]
        BOX["xunc / xunx"]
        EXT["xune"]
    end

    subgraph core["Core Agent"]
        CONV["Conversation: session and system prompt"]
        TB["ToolBox"]
        DISP["Display layer"]
        CFG["AgentConfig"]
        HK["Hooks"]
        ST["AgentState container"]
    end

    LLM["OpenAI-compatible model service"]

    entry --> core
    core --> LLM
    LLM --> core
    TB --> TOOLS["Built-in tools / custom functions"]
    DISP --> OUT["Console / Web / custom"]
    EXT -."injected at initialization".-> core

Extensions never modify the entrypoint programs. They attach tools, commands, hooks, and prompt sections to the core objects at each agent's initialize().

Documentation Structure

1. Installation: three paths — pip, source, and Docker.
2. Built-in Session Entrypoints: arguments and use cases for the five commands.
3. API Guide: initialization, configuration, lifecycle, display, structured tools, and more.
4. Plugin Development Guide: how extensions and the API divide the work, the loading mechanism, and the extension points.
5. Changelog.

Reading the code is faster

demo.ipynb in the repository root covers every point of the API part of these docs in ten short sections, and README.md is the shortest possible getting-started guide.