---
title: Tasks

sidebar:
  label: Tasks
  order: 0
---

A **task** is a piece of work you ask Metaphor to handle.

It keeps your request, the agent's work, and the resulting code changes together in one place.

Use a task to fix a bug, build a feature, update documentation, or make any other change to your project.

## What's in a task

Every task has:

- **Request** — what you want Metaphor to do
- **Repository** — the GitHub repository you want the agent to work in
- **Worktree** — an isolated working directory created for the task
- **Agent** — Claude Code, Codex, or another agent Metaphor can coordinate
- **Session** — the agent's progress, Git changes, and usage for the run

Tasks can start from the desktop app or Slack. See [Slack](/slack).

## How tasks run

1. **Created**

    You submit a request. Metaphor records the task and prepares an isolated
    [worktree](/worktree).

2. **Running**

    The agent works inside the task's worktree. You can follow the session and
    inspect the changes as it works.

3. **Verifying**

    With Handoff on, Metaphor verifies the work against the task's
    [checks](/checks). If a check fails, Metaphor sends the relevant context back
    to the agent so it can continue working.

4. **Ready**

    Once the work is ready, what happens next depends on
    [Handoff](/handoff). With Handoff on, Metaphor commits and pushes the
    changes and creates a pull request.

## Parallel tasks

You don't have to finish one task before starting another.

Each task gets its own worktree, so multiple tasks can work on the same
repository without mixing their changes.

For example, one task could fix a bug while another adds a new feature.

Learn more about [Worktrees](/worktree).

## Usage

Each task records token usage and session statistics, so you can see what a run used and how long it took.

## Review the result

The task keeps the history of the work, while the pull request brings the resulting changes together for review.

With Handoff on, Metaphor creates the pull request for you. You can review the changes, request follow-up work, or merge when you're ready.

Learn more about [Handoff](/handoff).