wingman-agent

Wingman Agent

A powerful AI-powered coding assistant that runs directly in your terminal. Wingman helps you with coding tasks by reading files, executing commands, editing code, and writing new files — all through natural conversation.

✨ Features

• Interactive TUI — Rich terminal interface with markdown rendering and syntax highlighting
• File Operations — Read, write, edit, and search files in your codebase
• Shell Integration — Execute shell commands with user approval
• LSP Integration — Code intelligence via auto-detected language servers (definitions, references, diagnostics, call hierarchy, and more)
• MCP Support — Extend functionality with Model Context Protocol servers
• Multi-Model Support — Works with any OpenResponses API compatible endpoint with auto-selection
• Changes — Git-backed working tree changes with a visual diff viewer
• Skills — Define custom workflows using Agent Skills format
• Plugins — Install skills, MCP servers, and lifecycle hooks from Agent Plugins and Codex/Claude-compatible packages
• Image Support — Paste images from clipboard for vision-capable models
• File Context — Add files to context with @ or drag-and-drop file paths
• Automatic Colors — Adapts the built-in palette to light or dark terminal backgrounds
• Session Management — Conversations are saved automatically and can be resumed

📦 Installation

Homebrew (macOS)

brew install adrianliechti/tap/wingman-cli

Linux: Homebrew no longer supports formula-style binary installs from taps, so use go install (below) or download a binary from the releases.

Desktop App (macOS, Apple Silicon)

Install the Wingman Agent desktop app into /Applications via Homebrew Cask:

brew install --cask adrianliechti/tap/wingman-app

Scoop (Windows)

scoop bucket add adrianliechti https://github.com/adrianliechti/scoop-bucket
scoop install wingman

From Source

go install github.com/adrianliechti/wingman-agent/cmd/wingman@latest

Build Locally

git clone https://github.com/adrianliechti/wingman-agent.git
cd wingman-agent
go build -o wingman ./cmd/wingman

🚀 Quick Start

1. Set up your API key:

# For any OpenAI-compatible API endpoint
export OPENAI_API_KEY="your-api-key"

# Optional: custom endpoint (defaults to OpenAI)
export OPENAI_BASE_URL="https://your-api-endpoint/v1"

1. Run Wingman in your project directory:

wingman

To use the Wingman terminal UI with an existing native Codex, Claude, or Pi configuration (including subscription logins), sign in or configure the corresponding CLI and select it at startup:

codex login
wingman --agent codex

claude auth login
wingman --agent claude

wingman --agent pi

These modes use the native CLI's active login and session storage rather than the Wingman/OpenAI-compatible API configuration above. They inherit the current shell environment unchanged, so unset API-key or alternate-provider variables if you want the native CLI to use its stored subscription login.

The web UI uses the same agent registry and native login paths as the TUI. Detected Claude, Codex, Copilot, OpenCode, and Pi installations are offered in both. Additional ACP agents can be configured in ~/.wingman/agents.json; they are merged with detected agents and replace a detected entry only when they use the same normalized name. The built-in Wingman entry continues to use the configured API backend.

1. Start chatting! Ask Wingman to help with coding tasks:

> Show me all TODO comments in this project
> Refactor the config package to use dependency injection
> Write tests for the agent module

1. Resume a previous session:

wingman --continue            # resume the most recent session
wingman --resume <session-id> # resume a specific session

wingman --agent codex --continue  # resume the latest native Codex session
wingman --agent claude --continue # resume the latest native Claude session
wingman --agent pi --continue     # resume the latest native Pi session

Non-interactive mode

Use wingman exec (or wingman e) to run a prompt without opening the TUI. Exec always runs unattended: actions are approved automatically, and elicitation uses defaults or recommended choices instead of waiting for a UI. Required free-text questions are declined rather than answered with invented input.

wingman exec "Summarize this project"
wingman exec "Fix the failing tests"
git diff | wingman exec "Review this diff for bugs"

When stdin is piped alongside a prompt, Wingman treats it as context and keeps the positional prompt as the instruction. Use - when stdin should be the entire prompt. Input is capped at 10 MiB.

git diff | wingman exec "Review this diff for bugs"
printf 'Summarize this project' | wingman exec -

