The Tasks Tool

The Tasks tool helps you plan and orchestrate work for AI agents. You define goals, break them into tasks, queue those tasks for execution, review the results, and track what was done. This workflow lets you prepare multiple work items in advance and run them sequentially through Claude Code instances.

The tool has four tabs across the top: Plan, Execute, Review, and History, which are used for each part of this process. Each tab shows only the tasks that belong to it -- Plan shows unqueued pending tasks, Execute shows queued pending and running tasks, Review shows tasks waiting for your review, and History shows completed tasks. When a task transitions between states (for example, by being queued, sent for execution, or submitted for review), a brief animation flies from the task row to the destination tab so you can see where it went.

An Options menu in the upper right provides settings that apply to the tool as a whole.

Toolbar Status Area

Even when the Tasks tool is not visible, an AI-agent status area at the right end of the main toolbar tracks agent activity across all queues:

A Lightning Bolt (executing) icon opens a menu of the current Claude Code instances; selecting one shows that instance wherever it lives. An orange number on the button counts the queues with a task waiting for your input.
A Review button becomes enabled once one or more queues have a task awaiting review. Its menu groups Start Review and Commit Without Review actions by queue, and an orange number counts the queues with a task ready to review.

These counts mirror the Execute and Review tab counts exactly, so you can watch agent progress and jump straight to work that needs attention without keeping the tool open.

Planning Goals and Tasks

The Plan tab has two sub-views, selectable from a toggle in its toolbar:

Tasks -- A flat list of all tasks across all goals, useful for scanning everything at once.
Goals -- An accordion view where each goal expands to show its tasks. Only one goal is expanded at a time.

You can work either with or without defining goals; use them and the Goals view if you have a lot of work to organize, or ignore goals and just use the Tasks view if you do not.

To add a task, use the + button in either view. Then enter the task description, which is the text that will be sent to Claude Code when the task is executed. Press Enter to save the task and create another, or click away to save without creating a new one. Shift+Enter and Ctrl+Enter insert newlines within a task. Any newly created or edited task that no longer has text in it is automatically removed when focus moves elsewhere.

To add a goal, use the + button in the Goals view. Type a title and press Enter. Goals are collapsible sections that group related tasks; only one Goal is expanded at a time.

Tasks and goals can be reordered by dragging the grip handle on the left side of each item. You can drag a task from one goal to another by dragging up to the goal. If you want to drop in a specific place in the goal, drag to the goal and hover until the goal expands, then drag to the desired target position.

By default, Wing stores your goals, tasks, and completed-task history in a private per-user file under .TASKS/ in the working directory, which is not shared through version control. Checking Share Plan in the Options menu moves that file into a shared TASKS/ directory that can be committed to version control and seen by other developers. When sharing is enabled you can also enable Show Other Developers' Plans, which appends their goals, tasks, and history in read-only form to the end of every tab in the Tasks tool. See Sharing Tasks via Version Control below for details.

Executing Tasks

Tasks can be executed directly from the plan by click on the cog icon. This sends the task to the default queue and starts running it. You can see its status relative to other running tasks on the Execute tab.

Queuing Tasks for Execution

It's also possible to queue tasks, rather than running them individually. This is done from the Q button in the top right of each task or goal, which also indicates the overall queue status of the task:

Green Q -- The task is assigned to a queue. Hover to see which one.
Red Q -- The task is not queued.

Click the Q button for a popup menu divided into three labeled sections: Queue (where to queue the task), New Session (launch options that start a fresh Claude Code process), and Reuse Session (options that keep the current process). The Queue section lets you assign the task to an existing queue, create a new queue, or leave the task unqueued. The other two sections set the task's session action, which controls both how the next Claude Code run for this task is started and what permission mode it uses.

New-Session options start a fresh Claude Code process just before the task is dispatched, swapping out any existing process on the queue's Claude Code instance. They give precise control over Claude's permission mode but lose the in-Claude conversation context that had accumulated on this queue:

