Setting Up an AI Agent

Wing works with several AI coding agents. Use Set Up for AI Agent in the Project menu and choose the agent you want to use; this authorizes the agent for the project, writes the files it needs, and opens the Tasks and AI Agent tools. You can also set an agent up when creating a new project, with the Set Up for AI Agent option in the New Project dialog.

The setup dialog asks you to select a directory where Wing's files will be written. This is typically the top-level directory of the source tree you want the agent to work in, and is shared by every agent set up in the project. If you have set an agent up for this project before, the dialog defaults to the directory you chose earlier.

Note that each agent is authorized separately, so Wing never runs an agent against your source tree without your permission.

Supported Agents

Wing needs each agent's own command line tool installed, and each agent needs its own account or API key. Wing does not download or install agents on its own.

Before choosing an agent, see the table in Know Each Agent's Safety Gaps, in AI Agent Safety. It shows which agents are recommended, how well each runs the Tasks Manager, and what each is missing.

Claude Code -- Anthropic's agent. Install it from the Claude Code setup guide. Needs a Claude subscription or an Anthropic API key.
Codex -- OpenAI's agent. Install it with npm install -g @openai/codex. Needs a ChatGPT plan or an OpenAI API key.
Antigravity -- Google's agent. Install the Antigravity CLI from its download page. Needs a Google account, or a Gemini API key.
Copilot -- GitHub's agent. Install it with npm install -g @github/copilot. Needs a GitHub Copilot subscription, or your own AI model provider.
Cursor -- Cursor's command line agent. Install it with curl https://cursor.com/install -fsS | bash. Needs a Cursor account, reached by browser login or with an API key from the Cursor dashboard.
goose -- Install it with the download_cli.sh script from its releases page. goose has no terminal interface of its own, so Wing runs it over the Agent Client Protocol (ACP) and manages it in its own AI agent conversation UI. Provider-agnostic: choose an AI provider, model, and key with goose configure.
OpenCode -- Install it with curl -fsSL https://opencode.ai/install | bash. Provider-agnostic: run opencode auth login for whichever AI model provider you choose.
Other ACP Agents -- Any other agent that speaks the Agent Client Protocol may also be used. Give Wing its command in Configure AI Agents, along with the environment variables it reads its credentials from.

Wing runs each of these agents, except goose and other ACP agents, in its own terminal interface inside the AI Agent tool.

Even agents that are not installed are listed, so Wing can show you how to install it. The exact install commands can of course change; check the agent's own site if you run into any problems.

The npm installs need a recent Node.js (22 or later for Copilot). Some Linux distributions ship an older version, in which case you can install a current one from nodejs.org or with nvm.

Credentials can be arranged outside Wing -- most of these tools are used from a terminal as well -- and an agent you have already signed into needs nothing further here. To pass an API key to an agent through Wing, set it in the Environment in Project Properties. For goose and other ACP agents, Configure AI Agents can also hold credentials, or keep several accounts side by side, as described in Choosing and Configuring an Agent.

An API key from an AI provider used with the legacy AI features, which are only in Wing Classic, also works with an agent: Claude Code takes an Anthropic key, Codex an OpenAI key, and Antigravity a Gemini key. goose and OpenCode work with keys from many providers.

Advanced: ACP Versions of Agents

Claude Code, Codex, Antigravity, Copilot, Cursor, and OpenCode can also run over ACP, in Wing's AI agent conversation UI. These ACP versions are hidden from Wing's UI unless the Show ACP Versions of Agents preference on the AI page under Projects in Preferences is enabled, and then are listed under ACP Agents:. When it is not, holding Shift as an agent menu or list opens, or while it is open, shows them there. The plain TUI versions are recommended; see AI Agent Safety for how the two differ.

Copilot, Cursor, and OpenCode need nothing more to run over ACP. Claude Code needs its ACP adapter, installed with npm install -g @agentclientprotocol/claude-agent-acp (Node.js 22 or later), and an Anthropic API key in place of a Claude subscription. Codex needs its adapter, installed with npm install -g @agentclientprotocol/codex-acp. Antigravity needs its separate ACP server, since the agy command does not speak ACP; see Using Wing with Antigravity. With the preference enabled, Configure AI Agents also offers these agents, and its configurations run them over ACP.

Wing's AI agent integration and the Tasks tool work with projects on the local host and on remote hosts. They are not currently supported for projects that run Python in a container or cluster. Email us at support@wingware.com if you need one of these.

Projects on a Remote Host

