Wingman is a stateful, multi-agent runtime with a local CLI control plane and a gateway for routing, sessions, and collaboration. It is designed for more than coding: use it for research, operations, support, planning, and any workflow where agents, tools, and durable context matter.

• Gateway-first runtime: The gateway hosts agents, routing, and durable sessions by default.
• Local control plane: The CLI configures, invokes, and connects to the gateway, with an optional --local execution mode.
• Multi-agent orchestration: A root agent can delegate to specialized subagents with clear roles.
• Protocol-first: The gateway streams raw agent events so any client (web, mobile, terminal) can render them.
• Tool-driven UI prompts (SGUI): tool calls can include UI render hints for Web UI components.
• Extensible: Custom agents, hooks, skills, and MCP tools let you tailor workflows to your team.

Wingman is an agent system, not a single “coding assistant.” Example use cases:

• Engineering: design reviews, refactors, dependency audits, multi-file changes, test automation
• Research: technology evaluations, competitive analysis, documentation synthesis
• Operations: scheduled routines, webhook-driven triage, incident summaries
• Support: channel routing, account-specific agents, structured responses
• Custom domains: finance, legal, data pipelines, or any workflow with tool integrations

• Wingman Gateway: stateful runtime for agents, routing, sessions, and channels
• Wingman CLI: local control plane for onboarding, config, and agent invocation
• Control UI: chat + streaming interface (served by the gateway)
• Wingman Desktop Companion (macOS available): native app that can be enabled as a node (system.notify, system.run)

By default, the CLI connects to a local gateway. For isolated, local-only runs, use --local.

All product requirements live in docs/requirements/. These PRDs are the source of truth and act as a documentation gate:

• Any product or behavior change must update the relevant PRD(s).
• PRs are expected to keep requirements and implementation in sync.
• Legacy docs outside docs/requirements/ (including any historical docs-site content) should not be used for product decisions.

Key docs:

• docs/requirements/000-architecture-overview.md
• docs/requirements/001-multi-agent-architecture.md
• docs/requirements/002-gateway-prd.md
• docs/requirements/003-macos-app-prd.md
• docs/requirements/004-node-protocol.md
• docs/requirements/005-web-ui-sgui-prd.md
• docs/custom-agents.md

• apps/desktop: Desktop Companion app (Tauri; macOS build supports node mode)
• apps/macos: legacy macOS app (Xcode project, transitional)
• apps/wingman: Gateway + CLI + Control UI (Bun)
• apps/cloudflare: Cloudflare Worker + container deployment for Wingman
• apps/docs-website: documentation site (Rspress)
• apps/website: marketing site (Vite)
• docs/requirements: PRDs (source of truth)
• docs/dev-setup.md: local development guide

npm install -g @wingman-ai/gateway

wingman init

wingman gateway start

export WINGMAN_GATEWAY_TOKEN=sk-...
wingman gateway start --auth

• CLI: wingman chat
• Control UI: http://localhost:18790 (default)
• VS Code: Install the Wingman extension (see project repo)

# Cloud providers
wingman provider login anthropic
wingman provider login openai
wingman provider login openrouter
wingman provider login xai
wingman provider login copilot

# Local providers (optional - work without auth)
wingman provider login lmstudio  # Optional
wingman provider login ollama     # Optional

wingman agent --local --agent <id> "prompt"

Main point: skill scanning and MCP proxy are separate toggles, both explicit, and uv checks only happen when the feature is enabled.

Key CLI commands:

# gateway auth token
wingman gateway token --generate
export WINGMAN_GATEWAY_TOKEN="<token>"

# gateway runtime
wingman gateway start

# skills
wingman skill browse
wingman skill install <skill-name>
wingman skill list
wingman skill remove <skill-name>

• Skill scan runs on each wingman skill install only when skills.security.scanOnInstall is enabled.
• MCP proxy runs at agent runtime only when gateway.mcpProxy.enabled is enabled.
• If uv is missing for an enabled feature, Wingman fails with an error (no interactive prompt).
• Full config examples: apps/docs-website/docs/configuration/skills.mdx, apps/docs-website/docs/configuration/gateway.mdx, apps/docs-website/docs/configuration/wingman-config.mdx.

Where to configure:

• Runtime flags: wingman gateway start --help
• Environment secret: WINGMAN_GATEWAY_TOKEN
• Persistent config: .wingman/wingman.config.json
• JSON schema: https://getwingmanai.com/schemas/wingman.config.schema.json

Docs (full examples):

• Gateway: apps/docs-website/docs/configuration/gateway.mdx
• Skills: apps/docs-website/docs/configuration/skills.mdx
• Full config: apps/docs-website/docs/configuration/wingman-config.mdx

• Deterministic routing: bindings map inbound messages to a single agent by default.
• Durable sessions: sessions live in the gateway and persist across clients/devices.
• Agent isolation: each agent has its own workspace, config, and session store.
• Explicit broadcast: rooms enable parallel agent responses when requested.

• Channels + bindings for deterministic routing across accounts and peers.
• Routines for scheduled runs and repeatable workflows.
• Webhooks to trigger agents from external systems.
• Hooks for pre/post tool automation.
• Skills for reusable, domain-specific instruction sets.
• MCP tools to connect external systems and custom integrations.

• Bun (required for bun:sqlite support)
• Node.js (for tools outside Bun)

bun install

cd apps/wingman
bun run build

cd apps/wingman
./bin/wingman gateway start

cd apps/wingman
bun run dev

cd apps/wingman
bun run test

• Config: apps/wingman/.wingman/wingman.config.json
• Logs: ~/.wingman/logs/wingman.log

• Keep docs/requirements/ current for any behavior changes.
• Add tests for new functionality.
• Ensure all tests and builds pass before submitting.

See LICENSE.txt.