Plan Mode -- Launch Claude with --permission-mode plan. Claude is in read-only exploration mode: it can examine the code and propose a plan via ExitPlanMode but cannot modify files. Good for research, investigation, and diagnosis tasks.
Auto Mode -- Launch Claude with --permission-mode auto (default). Claude auto-approves tool calls that its safety classifier considers low-risk and prompts only when the classifier flags something unusual. Requires a Claude Max, Team, or Enterprise account running a recent, sufficiently capable Claude model -- other accounts, or sessions using one of the lightweight models, will see Claude Code exit with an error at launch.
Accept Edits -- Launch with --permission-mode acceptEdits. Claude auto-approves file edits and common filesystem commands; other tools still prompt unless they are covered by project-level pre-approvals.
Edits Require Approval -- Launch with Claude Code's default permission behaviour. Every edit and unrecognized command prompts for approval unless the project pre-approves it.

Reuse-Session options keep the current Claude Code process running and do not change its permission mode; they are about what to do with the existing in-Claude conversation history before the next task text is sent:

Compact Context -- Inject /compact before the task text. Claude summarizes its history to reduce token usage while preserving key context. Useful for long auto-advance queues.
Full Context -- Keep the full conversation history. This is appropriate when consecutive tasks build on each other directly.

The default when you haven't explicitly picked one is Auto Mode (under New Session). Permission allow lists configured in Project Properties (project directories, VCS commands, custom directories, MCP tools) are layered on top of the selected mode -- they are not mutually exclusive with the session action. See :doc:`project-config` for details.

System Message: ERROR/3 (<string>, line 138); backlink

Unknown interpreted text role "doc".

To queue multiple tasks at once, use the Select button in the Plan toolbar to enable checkboxes, select the tasks you want, and use the batch Q button that appears to assign them all to a queue.

A goal's Q button queues or unqueues all of its pending tasks at once. It also defines the default queue and queueing state to use for newly added tasks.

Executing Queued Tasks

Switch to the Execute tab to run your queued tasks. This tab shows your queues at the top, with the selected queue's tasks listed below. The currently selected queue's name appears underlined, and blinking dots next to a queue's name indicate that it is currently running.

Each queue has a one-to-one relationship with a Claude Code tool instance and (at any given moment) a single Claude Code process. When you start a queue, it creates or connects to a dedicated Claude Code terminal, and tasks in that queue run sequentially in it. Tasks whose session action starts with "New Session" swap out the underlying Claude process before running, so "Plan Mode" / "Auto Mode" / "Accept Edits" / "Edits Require Approval" can be chosen per task; tasks with "Reuse Session" keep the current process running so conversation context is preserved between tasks (optionally compacted with /compact).

Queue controls (left to right):

Rename (pencil icon) -- Edit the queue name.
Changed Files (diff icon) -- Shown only when the queue has modified files during its running tasks. Clicking pops up a list of the files changed by tasks in this queue since they started. This data also scopes the queue's review and commit actions (see below). Files that are not currently tracked in version control are flagged with a [not in VCS] suffix and the secondary palette color. These are usually files Claude created as a side effect of a Bash command (e.g. coverage reports, generator output) that didn't go through the Write tool, so Wing's PreToolUse guard couldn't intercept. Decide per file whether to hg add and re-commit, add an .hgignore entry, or delete it before committing.
Auto-Advance (checkbox) -- When checked, the queue automatically sends the next task after the current one completes or is canceled. When set, a running queue without tasks will wait for new tasks to be added and start executing them immediately. This lets you run tasks as soon as they are ready, and you can walk away while the queue runs through all its tasks.
Start/Next (play icon) -- Send the next pending task. When the queue has not yet been started or was stopped, this starts the queue from the first pending task. When the queue is paused, it sends just the next task.
Pause -- Stop advancing after the current task finishes. The running task is not interrupted. The queue stays alive so you can use Next to manually advance one task at a time, or resume with auto-advance.
Stop -- Interrupt the current task (sends Escape) and reset it to pending. The queue returns to its initial state so Start is needed to begin again.
Remove (delete icon) -- Remove the queue entirely.

