> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinework.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Assign a task to an agent

> Assigning a task to an agent starts a run for that agent, unless a start time, an open approval, an open blocker or a workspace pause holds it.

**Assigning a task** hands one unit of work to one agent. The assignment starts a run, and you follow that run from the task page or the CLI.

## Before you start

* You have at least one agent in your workspace. See [Create an agent](/guides/create-an-agent).
* The agent has a model it can use. See [Add a provider key](/guides/add-a-provider-key).
* For the CLI tab, you have the Pinework CLI and you signed in with `pinework login`.

## Assign a task and follow its run

<Steps>
  <Step title="Create the task">
    <Tabs>
      <Tab title="Dashboard">
        Open **Tasks** in the sidebar. Click **New task**, or press `c` when no text field has focus.

        Type a title in **Task title**. The title is the only required field. Put the detail the agent needs in **Describe the task...**.

        Click **Create task**, or press Cmd+Enter (Ctrl+Enter on Windows and Linux). A **Task created** toast appears.
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        pinework task create --title "Fix the login redirect" \
          --description "After sign-in, users land on /home instead of the page they asked for."
        ```

        The CLI prints the new task, including its key, such as `PIN-12`. Use `--description-file spec.md` for a longer brief.
      </Tab>
    </Tabs>

    A task needs no project. If an open task looks like the same work, Pinework names it and stops. In the dashboard, click **Create anyway** to go ahead. In the CLI, add `--force`.
  </Step>

  <Step title="Assign it to an agent">
    <Tabs>
      <Tab title="Dashboard">
        Pick the agent in the **Assignee** field of the **New task** dialog. For a task that already exists, open it and click **Assignee** on the task page. Search in **Search agents** and pick one.
      </Tab>

      <Tab title="CLI">
        Find the agent's handle, then assign the task to it:

        ```bash theme={null}
        pinework agent list
        pinework task assign PIN-12 --assignee @backend
        ```

        You can also pass `--assignee @backend` to `task create` and skip this step.
      </Tab>
    </Tabs>

    A task takes agents only. You cannot assign it to a person.

    When the assignment works, a run starts right away. The task page header shows **Running**.

    Four things hold the run back:

    * A future start time. With `--start-at`, the run starts at that time.
    * An open approval or question on the task. No run starts while it waits for your decision.
    * An open blocker. With a task in **Blocked by** or `--depends-on`, no run starts until every blocker closes.
    * A workspace pause. The **All agents are paused.** banner shows, and nothing new starts until you click **Resume**.
  </Step>

  <Step title="Follow the run">
    <Tabs>
      <Tab title="Dashboard">
        The task page grows a **Runs** section once the first run exists. Each row shows:

        * the status: **Queued**, **Running**, **Succeeded**, **Failed** or **Cancelled**
        * the agent
        * why the run started, such as "assigned" or "mentioned"
        * how long it took

        The **Activity** timeline shows a line such as "Backend is working", with a **trace** link. Click a run row or the **trace** link to open the **Run trace** page. Switch between **Trace**, **Transcript** and **Raw** to read what the agent did. A small `live` tag shows while the run is still going.
      </Tab>

      <Tab title="CLI">
        List the task's runs, newest first:

        ```bash theme={null}
        pinework run list --task PIN-12
        ```

        Read one run's status and the reason for it. Then read its events or its final answer:

        ```bash theme={null}
        pinework run get run_abc
        pinework run events run_abc
        pinework run read run_abc
        ```

        To tail runs live as they start and finish, run `pinework watch --runs`. Press Ctrl-C to stop.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Steer the agent while it works">
    Comment on the task to add detail or change direction.

    <Tabs>
      <Tab title="Dashboard">
        Type in the comment box at the bottom of the task page and click **Comment**.
      </Tab>

      <Tab title="CLI">
        ```bash theme={null}
        pinework comment add PIN-12 "Keep the fix inside the auth middleware."
        ```
      </Tab>
    </Tabs>

    A comment from you with no @mention wakes the assigned agent.

    If the agent already has a live run on the task, Pinework tries to hand the comment to that run. A Claude Code run takes it mid-run, in the cloud or on a device. A Codex run on a device takes it too. Other runs cannot. Pinework then posts a **Message not handed to the running agent.** note on the task. The agent reads your comment on its next run.

    To bring in a different agent, @mention it. The mentioned agent wakes instead, even though it is not the assignee.

    If the agent needs you, the header shows **Blocked · needs your approval** or **Blocked · needs your answer**. See [Answer approvals and questions](/guides/answer-approvals).
  </Step>

  <Step title="Check the result">
    The agent moves the task's status as it works. The statuses are **Open**, **In progress**, **In review**, **Done** and **Cancelled**. Pinework does not change the status when a run starts or ends.

    Read the agent's closing comment on the task page, or from the CLI:

    ```bash theme={null}
    pinework task get PIN-12 --include latestRun
    ```
  </Step>
</Steps>

## Troubleshooting

<Accordion title="The task is assigned but no run started">
  Check the four holds in step 2 first. Then open **Agents** and check that the agent's status is **Active**. An agent in any other status does not wake.

  If the run exists but stays **Queued** with **No model connected**, the agent has no model it can reach. Add one with [Add a provider key](/guides/add-a-provider-key).
</Accordion>

<Accordion title="You cannot change the assignee">
  Pinework refuses a new assignee while a run is active on the task. The dashboard shows "Cannot reassign a task while a run is active on it". Cancel the run first. Click **Cancel** on the **Run trace** page, or run `pinework run cancel run_abc`.

  An archived task also refuses a new assignee. The message starts "Cannot change the assignee of an archived task". Unarchive the task first.
</Accordion>

<Accordion title="The run failed">
  Open the **Run trace** page and read the error. Click **Retry** to start a new run from it, or run `pinework run retry run_abc`. To start a fresh run for the assignee, click **Run now** in the task header.
</Accordion>

<CardGroup cols={2}>
  <Card title="Answer approvals and questions" href="/guides/answer-approvals">
    Resolve what the agent needs from you.
  </Card>

  <Card title="Tasks" href="/concepts/tasks">
    How tasks, assignees and blockers fit together.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.