The final assistant message is the only content written to stdout, and normal runs are otherwise quiet. Add --debug to stream reasoning, tool arguments, and tool results to stderr. --json runs a final tool-free formatting pass and returns one JSON object; --schema additionally constrains that object with a JSON Schema:

wingman exec "Generate release notes" > release-notes.md
wingman exec --debug "Inspect the main packages"
wingman exec --json "Inspect the main packages" | jq
wingman exec --schema ./project.schema.json "Extract project metadata"

Sessions are saved by default. Resume one by ID or continue the latest session for the current agent and workspace:

wingman exec resume <session-id> "Now suggest improvements"
wingman exec resume --last "Implement the first suggestion"
wingman exec --ephemeral "Triage this repository"

Agent Modes

wingman acp <target> defaults to the native backend. This keeps subscription login and session behavior aligned with selecting the same agent in the TUI or Web UI; --backend wingman is the explicit opt-in to provider overrides.

⚙️ Configuration

Environment Variables

Backend — connect to a Wingman server, or any OpenAI-compatible API:

When neither WINGMAN_URL nor OPENAI_API_KEY is set, Wingman connects to an OpenAI-compatible backend at http://localhost:4242/v1.

Models & Reasoning — every value is optional; unset values are chosen automatically by role (plan → largest available model, code → medium, utilities → smallest):

Behavior

Project Configuration

Create an AGENTS.md (or CLAUDE.md) file in your project root to provide context-specific instructions. Wingman walks up from your working directory and reads all matching files it finds, so you can layer project and workspace-level guidelines:

# Project Guidelines

- Use Go 1.25+ features
- Follow standard Go project layout
- Write tests for all new functionality

MCP Integration

Add an mcp.json file to integrate with MCP servers:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"]
    }
  }
}

Remote (HTTP/SSE) servers are also supported via the url and optional headers fields.

Configs are loaded from two locations and merged: ~/.wingman/mcp.json (global, shared across all projects) and ./mcp.json (project root). When a server name appears in both, the project config wins.

🛠️ Built-in Tools

Wingman comes with powerful built-in tools:

LSP Support

Wingman automatically detects and connects to language servers based on project files. No configuration needed — if you have a language server installed, Wingman will use it.

The LSP tool provides these operations:

• diagnostics / workspaceDiagnostics — Compiler errors and warnings
• definition / implementation — Navigate to symbol definitions or interface implementations
• references — Find all usages of a symbol
• hover — Type information and documentation
• documentSymbol / workspaceSymbol — List or search symbols
• prepareCallHierarchy / incomingCalls / outgoingCalls — Explore call graphs

🎨 Modes

• Agent Mode — Full autonomous operation with tool execution
• Plan Mode — Planning and analysis without project source edits

Toggle between modes using Tab or the explicit /plan and /agent commands.

⌨️ Keyboard Shortcuts

📝 Commands

Skill slash commands (e.g. /commit, /code-review) also appear here — see Skills below.

🔧 Skills

Skills are reusable, invocable workflows defined in SKILL.md files. Project skills override personal, plugin, and bundled skills with the same name. Within each scope, the first listed directory wins:

Project skills (scoped to the current repo):

• .wingman/skills/<name>/SKILL.md
• .agents/skills/<name>/SKILL.md
• .claude/skills/<name>/SKILL.md

Personal skills (user-wide, across all projects):

• ~/.wingman/skills/<name>/SKILL.md
• ~/.agents/skills/<name>/SKILL.md
• ~/.claude/skills/<name>/SKILL.md

This allows project-specific customization while keeping personal defaults reusable across repositories. Wingman uses the same directory order and the same first-wins rule for skills, plugins, and custom agents, and reports every shadowed entry on startup so a silently ignored file is visible.

Skill frontmatter follows the Agent Skills specification: name and description are required; license, compatibility, metadata, and experimental allowed-tools are accepted. allowed-tools is descriptive metadata and never bypasses Wingman's normal tool approval policy.

Bundled Skills

Wingman ships with built-in skills that are available immediately via slash commands. Their complete directories are copied to a managed temporary workspace snapshot, while a personal or project skill with the same name cleanly overrides the built-in:

Existing ~/.wingman/skills/<name> customizations from older Wingman versions remain personal overrides. Rename or remove one only when you want the current bundled skill to take precedence.

Custom Skill Example