For a project whose files are on a remote host, the agent runs there rather than on your machine, so it is the remote host that needs the agent installed and signed in. Everything above works the same: the setup dialog asks for a directory on that host, Wing writes its files there, and its MCP servers run there too, reaching this Wing through the same connection the rest of the IDE uses. The AI Agent and Tasks tools behave as they do locally.

What the Setup Process Does

When you click OK, Wing:

writes the development guides that tell the agent about this project: the MCP tools available to it, the testing regimen, the commit policy, and your conventions
points AGENTS.md at those guides, creating it if it does not already exist and leaving anything else in it alone (Claude Code reads CLAUDE.md instead, so it gets that as well)
writes the files that agent itself needs, which differ per agent and are listed under Files Wing Writes below
adds the directory to the project if it is not already included, and records it as the agent directory
adds its generated files to your version control ignore file, if you have one
opens the Tasks tool in the first editor split and an AI Agent tool panel in the second (if present). The panels can be moved from there to any other panel location.
offers to run the agent's own project analysis, if it has one, so it starts with its own notes about your code as well as Wing's

Everything Wing generates goes in the directory you chose, and is listed next.

Files Wing Writes

Whichever agent you set up, Wing writes these into that directory:

.wing -- the development guides every agent reads: this project's conventions, its testing regimen, its commit policy, and which MCP server each of Wing's tools is on. Rewritten when the settings behind them change.
AGENTS.md -- a marked block pointing at those guides, in the file most agents read. Wing creates it if it does not exist and rewrites only its own block, leaving anything you put before or after it alone.
.claude/CLAUDE.md -- the same pointer in the file Claude Code reads instead.
.mcp.metadata.json -- how Wing's MCP servers reach this Wing and this project: the port, and the Python environment, test framework and paths they run tests with.
.TASKS -- the Tasks tool's record of your tasks, one file per user.

Wing adds the generated ones to your version control ignore file, since they name paths on your machine. AGENTS.md is not ignored: it is a file teams usually write and commit themselves.

Then, per agent:

Claude Code -- .mcp.json, which tells it how to start Wing's MCP servers, and .claude/settings.local.json, holding Wing's hooks and its pre-approvals of Wing's own tools. Wing's entries in each are merged with yours.
Codex -- nothing more. Codex is given Wing's hooks and MCP servers on its command line, and Codex ACP is handed them over the protocol.
Antigravity -- a plugin in .agents/plugins/wing holding Wing's hooks and MCP servers. The rest of .agents is left alone, and Antigravity ACP writes nothing more.
Copilot -- .mcp.json, the same file Claude Code reads, and its hooks in .github/copilot/settings.json. Copilot ACP writes nothing more, since Wing passes its MCP servers over the protocol.
Cursor -- .cursor/hooks.json for Wing's hooks, .cursor/plugins/wing, a plugin of Wing's own holding its MCP servers, and its own tools pre-approved in .cursor/cli.json. The rest of .cursor, where teams keep their rules, is left alone, and Cursor ACP writes nothing more.
goose and OpenCode -- nothing more. OpenCode is given Wing's hooks and MCP servers in its environment, and an agent run over ACP is handed them over the protocol.

.mcp.json and an agent's hook file are ones Wing merges its entries into rather than owns, so each is added to the ignore file only while it holds nothing but Wing's. If your project keeps its own MCP servers or its own hooks there, Wing leaves the file for you to decide about, and the Tasks tool asks what to do with it the first time an agent's work touches it.

Updating Configuration

Wing automatically updates its configuration files whenever relevant project properties change, or if needed to support new features in the currently running version of Wing.

If the project's home directory changes, Wing will ask before moving its files to the new location, and will not move them while an agent is working.

MCP Servers

Wing provides four MCP (Model Context Protocol) servers that give the agent access to Wing's testing, debugging, review, and source analysis capabilities. These servers help to drastically reduce token, and thus costs, use during AI agent driven development:

wing-analysis -- Allows the agent to query Wing's Python source analysis engine for points of definition and points of use, and to get at the code for named scopes much more efficiently and accurately than it can without Wing.
wing-debug -- Allows the agent to run code under Wing's debugger, set breakpoints, evaluate expressions, and inspect the call stack.
wing-testing -- Allows the agent to discover, run, and inspect the results of unit tests with Wing's test runner.
wing-review -- Allows the agent to start a change review in Wing's user interface. Wing shows all uncommitted changes and lets you approve, request adjustments, or cancel. See The AI Agent Tool for details on the review workflow.

How the agent reaches these servers depends on the agent: Claude Code launches them itself, and other agents are handed them by Wing when their session starts. Either way the servers use the Python environment, test framework, and other settings configured in your Wing project.