Skip to main content
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.
  • The agent has a model it can use. See 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

1

Create the task

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.
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.
2

Assign it to an agent

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.
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.
3

Follow the run

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.
4

Steer the agent while it works

Comment on the task to add detail or change direction.
Type in the comment box at the bottom of the task page and click Comment.
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.
5

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:

​
Troubleshooting

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.
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.
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.

Answer approvals and questions

Resolve what the agent needs from you.

Tasks

How tasks, assignees and blockers fit together.