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
• Rewind & Diff — Checkpoint-based undo with visual diff viewer
• Skills — Define custom workflows using Agent Skills format
• 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

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:

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 and bundled skills with the same name. Within each scope, the first listed directory wins:

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

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

Project skills (scoped to the current repo):

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

This allows project-specific customization while keeping personal defaults reusable across repositories.

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.

Skills support argument placeholders (${ARGUMENTS}, ${1}, ${2}, and so on) for parameterized workflows.

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.

🤝 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 / .claude/agents/*.md (project)
• ~/.wingman/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, checkpoint browser, 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.

🔀 Proxy Mode

When WINGMAN_URL is set, Wingman can act as a local API proxy with a TUI dashboard for inspecting requests:

wingman proxy [--port 4242]

This starts a local OpenAI-compatible proxy server that forwards requests to your Wingman server, showing real-time request/response details in a terminal UI.

🧩 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. It uses WINGMAN_URL when set; otherwise it expects a local Wingman proxy at http://localhost:4242. These wrappers are deliberately Wingman-backed and are separate from the native subscription-backed wingman --agent <name> modes.

🤖 Claw Mode

Wingman includes an experimental multi-agent orchestration mode:

wingman claw

Claw manages a pool of named agents with persistent memory, scheduled tasks, and a TUI interface. Each agent has its own sandboxed workspace and can spawn sub-agents. Agents persist their sessions across restarts and support proactive check-in schedules.

📊 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.