Xiaoyu 小羽 中文 PyPI

All of the harness.
None of the shell.

A coding agent for the terminal, for CI, or inside your own program. No subscription, no login. Your key, your model.

View source
zsh~/projects/api
$ xy "add type hints to utils.py"
$ git diff | xy "write a commit message"
$ xy --output-format stream-json "summarize this repo"
$ xiaoyu --acp
$ xiaoyu send zhinu-1 "run lint while you're at it"
$ xiaoyu --yolo --no-network
xiaoyu 0.44.0 · model deepseek-v4-pro · sandbox seatbelt
/help /tools /skills /model /mode /plan /tasks /resume
›

Bring your own key. Swap models anytime.

Vendor agents are welded to vendor models. The neutral ones keep adding subscriptions, accounts, and a model you didn't pick. Xiaoyu talks straight to deepseek, moonshot, qwen, zhipu, anthropic, gemini, openai, xai, or any OpenAI-compatible gateway. Set up both and the lists merge.

Confirmations are a setting, not a rule.

Guardrails keep stacking up and get harder to switch off. Xiaoyu gives you the switch: --yolo runs with no prompts, no pauses, no slowdown, while the sandbox and the irreversible-command guard stay on.

Every team will end up with its own coding agent.

One that knows your codebase, your rules, your toolchain, your approvals. Nobody else can build that. Xiaoyu is the kernel underneath: tools, sandbox, approvals, context management, MCP, and skills, ready-made. You plug in the rest.

You set the leash

Shift-Tab cycles modes; /mode or --mode sets one. --yolo is its own switch.

  1. default

    Asks before every write and every command.

  2. auto

    Edits in the workspace and sandboxed commands just run. Dangerous commands, escalation, and writes outside still ask.

  3. plan

    Read-only. You get a plan and approve it before anything runs.

  4. --yolo

    Everything allowed, straight through. Built for unattended runs, CI, and containers.

Four lines --yolo never crosses

  • bash stays in the kernel sandbox: workspace, temp, and build caches only
  • deny rules are never bypassed
  • rm -rf /, fork bombs, and the like never run in any mode
  • Plan approval still asks; cross-session messages are off by default. Add --no-network to cut the wire

What it does

Kernel sandbox

bash runs inside macOS Seatbelt or Linux bubblewrap and writes only to the workspace, temp, and build caches. auto mode trusts the sandbox, not the model; no sandbox, and it degrades on its own.

Background tasks

run_in_background returns at once and notifies when done. monitor tails logs or CI, one event per line, rate-limited.

Sessions that don't snap

Layered context reclaim when the window fills. Ctrl-C and pick up where you were. xiaoyu resume brings old sessions back. Per-turn usage snapshots land on disk; xiaoyu sessions digest sums the ledger.

Right protocol per model

Chat completions, Responses, or Anthropic Messages, picked by model, with reasoning round-trips and prompt caching. Rate limits retry; a fallback chain swaps models and keeps going.

Hundreds of MCP tools, zero context tax

MCP tools load by retrieval, not by schema dump: search_tool to find, use_tool to call. Local stdio and remote Streamable HTTP servers both mount. OSV checks and rug-pull isolation included.

Finish on a schema

--output-schema schema.json ends the turn with an object that matches your JSON Schema, delivered in the output field. One mechanism across the CLI, serve, and embedding, so scripts, CI, and orchestrators consume it directly.

Paced budgets, tunable depth

A soft token budget: the model gets a countdown at 50 / 80 / 95% and wraps up cleanly before the line instead of being cut off. At the turn cap it can ask for an extension, reason on record. /effort sets reasoning depth per session and per sub-agent, translated for each of the three protocols.

Sees images, keeps long output

One-shot runs take --image shot.png (repeatable) or --paste from the clipboard. If the current model can't see images, a vision model reads them into text first. Oversized tool output keeps head and tail; recall fetches the middle by short id without spending context.

Plugins in one line

xiaoyu plugin add aws/agent-toolkit-for-aws installs skills and MCP declarations together. Speaks the agent-plugins.org bundle format, so community bundles just work.

Multi-agent weaving

Zhinu is a guild of Weavers; Xiaoyu is one of them: a weaver (the agent) who brings her own loom (the platform). One file in agents/*.toml is one more sub-agent, with worktree isolation and resumable runs.

七襄Qixiang · Parallel-Weave

Parallel weave: one template, N inputs, many weavers at once. Results come back in input order, with resume handles.

斗巧Douqiao · Contest-Weave

Contest weave: several weavers take the same task blind. models lets each vendor weave one. A judge picks the best.

宸枢Chenshu · Sovereign-Weave

Sovereign weave: one planner splits a big job into non-overlapping missions, workers run in parallel on their own worktree branches, and reviewed work merges back to main.

Keep your workbench

Xiaoyu is a kernel. It runs in the terminal, and it runs here.

Xiaoyu inside Zed; the bottom bar switches model and mode (cropped)

Zed

Xiaoyu speaks ACP (Agent Client Protocol) natively; xiaoyu acp and --acp are equivalent. Add it to Zed as a custom agent with one command and use it from the side panel, on your own key and model. An ACP registry listing is in review; once merged, it shows up in the agent picker.

# launch command for any ACP client
uvx xiaoyu-agent --acp
A KiroCrew session running on Xiaoyu (cropped)

KiroCrew beta

Xiaoyu Desk (羽案) swaps KiroCrew's kiro-cli for Xiaoyu. No patch, no fork: it uses KiroCrew's own KIROCREW_KIRO_BIN override and ships a doctor check. Known limits: only the agent the gateway started with, and Xiaoyu's own modes aren't reachable from KiroCrew.

pip install xiaoyu-desk
KIROCREW_KIRO_BIN=$(which xiaoyu-desk-acp) kirocrew gateway
Xiaoyu Desk source and known limitations

Your own program

import xiaoyu is the public API: the top-level exports (Agent, AsyncAgent, Allow, Deny, event types) follow semver, and breaking changes get a one-minor deprecation window. Run the agent as an engine inside your process with approval callbacks, event streams, and session reuse. Other languages use --wire, JSON-RPC over stdio.

import xiaoyu
agent = xiaoyu.Agent(config, approver=approve)
result = xiaoyu.measured_send(agent, "Translate the install section")

Plug into what you already run

One key is enough. A gateway works too.

  • DEEPSEEK_API_KEY
  • MOONSHOT_API_KEY
  • DASHSCOPE_API_KEY
  • ZHIPU_API_KEY
  • ANTHROPIC_API_KEY
  • GEMINI_API_KEY
  • OPENAI_API_KEY
  • XAI_API_KEY
  • XIAOYU_BASE_URL

HTTP API

xiaoyu serve gives n8n, Dify, or your own scheduler a handle: async submit, status polling, event cursors, OpenAPI schema generated from code. Register agents and pin their versions, cap each session with a hard token budget, and let the server pick sessions back up after a restart.

Browse the API reference →

MCP server

The same server mounts an agent-level MCP server at /mcp. LangChain and LangGraph connect through the official adapters.

Three lines to install

# completion / history / paste folding / images / diff highlighting
pip install "xiaoyu-agent[tui]"
# wizard for your key; --show prints the config, never the key
xiaoyu config
# start chatting; xy is the short alias
xiaoyu
Hit Enter after install and this is what you get.

Windows, macOS, Linux. MIT, source on GitHub.