---
name: run-tests
description: Run the project test suite with coverage
---

# Testing Skill

Run tests with: `go test -cover ./...`

Place this file at .wingman/skills/run-tests/SKILL.md and invoke it with /run-tests. Wingman supports Claude-style skill arguments: $ARGUMENTS, zero-based $ARGUMENTS[N], and $N; non-empty arguments are appended as ARGUMENTS: <value> when no argument placeholder is present. The optional Claude extensions arguments (a space-separated string or string list) and argument-hint enable named positional substitutions such as $component and display /skill [component] hints in the UI. ${SKILL_DIR} and ${PROJECT_DIR} provide neutral directory variables, with ${CLAUDE_SKILL_DIR} and ${CLAUDE_PROJECT_DIR} accepted as compatibility aliases. The two extra frontmatter fields are intentionally non-portable and therefore rejected in Agent Plugin skills.

A skill may keep any supporting files next to SKILL.md. Common conventions are references/ for selectively loaded guidance, assets/ for files to copy or transform, templates/ and examples/ for reusable inputs, and scripts/ for deterministic helpers. Wingman copies the complete directory tree for built-in skills, including dotfiles and underscore-prefixed resources.

Scripts run through Wingman's normal shell command path and its approval policy. Wingman does not infer dependencies or automatically create a virtual environment, so a skill that needs Python packages should document a reproducible command such as uv run, a lockfile-backed environment, or explicit venv setup.

A ready-to-copy resource-backed skill with metadata, named arguments, directory variables, a reference, and a helper script lives in examples/skills/run-tests.

🪝 Hooks

Wingman loads Codex-format hooks from ~/.codex/hooks.json, <project>/.codex/hooks.json, and enabled plugins. It supports the Codex lifecycle events and JSON input/output decision protocol; matching command hooks run concurrently. Project and plugin hooks require a one-time confirmation in each session before their first matching command runs.

Command handlers are Codex-compatible. Wingman additionally supports Claude-style type: "http" handlers using the same JSON request and response body as command hooks. The HTTP extension requires explicit allowedEnvVars for environment interpolation in headers.

See the Codex hooks reference for the configuration shape. Wingman intentionally does not load the former Wingman-specific flat hook format.

🧩 Plugins

A plugin bundles skills, MCP servers, and optional lifecycle hooks. Wingman implements the portable Agent Plugins specification v1.0.0.

Drop a plugin directory into any of these, project before personal, first name wins:

• .wingman/plugins/<name>/, .agents/plugins/<name>/, .claude/plugins/<name>/ (project)
• ~/.wingman/plugins/<name>/, ~/.agents/plugins/<name>/, ~/.claude/plugins/<name>/ (personal)

A portable Agent Plugin starts with a plugin.json manifest and two standard component types. A complete package can also carry resources and client-owned extensions such as hooks:

release-tools/
├── plugin.json                        # required manifest
├── mcp.json                           # MCP servers this plugin provides
├── hooks/
│   └── hooks.json                     # declared through extensions.com.openai
├── scripts/
│   └── release-context.sh             # hook helper
├── templates/
│   └── changelog.md                   # shared plugin resource
├── skills/
│   └── release-check/
│       ├── SKILL.md                   # one skill per immediate subdirectory
│       └── references/
│           └── release-policy.md      # skill-local resource

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "release-tools",
  "version": "1.0.0",
  "description": "Release checklist skill plus the MCP servers it needs"
}

name must be lowercase alphanumerics, hyphens, and periods. A manifest that violates the schema is rejected and reported. As explicit non-fatal exceptions, unknown top-level fields and a non-object extensions value are reported and ignored; unknown reverse-domain extension namespaces remain opaque.

Only plugin.json is a plugin manifest. Native .codex-plugin, .claude-plugin, and .cursor-plugin manifests are not loaded. Skills are read only from immediate subdirectories of skills/, and MCP servers only from mcp.json, as defined by the portable specification. Every loaded SKILL.md is validated against the Agent Skills name, directory-name, description, compatibility, and frontmatter constraints.

Plugin hooks

A plugin can supply a Codex hook declaration under the client-owned extensions.com.openai.hooks field. Wingman accepts a single ./ path, an array of paths, an inline hooks object, or an array of inline objects. Manifest paths must remain inside the resolved plugin root. com.openai is a namespaced Agent Plugins extension defined by Codex, not a portable Agent Plugins core field; no hook file is loaded implicitly.

