wing-agent

Towards general agent runtime.

中文文档

⚠️ Experimental — Expect breaking changes until v1.0.

Why wing?

No magic in your context. We never inject hidden system prompts. You see exactly what the model sees — your system prompt, your tools, your conversation. Nothing more.

Maximum cache hit rate. We commit to the theoretical maximum prompt caching. Beyond compaction, we never break your cache prefix.

Minimal tool schemas. Our built-in tools use the simplest possible schemas. Your context window starts with under 2K tokens of tool overhead — not 10K.

Quick Start

pip install wing-agent
wing

On first run, wing creates a config template at ~/.wing/core/config.yaml and exits. Open it and fill in your provider, key, and model:

providers:
  - name: default
    protocol: openai                         # openai | anthropic
    base_url: "https://your-api-endpoint/v1" # ← your provider
    api_key: "sk-xxx"                        # ← your key

agents:
  - name: default
    model: "gpt-4o"                          # ← your model
    default: true
    tools: [Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, TodoWrite, Explorer]

Then start wing:

wing stop    # stop the gateway if it was already running
wing         # start fresh

Note: The gateway loads config at startup. After editing config.yaml, run /reload in the TUI (or wing stop then wing) to pick up changes.

Configuration

Backend config: ~/.wing/core/config.yaml — generated on first run, fully annotated (see wing/default_config.py for the template). Frontend config: ~/.wing/tui/config.yaml

Built-in Tools

Tool	Description
Bash	Execute shell commands with safety review
Read	Read file contents with line range
Write	Create or overwrite files
Edit	Surgical string replacement in files
Glob	Find files by pattern
Grep	Search file contents with regex
AskUserQuestion	Ask the user a question
TodoWrite	Track task progress
Explorer	Autonomous code exploration sub-agent (blocking or background)
BetterEdit	Anchored [upto] edits (experimental)

Custom tools: docs/en/custom-tools.md

Magic Commands

Type / in the TUI to see available commands.

Full reference: docs/en/magic-commands.md

Headless mode (stdio)

wing also runs headless with a Claude Code compatible stdio protocol — alias wing as claude to plug into external orchestrators, or drive it from scripts:

wing -p "list the files in this directory"                    # text (default): final result only
wing -p "list files" --output-format json                     # single result JSON object
wing -p "list files" --output-format stream-json              # real-time NDJSON stream

Useful flags: -m/--model, -r/--resume, --system-prompt, --append-system-prompt, --max-turns, --effort, --input-format, --yolo. Unknown --xxx flags are ignored for Claude compatibility.

Documentation

Document	English	中文
Custom Tools	docs/en/custom-tools.md	docs/zh/custom-tools.md
Magic Commands	docs/en/magic-commands.md	docs/zh/magic-commands.md

Developing

Start with AGENTS.md (high-density project overview). For mechanism-level deep dives (data flow, full HTTP API, glossary), see docs/dev/ (中文).

License

Apache-2.0