Metadata-Version: 2.5
Name: wing-agent
Version: 0.5.0
Summary: General-purpose coding agent — Rust TUI/CLI + Python gateway runtime
Project-URL: Homepage, https://github.com/lpdink/wing-agent
Project-URL: Repository, https://github.com/lpdink/wing-agent
Project-URL: Issues, https://github.com/lpdink/wing-agent/issues
Project-URL: Changelog, https://github.com/lpdink/wing-agent/releases
Project-URL: Documentation, https://github.com/lpdink/wing-agent/blob/develop/docs/zh/README.md
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,cli,coding-agent,llm,tui
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: wing-cli==0.5.0
Requires-Dist: wing-gateway==0.5.0
Description-Content-Type: text/markdown

# wing-agent

<p align="center">
  <strong>Towards general agent runtime.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/wing-agent/"><img src="https://img.shields.io/pypi/v/wing-agent" alt="PyPI"></a>
  <a href="https://pypi.org/project/wing-agent/"><img src="https://img.shields.io/pypi/pyversions/wing-agent" alt="Python"></a>
  <a href="https://github.com/lpdink/wing-agent/blob/develop/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
</p>

**[中文文档](https://github.com/lpdink/wing-agent/blob/develop/docs/zh/README.md)**

> **⚠️ 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

```bash
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**:

```yaml
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:

```bash
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](https://github.com/lpdink/wing-agent/blob/develop/docs/en/custom-tools.md)**

## Magic Commands

Type `/` in the TUI to see available commands.

Full reference: **[docs/en/magic-commands.md](https://github.com/lpdink/wing-agent/blob/develop/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:

```bash
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](https://github.com/lpdink/wing-agent/blob/develop/docs/en/custom-tools.md) | [docs/zh/custom-tools.md](https://github.com/lpdink/wing-agent/blob/develop/docs/zh/custom-tools.md) |
| Magic Commands | [docs/en/magic-commands.md](https://github.com/lpdink/wing-agent/blob/develop/docs/en/magic-commands.md) | [docs/zh/magic-commands.md](https://github.com/lpdink/wing-agent/blob/develop/docs/zh/magic-commands.md) |

## Developing

Start with **[AGENTS.md](https://github.com/lpdink/wing-agent/blob/develop/AGENTS.md)** (high-density project overview). For mechanism-level deep dives (data flow, full HTTP API, glossary), see **[docs/dev/](https://github.com/lpdink/wing-agent/tree/develop/docs/dev/)** (中文).

## License

[Apache-2.0](https://github.com/lpdink/wing-agent/blob/develop/LICENSE)
