Using Wing with Claude Code

Wing Pro 12 ships with a deep integration of Claude Code, Anthropic's AI coding agent. The agent reads your code, makes edits, runs tests, debugs failures, and iterates until the work is done. Wing provides a Claude Code panel, a Tasks tool for queueing and tracking work, one-click code actions on test failures and warnings, and a side-by-side review workflow for agent-made changes. Wing also gives the agent efficient access to its analysis, debugger, testing, and version control through the Model Context Protocol (MCP).

If you do not already have Wing installed, download it now. For a step-by-step walkthrough of the same workflow, see the AI agent chapters in the Tutorial. This how-to is the fast path: how to set up, what each piece does, and how to use them together. For full reference details on each feature, see AI Agent-Assisted Development in the manual.

Prerequisites

Using Claude Code requires a Claude account and the claude command available on your PATH. See the Claude Code documentation for sign-up and installation. Anthropic's free and low-cost subscription tiers are sufficient for evaluation; sustained day-to-day use will require the Max plan or comparable API spending.

Wing invokes the claude command when starting a session, so it must be available on your PATH (or you can use an Anthropic API key configured per Claude Code's documentation).

Quick Setup

The easiest way to set up Claude Code is to use the Set Up for Claude Code command in the Project menu. This opens a dialog where you can choose the directory in which to install the Claude Code configuration files; the default is your project's home directory.

You can also enable the same setup when creating a new project:

Use New Project in the Project menu.
Select your host, source directory, and project type as usual.
Tick the Set Up for Claude Code option.
Complete the project creation.

Wing writes the following files in your chosen directory:

.mcp.json -- tells Claude Code where to find Wing's MCP servers (analysis, debugger, testing, review).
.mcp.metadata.json -- resolved project configuration (Python executable, test framework, paths) so the servers don't need to parse Wing project files directly.
CLAUDE.md (project root) -- generated by the agent on first setup, capturing facts about your code base for use in later sessions. The agent maintains this file as the codebase evolves; you can also edit it to add site rules.
.claude/CLAUDE.md -- Wing's instructions to the agent on how to use Wing's MCP tools and an appropriate testing and review methodology.

The next time Claude Code starts in that directory, it discovers Wing's MCP servers and makes their tools available.

Claude Code works with projects on your local machine or on a remote host; projects that run Python in a container or cluster are not yet supported.

Working with Claude Code

The Claude Code tool provides a full Claude Code terminal session inside Wing. It is shown automatically when you run Set Up for Claude Code, or you can show it from the Tools menu.

You interact with Claude Code by typing requests at its prompt -- implement a feature, refactor existing code, write tests, investigate a bug. The agent reads your source files, makes changes, runs tests, and iterates until the task is done.

Sessions persist across restarts. Wing captures the session ID when Claude Code exits and resumes the same session the next time you start it, so your conversation history is preserved. Use the Options menu in the tool to start a new session, resume a different one, or change the working directory.

You can have multiple Claude Code instances open simultaneously, each in a different working directory. Additional instances are created automatically when you use one-click fixes or run multiple queues from the Tasks tool.

See The Claude Code Tool for full details.

AI Actions

Wing provides quick access to AI agent-driven actions:

One-click fixes for failing tests, debugger exceptions, and code warnings -- via the relevant tool's right-click menu.
Test generation for Python files from the Testing menu.
Code actions from the AI actions icon in the top right of the editor: explain a scope, review for quality or security, fix warnings, optimize, update docs, or run a custom action.

See AI Actions for details.

Planning and Executing Tasks

The Tasks tool lets you draft work in advance and run it through Claude Code. This is especially useful when you have several tasks and want them to run sequentially -- or in parallel across multiple queues -- with minimal intervention. The tool has four tabs:

Plan -- Draft new tasks under goals or as a flat list. Tasks start in draft mode and don't run until you assign them to a queue using the Q button on each task (or queue a whole goal at once from its Q menu).

Execute -- Queued and running tasks live here. Each queue maps to a Claude Code instance. With Auto-advance enabled the queue moves to the next task automatically; otherwise the cog icon on a task starts it manually.

Review -- When a task finishes, it transitions here. Each queue shows a list of changed files plus two action links:

Start Review opens a side-by-side diff/merge session where you accept or reject individual hunks and optionally add comments with the pencil icon between hunks. When you finish review, the toolbar's green check mark commits the change set. If you have added per-hunk comments, those comments are agent feedback (not commit annotations), so the task transitions back to Execute for the agent to act on instead of committing. The toolbar's pencil icon rejects the task with an overall comment.
Commit Without Review skips the diff session and commits directly. Appropriate when tests have already validated the work or when a separate reviewer has signed off.

History -- Completed tasks appear here with run time and token consumption recorded.

Per-task controls are available from the Q button:

Plan Mode -- the agent writes a plan for the task without making any code edits. You review the plan, edit it if needed, then approve to execute. Use for risky or large changes, or when multiple Claude instances are running concurrently and you want to avoid them deciding to edit the same file at the same time.
Auto Mode -- Claude Code's built-in classifier decides which agent actions need your approval and which can run on their own. This is the right setting for letting the agent work without constant interruption. Requires a Claude Max, Team, or Enterprise account and a recent, sufficiently capable model; other accounts, or the lightweight models, cannot use auto mode.
Session reuse -- the default is a new session per task, which keeps unrelated context out of the way and minimizes token use. Reuse the existing session when the next task builds on the last one.
Compact Context -- compacts a long-running session before continuing, when context has grown large but is still useful. Compaction itself consumes tokens, so it pays off only in long sessions.

Commit Mode, set in the AI Agent tab of Project Properties:

Claude commits only when asked (default) -- Claude commits only when you start a review or use Commit Without Review, writing the message from the task summaries.
Claude commits after each task -- Claude commits on its own at the end of each completed task, without waiting for you.
Claude commits at its discretion -- Claude commits on its own at logical stopping points it chooses.
Wing commits with generated message -- Wing builds a commit message from the task summaries and commits immediately.
Wing presents commit message for review -- Wing opens the regular VCS commit dialog with the message pre-filled.

Sharing with a team -- Tasks can be shared via version control by enabling Share Plan in the Options menu. Other developers' goals, tasks, and history are visible in read-only form.

See The Tasks Tool for full details.

Reviewing Ad-Hoc Changes

When Claude Code makes changes outside the Tasks workflow -- for example, in response to requests typed directly into the Claude Code panel -- and there are uncommitted version control changes, a REVIEW button appears next to the Claude Code toolbar. Clicking it asks Claude Code to start a review using Wing's review MCP server, which opens the same diff/merge session described above.

The review behavior is identical: any per-hunk comment causes the task to iterate when you finish review, rather than commit.

Debugging with Claude Code

Once set up, Claude Code has access to Wing's debugger. You can ask Claude Code to:

Launch and debug a script -- "Debug my_script.py and stop on the first line."
Set breakpoints -- "Set a breakpoint at line 42 in app.py."
Step through code -- "Step over the next line" or "Step into this function."
Inspect state -- "What are the local variables?" or "What is the value of result?"
Evaluate expressions -- "Evaluate len(items) in the current context."
Try out new code in the live runtime -- "Execute this revised function and re-run the test."
Debug exceptions -- "Set exception mode to always break on exceptions."

The debugger MCP server runs as a separate process from the Wing IDE, so Wing does not need to be open for Claude Code to debug. Multiple debug sessions can be active at the same time.

Testing and Coverage with Claude Code

Claude Code has access to Wing's test runner and coverage analysis. You can ask Claude Code to:

Discover tests -- "List all test files in this project."
Run tests -- "Run the tests" or "Run test_foo.py."
Run tests with coverage -- "Run tests with coverage collection."
Find affected tests -- "Which tests are affected by my changes to utils.py?"
Get coverage info -- "Show coverage for src/mymodule.py."

The testing MCP server reads the project metadata written by Wing (.mcp.metadata.json) to determine which test framework to use (pytest, unittest, etc.), how to discover test files, and which Python interpreter to run tests with. This metadata is updated automatically whenever project settings change in Wing.

Coverage-based test invalidation: When tests are run with coverage collection (the default), the server tracks which test functions execute which lines of source code. After making code changes, asking "which tests are affected?" identifies the exact tests that exercised the changed lines -- not just tests that touched the file, but tests that ran the specific lines you changed. This is especially useful in large codebases where running all tests would take a long time.

Testing Regimen -- the AI Agent tab in Project Properties includes a Testing Regimen setting that controls how aggressively Wing instructs the agent to write and run tests. The default is minimal: write new tests when adding functionality and run those new tests at task end. Other modes range from none (don't push the agent toward tests) through balanced (also run stale tests in changed directories before review and commit), thorough (run all stale tests before review and commit), and obsessive (run the full suite before review and commit). Changes apply only to new Claude Code sessions; running sessions keep the regimen they started with.

The testing MCP server runs as a separate process and does not require the Wing IDE to be open.

Tips for Effective Use

A few habits that produce reliable results:

Write clear, thorough requests. Provide context about what you want, why, and any constraints. The more specific you are, the better the results.
Don't micro-manage. Let the agent plan and execute. Step in when it gets stuck rather than directing every step.
Build feedback into requests. Ask for unit tests and ask the agent to run them. Tests give the agent a way to verify its own work and give you concrete evidence even before reading the diff.
Use tasks for multi-step work. Rather than typing a sequence of requests manually, plan them as tasks and let the queue handle execution and advancement.
Review at the behavior level. For larger changes, read the task summary and test results first, skim the diff for surprises, spot-check a few hunks, and trust the rest contingent on tests passing.
Cross-check from multiple angles. Ask the agent to review its own work for behavior, edge cases, security, or performance: "Re-read the change you just made and propose the three most likely sources of bugs. Don't fix anything; just list them."
Manage context size. Long conversations consume more tokens and may degrade quality. Use /clear in Claude Code to start fresh, or use Compact Context on a queued task to preserve key context while reducing token usage.

See Using AI Agents Effectively for more guidance.

Permissions and Safety

The AI Agent tab in Project Properties controls what Claude Code is pre-approved to do without asking for confirmation. You can restrict which directories it may edit, whether it can run commands, and whether it can use version control.

For working safely with an AI agent, the recommended posture is:

Run the agent in a dedicated environment (VM, container, or at minimum a dedicated user account) so it does not have access to keys for production infrastructure or sensitive data.
Use revision control with a remote repository the agent cannot push to. Set up a VCS-only SSH key for the remote and do remote operations manually.
Configure continuous backup (Dropbox, iCloud, or similar) so mistakes are recoverable.

See AI Agent Safety for the full discussion.

Multiple Wing Instances

Each Wing instance runs its own IPC listener and passes the port to Claude Code via the WING_MCP_PORT environment variable. Multiple Wing instances operate independently, each servicing the Claude Code instances that they launch.

If Claude Code is started outside of Wing (e.g., from a terminal), the MCP servers fall back to the port recorded in .mcp.metadata.json, which may belong to a different Wing instance. For reliable operation, launch Claude Code from within Wing.

Troubleshooting

MCP server fails to start: Verify that the path in .mcp.json points to an existing Wing installation. If you have reinstalled or moved Wing, update the path accordingly.

Python not found: The MCP servers use Wing's bundled Python interpreter. If this fails, ensure your Wing installation is complete by running wing --check-install from the command line.

Path changes after update: After updating Wing to a new version, you may need to update the path in .mcp.json if the installation directory has changed. Creating a new project with the Set Up for Claude Code option will always write the correct path.

No project metadata: The testing MCP server requires .mcp.metadata.json to be present alongside .mcp.json. This file is written automatically by Wing when you use the Set Up for Claude Code command or the New Project dialog's setup option. If the file is missing, re-run Set Up for Claude Code from the Project menu.

No coverage data: If coverage queries return no data, make sure you have run tests with coverage collection enabled first. The test_run tool collects coverage by default.

Manual Setup

If you prefer to configure Claude Code manually instead of using the Set Up for Claude Code command, create a file named .mcp.json in the root of your project directory with the following content:

Linux and macOS:

{
  "mcpServers": {
    "wing-analysis": {
      "command": "/path/to/wing/bootstrap/run-mcp-analysis.sh"
    },
    "wing-debug": {
      "command": "/path/to/wing/bootstrap/run-mcp-debug.sh"
    },
    "wing-testing": {
      "command": "/path/to/wing/bootstrap/run-mcp-testing.sh"
    },
    "wing-review": {
      "command": "/path/to/wing/bootstrap/run-mcp-review.sh"
    }
  }
}

Windows:

{
  "mcpServers": {
    "wing-analysis": {
      "command": "C:\\path\\to\\wing\\bootstrap\\run-mcp-analysis.bat"
    },
    "wing-debug": {
      "command": "C:\\path\\to\\wing\\bootstrap\\run-mcp-debug.bat"
    },
    "wing-testing": {
      "command": "C:\\path\\to\\wing\\bootstrap\\run-mcp-testing.bat"
    },
    "wing-review": {
      "command": "C:\\path\\to\\wing\\bootstrap\\run-mcp-review.bat"
    }
  }
}

Replace the command paths with the actual path to your Wing installation directory.

When setting up manually, the MCP servers still need a .mcp.metadata.json file alongside the .mcp.json for project configuration (Python path, test framework, etc.). This file is written automatically by Wing when the project is open. Use Set Up for Claude Code in the Project menu to have Wing create both files for you.