When editing a task's text on the Execute tab, a Done / Cancel bar appears below the editor so edits are never submitted accidentally. Press Enter to submit the task (and create another), click Done to save without creating a new task, or click Cancel to discard the edits (or remove a freshly added empty task).

Right-clicking a queue provides:

Bind to Claude Session -- Select which Claude Code instance this queue uses. This is useful for running the tasks in an already-establish context.
Go to Terminal -- Switch to the Claude Code tool showing this queue's terminal.

Task Lifecycle

A task moves through these states as it is executed:

Unqueued -- The task has been written but is not yet in a queue. Adding ... at the end of the task text keeps it unqueued, which is useful to prevent automatic queueing while you are still working on the task description. Remove the trailing ... or queue it from the Q icon when the task is ready.
Pending -- The task is in a queue and waiting to be executed.
Running -- The task has been sent to Claude Code and is being worked on.
Needs Review -- Claude Code has finished and the task's changes are ready for review.
Completed -- The task has been reviewed and accepted (or review was skipped) and committed. A timestamp shows when it was completed. The task is recorded in the History tab.

While a task is running, a Cancel link appears instead, which sends Escape to Claude Code to stop the task and moves it to Needs Review.

Two more links appear on the Execute tab for tasks that did not finish cleanly:

Move to Review -- Shown for a task left interrupted on the Execute tab. This promotes it to the Review tab so you can act on it there.
Reset -- Returns the task to the Plan tab, where it can be edited and/or re-queued later.

If a task is stuck in Running (for example, after a crash), it resets to Pending on the next load.

Select Mode

The blue mouse cursor icon in the top right of the Tasks tool views lets you enter selection mode, where each task and queue displays a checkbox for selecting it. The batch actions that appear depend on which tab you are on:

Plan -- Batch delete, set the queue used by all the tasks or goals, or split selected tasks into a new goal. The latter is useful for breaking a large goal into smaller pieces that can be worked on independently. A Select All / Deselect All toggle is available on the flat Tasks view.
Review -- Mark selected tasks complete without reviewing, or reset them back to Plan. A Select All / Deselect All toggle is available.
History -- Export only the selected history records when using Export History as Text or Export History as HTML.

Note that you can also drag tasks between goals, or drag a goal onto another goal to merge them, and use Undo any time to undo drags or deletions.

Reviewing Tasks

The Review tab collects all tasks that are awaiting review in one place. Tasks are grouped by the queue they ran in, with a header above each group showing the queue name and a summary of the number of files changed by tasks in that queue. From the header you can pop up the list of changed files, start a review scoped to just that queue's files, or commit them directly. Tasks rows within the group show a per-task changed-files icon when the task has its own tracked changes.

You can review one task at a time as you work, or let tasks pile up and review them in groups when it is convenient. A review always covers the whole queue, since multiple tasks may have changed the same file; Wing uses per-task snapshots to scope the review to the files the queue actually touched, so unrelated uncommitted changes elsewhere in the tree are excluded. You can also tell Claude to commit just specific files by interacting with it directly -- for example "commit all the source files but not the documentation, which I am still working on" -- and it will start a file-scoped review in Wing that skips the irrelevant changes.

Starting Review

Once one or more tasks in a queue reach Needs Review state, the queue header on the Review tab shows the following links:

Start Review -- Ask Claude Code to open Wing's diff viewer on the queue's changed files. Disabled when there are no uncommitted changes or while another review is already in progress; a second request is queued and runs automatically when the active review finishes.
Commit Without Review -- Ask Claude Code to commit all of the queue's changes without opening the diff viewer first.

Each individual task row on the Review tab shows:

Mark Complete -- Move the task to the History tab without reviewing or committing. When there are no uncommitted VCS changes at all (for example, an exploratory or research task), this shows as Done.
Reset -- Return the task to the Plan tab as Unqueued so you can edit it and re-run.
Cancel (only while running) -- Send Escape to Claude Code to stop the task.

You can also start a review from the REVIEW icon in the top right of the Claude Code tool: it appears once the session's queue has a task here on the Review tab and is scoped to that queue's changed files, just like Start Review above. A diff/merge dropdown beside it lists those files.

