miao：开源 AI 编程智能体，主打上下文效率与可控成本

miao

Your models. Your workflow. Less wasted context.

English | 简体中文

Website · Quick start · Why miao · Guide · Releases · Related projects

miao is an open-source AI coding agent for developers who want to get real work done—and understand what it costs. Work in your terminal, use the models you choose, and let the agent explore a repository, edit code, run commands, and check its work.

miao focuses on the engineering around the model: context efficiency, durable sessions, collaboration, and control over long-running work. Its aim is the same useful result with less waiting and fewer wasted tokens.

See it in action

The terminal and browser captures below use the same illustrative session, imported into the real application without a model request. Captured on 2026-10-04 with miao v0.1.0; the opt-in mini interface is from the current v0.1.1 development build and uses its built-in demo mode.

Choose your provider	Review in the browser

Compact interactive mode · development preview	Review before allowing an edit · development preview

More short, controllable demos: miao on mtty.dev.

Why miao

Choose the model that fits the work

Use multiple providers in one interface, switch models within a session, and configure specialist agents with their own models and permissions. The provider catalog and custom provider configuration let you choose for reasoning quality, speed, or price rather than rebuilding your workflow around one vendor.

Keep long tasks moving—and steer as you go

Add a requirement while the agent is working. V2 saves the input before scheduling execution and brings it into the conversation at a safe provider-turn boundary. Explicit queued inputs wait until the current work would otherwise become idle. You can refine the task without starting another conversation or interrupting every tool call.

Give collaboration its own context

Delegate a scoped task to a specialist subagent and continue that subagent session later. V2 also provides list_sessions and send_message: agents can discover and message other sessions in the same project, subject to permissions. Research and focused investigations can live in their own conversations while the main session keeps the overall objective.

See where your tokens and money go

Per-turn usage, estimated cost, time to first token, and prompt-cache telemetry make performance visible. Context Epochs preserve an immutable system-context baseline and admit changes chronologically, helping keep cache prefixes reusable. Optional output pruning, compaction tuning, cache TTL, and session budgets give you controls for longer tasks.

Cost estimates use configured model rates and provider currency metadata. They are useful for understanding a session; your provider's billing remains authoritative.

Keep a record you can continue and inspect

V2 uses durable prompt admission and an event-backed session history. List, reopen, fork, and export sessions instead of treating each terminal window as a disposable chat. Large tool results are bounded in model context, with full output retained in temporary files when available.

Durable history does not imply automatic execution recovery after a crash: unfinished provider work requires an explicit resume, and arbitrary commands are not guaranteed to run exactly once.

Built for everyday engineering

Try a concrete task: “Find the cause of this failing test, fix it, run the relevant checks, and explain the diff.” Then add a constraint while it works: “Preserve the public API and avoid new runtime dependencies.”

Quick start

Install on macOS or Linux with the bash script, or on Windows from PowerShell:

irm https://mtty.dev/miao/install.ps1 | iex   # Windows: PowerShell 5.1 or 7

Windows terminal rendering is still being verified; see the Windows verification notes.

Windows binaries are currently unsigned.

curl -fsSL https://mtty.dev/miao/install | bash   # redirects to this repo's install script

miao providers login          # choose a provider and connect your account / API key
cd /path/to/project
miao                          # start the terminal UI

Inside the TUI, use ctrl+p for the command palette or ctrl+x m for model selection. Run miao models to inspect available models.

miao run "Explain this repository's architecture and identify its main entry points"
miao web                      # open the browser interface
miao upgrade                  # update the release binary

The installer places the release command at ~/.miao/bin/miao. Start with the guide for configuration, permissions, MCP, LSP, and troubleshooting.

Longer tasks, with limits

The V2 autonomous loop is opt-in. It continues while todos remain open, with iteration and stall guards. A cost budget stops scheduling further provider turns after the estimated session cost reaches the threshold; it is not a hard cap on a provider bill or on a turn already in flight.

Place this in .miao/miao.jsonc for a project or ~/.config/miao/miao.jsonc globally. These settings are optional; see the configuration guide before tuning them.

Remote Control

Use /remote-control in the TUI to configure a self-hosted relay and pair or revoke App/Web devices. The legacy WeChat/QQ connectors and local IM session Router have been removed. See Runtime behavior and relay setup.