Plugin hook commands receive PLUGIN_ROOT and PLUGIN_DATA. The plugin data directory is created before hooks run. Plugin hooks are untrusted code: Wingman asks once per session before the first matching hook from each plugin executes.

Plugin MCP servers

mcp.json uses the portable Agent Plugins format, which is stricter than Wingman's own mcp.json: every server declares its type explicitly, and command must be a bare executable name or a ./ path inside the plugin.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "changelog": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/changelog-mcp", "--cache", "${PLUGIN_DATA}/cache"],
      "env": { "CHANGELOG_TEMPLATE": "${PLUGIN_ROOT}/templates/changelog.md" },
      "cwd": "${PLUGIN_DATA}"
    },
    "release-api": {
      "type": "streamable-http",
      "url": "https://releases.example.com/mcp"
    }
  }
}

Two variables are expanded in args, env values, and cwd, and are set in every plugin subprocess:

Remote servers must use HTTPS unless they point at loopback, and must not carry credentials in headers, which are visible package data rather than a secret store.

Precedence and conflicts

Plugin components join the same namespaces as your own configuration, and your configuration always wins:

• Skills — a plugin skill is invoked by its plain name (/release-check) and also as <plugin>:<skill> (/release-tools:release-check). If a personal or project skill takes the plain name, the qualified form still reaches the plugin's copy.
• MCP servers — plugin servers sit below ~/.wingman/mcp.json and ./mcp.json, so a server you configure yourself replaces the plugin's entry of the same name.
• Duplicate endpoints — servers configured identically across any source are collapsed to one connection, so the same tools are not offered twice under different names. Any difference in headers, arguments, or environment keeps both.

Component failures never take down the rest of a plugin: an unreadable mcp.json still leaves its skills loaded, and one invalid server entry skips only itself. Everything skipped is reported on startup.

A ready-to-copy plugin lives in examples/plugins/release-tools.

🤝 Custom Agents

Custom agent types extend the built-in sub-agent roster (explore, code-reviewer, verification, …) with your own specialists. Wingman discovers them from markdown files (first definition of a name wins, project before personal):

• .wingman/agents/*.md, .agents/agents/*.md, .claude/agents/*.md (project)
• ~/.wingman/agents/*.md, ~/.agents/agents/*.md, ~/.claude/agents/*.md (personal)

---
name: db-expert
description: Deep PostgreSQL schema and query analysis
access: read-only
---

You are a PostgreSQL specialist. Inspect schemas, migrations, and queries...

The body becomes the agent's system prompt. access selects the toolset — read-only (search/read only), verify (read plus build/test commands), or all (default) — and an optional model: plan or model: utility picks the session's planning or utility model instead of inheriting. A custom definition with a built-in name replaces that built-in.

🖥️ Server Mode

Wingman includes a web-based UI server — useful for IDE integrations or browser-based access:

wingman server [--port 9000]

This starts an HTTP server at http://localhost:9000 (or another available port) with a React UI featuring a chat panel, file browser, diff viewer, diagnostics panel, an integrated terminal (multiple xterm.js sessions, shell of your choice, Ctrl+Alt+T), and session management. Ctrl+P opens the command palette — same shortcut as the TUI command center (Cmd/Ctrl+K works too). The server uses WebSockets for real-time streaming.

🧩 CLI Wrappers

Wingman can launch other coding agents pre-configured to use a Wingman backend:

wingman run claude [args...]
wingman run claude-desktop [args...]
wingman run codex [args...]
wingman run copilot [args...]
wingman run gemini [args...]
wingman run goose [args...]
wingman run junie [args...]
wingman run opencode [args...]
wingman run pi [args...]

Each wrapper automatically configures the target CLI with the correct endpoint and authentication. WINGMAN_URL is required. These wrappers are deliberately Wingman-backed and are separate from the native subscription-backed wingman --agent <name> modes.

📊 Terminal-Bench

Wingman can run Terminal-Bench tasks through Harbor's generic ACP agent runner. The integration installs the released Wingman binary inside each task container, preserving the task's own Docker environment and verifier. See the Terminal-Bench compatibility guide for the pinned agent descriptor and benchmark commands.