However you start a review, Wing opens its diff/merge viewer on the relevant changes, which lets you:

Navigate between changed files and individual hunks.
Use the pencil icon between hunks to add per-hunk comments as feedback for the agent.
Revert individual hunks you don't want to keep.
From the toolbar, finish the review with the green check mark, or reject the task with an overall comment using the toolbar's pencil icon.

The toolbar check mark normally commits the changes using the configured commit mode. If you have left any per-hunk comments, however, 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 pencil icon always sends the task back to Execute for iteration, regardless of whether per-hunk comments are present.

Task History

The History tab provides a record of completed tasks and commits, organized by goal, including also the run time and token consumption for the different tasks. This serves as an audit trail of the work that AI agents have done in your project.

Each goal appears as a collapsible section with a summary showing the number of tasks and total time spent. Within each section, entries are sorted with the most recent first and include:

Task entries -- Each completed task shows its completion timestamp, how long it ran, the tokens it consumed, the review outcome (if reviewed), and the full request text that was sent to Claude Code.
Commit entries -- Version control commits made through the review process are shown with the revision number, date, and full commit message.
Follow-up prompts -- If additional prompts were sent while a task was running (for example, to provide clarification or redirect the agent), these appear as separate entries alongside the original task.

Completed tasks are automatically removed from the Plan tab and recorded in the History tab, so the audit trail is not lost. Tasks that are explicitly deleted before completing are not recorded.

When Share Plan and Show Other Developers' Plans are both enabled in the Options menu, the History tab also shows completed tasks from other developers at the end of the list, below a divider.

Options Menu

The Options menu in the upper right of the Tasks tool provides:

Share Plan -- When checked, your goals and tasks are stored in a shared file that can be committed to revision control.
Show Other Developers' Plans -- When checked, goals, tasks, and history from other developers are shown in read-only form. Available only when Share Plan is enabled.
History Settings... -- Opens a dialog with a top-level Record History toggle and auto-clear thresholds (remove records older than a given number of days and/or keep at most N records per developer). A Clear All Now button removes all history immediately, and a checkbox controls whether these actions also apply to other developers' history. Thresholds are shared across developers when sharing is enabled.
Show History in Reverse Order -- When checked, the History tab shows the most recent entries first. Enabled by default. Hidden when history recording is off.
Export History as Text... / Export History as HTML... -- Export history records to a plain-text or styled HTML file. When selection mode is active with items checked, only the selected records are exported. Hidden when history recording is off.
Raise Claude Code on Execute -- When checked (the default), Wing raises the Claude Code tool and switches to the correct instance when a task starts running.
Track Queue Changes in Claude Code -- When checked, Wing keeps the current queue on the Execute page in sync with the current Claude Code instance: selecting a queue raises the Claude Code instance bound to it, and switching instances in the Claude Code tool selects the matching queue. Off by default.

Sharing Tasks via Version Control

Each developer owns exactly one plan file, identified by the email from your version control configuration (git config user.email or hg config ui.username). A display name is also extracted and recorded in the file's metadata.

When Share Plan is off (the default for new users), the file lives under a .TASKS/ directory in the Claude Code working directory and is ignored by version control. When Share Plan is on, Wing moves the file into a sibling TASKS/ directory, which is designed to be committed to version control so team members can see what work is planned, in progress, and completed. Each developer only ever writes to their own file, so multiple developers can commit task changes simultaneously without producing merge conflicts.

Queues are always stored privately in the per-user project file and are never shared, since they represent active execution state tied to local Claude Code instances. The TASKS/ directory is written only at commit time, not on every edit; the private .TASKS/ file is the authoritative local store and is updated continuously.

When Show Other Developers' Plans is enabled, the Goals and Tasks views display other developers' goals, tasks, and completed-task history in a read-only section below your own. These items use a distinct visual style (muted text and a colored header overlay) to distinguish them from your own work. The TASKS/ directory is watched for external changes, so updates from other developers appear automatically after they pull commits in, without restarting Wing.