Performance work you can inspect

miao includes Rust accelerators and benchmarks against this repository's earlier TypeScript implementation. Selected recorded measurements, on the same machine using release builds and medians:

These are component benchmarks, not end-to-end task speedups or comparisons with today's upstream release. The primitives behind them did not leave with the V1 tools: V2's edit and apply_patch call the same native matching and derivation whenever the addon is loaded, which it is by default, and MIAO_NATIVE=0 falls back to the TypeScript implementations. The addon also backs the opt-in OS sandbox runner, and in-process Git remains a prototype. See the recorded component benchmarks.

Public baseline: startup, memory, idle cost, crash recovery

Measured 2026-10-02 on an Apple M2 with 16 GB RAM, macOS 26.5. Each run launches the compiled TUI in a 160×45 tmux pane in an empty git repository and waits until the prompt renders. The two builds ran alternately, 6 starts and 2 two-minute idle runs each. Other agents were running on the machine (1-minute load average 3.5–12.4), so treat the absolute numbers as an upper bound; the comparison is like for like.

Crash recovery (0.0.31): killing the process with SIGKILL while a bash tool call was running lost no messages; miao -c reopened the session and the next prompt continued it. Three gaps remain: the interrupted tool call still shows as running until the next turn starts, the child process it started keeps running, and nothing resumes automatically.

Idle RSS and idle CPU still miss the Phase 0 targets; see specs/architecture.md.

Status and architecture

miao is pre-1.0. The V1 session runtime and its legacy /session/* routes have been removed, so every shipped client runs the single V2 core. V2 uses Effect services, Location-scoped tools, durable inboxes, event-backed history, and Context Epochs. Local execution coordination is process-local; clustered execution and automatic crash continuation are not implemented.

From V1 to V2

V1 was the session runtime miao inherited from opencode; V2 is miao's rewritten core. The V1 session runtime, its legacy tools, and the /session/*, /permission/*, /question/*, and /sync/* routes have been removed, so all shipped clients run V2. Two compatibility surfaces remain: the database migration layer that reads history written before V2, and the non-session legacy routes still being migrated to /api/*.

See specs/v2/v1-retirement.md and specs/architecture.md.

Use miao for releases, miao-dev for source iteration, and miao-preview for compiled checkout validation. New source features may not yet be in the installed release.

Related projects

Local defaults and optional services

miao runs locally without a miao or OpenCode account. Connect your chosen model provider directly with its API key or supported OAuth method.

• Model metadata comes only from miao's catalog at mtty.dev. The website builds it from public models.dev data and miao-maintained providers (currently Command Code); the runtime does not fall back to models.dev. Builds bundle a snapshot for offline startup. Pin a source with MIAO_MODELS_URL, or select an exact catalog with MIAO_MODELS_PATH.
• Command Code is available as a subscription provider: connect it with miao auth login commandcode (browser-assisted) or CMD_API_KEY, and its models are discovered from the account at runtime.
• Release notes and updates come from oxdingzg/miao releases.
• Session sharing and share-URL imports have been removed. Use miao export / miao import for portable session files; legacy enterprise.url configuration does not enable sharing.
• MIAO has no Console account or organization support. MIAO_CONSOLE_URL only exposes Console OAuth for the OpenCode provider integration; a custom server can specify MIAO_CONSOLE_CLIENT_ID.
• OpenCode Zen / Go remain optional third-party model providers, with their actual OpenCode service names and endpoints.

miao and mtty are separate projects, and each works without the other. Run miao inside an mtty pane and it reports its state (working, waiting for you, done, error) to mtty, which badges the pane, notifies you when the agent needs you, and sends your queued prompt when it goes idle. Outside mtty the report does nothing. miaotty was a personal macOS prototype of that terminal and has been replaced by mtty.

Documentation and development

• Usage guide · 使用指南
• Providers and models · Remote Control
• Why choose miao? — use cases, current state, and direction
• Open-source agent comparison — eight workflows, source evidence, and boundaries
• Release workflow — versions, builds, and publishing
• Runtime design · V2 specifications — session, context, and client contracts

Requires Bun for development:

bun install
bun run dev
# Run checks in the package you changed, for example:
cd packages/miao
bun typecheck

miao is released under the MIT License. See LICENSE.