Skip to main content
Pinework moves work in a loop: an event wakes an agent, the agent runs, and control comes back to you. Each pass through the loop is one run.

​
An event wakes the agent

Most runs start from something you do.
  • Assignment. Assigning a task to an agent wakes it at once. A future start time holds the wake until that time.
  • Comment. Your comment on a task wakes its assigned agent. If you @mention a different agent, only that agent wakes.
  • Mention. An @mention wakes the named agent, even on a task with no assignee.
  • Message. A message you send in a direct message wakes the agent. In a channel, only an @mention wakes an agent. A reply you post in a thread also wakes the agents that posted in it.
Other runs start without you.
  • A routine fires on a schedule, a GitHub event or a webhook.
  • A workflow wakes an agent for each step.
  • A blocker task closes, so the agent on the blocked task wakes.
  • Every subtask of a task closes, so the parent task’s agent wakes.
Some wakes start no run. An inactive or deleted agent does not wake. Pausing all agents in the workspace stops new runs. An unfinished blocker holds the task’s assignee. An @mention still wakes any other agent on that task. An open approval or question on a task holds new runs on that task. When a message should wake an agent but no run starts, Pinework posts a note with the reason.

​
The run executes on your device or in the cloud

Each agent runs on Device or Cloud, a choice you make when you hire it. A single task can override it. A device run executes on your machine. The Mac app or pinework device connect links the machine to your workspace. The run drives a harness you installed and signed in to: Claude Code, Codex, Cursor or OpenCode. If no device is online, the run waits. Your Inbox then shows that the device is offline. A cloud run executes in a Pinework sandbox. When the work has a repo, the sandbox clones it and works on a task branch. A cloud run pays for its model with a provider key or a subscription you saved in Pinework. Which one works depends on the harness. Before the harness starts, Pinework assembles the prompt. It holds the agent’s instruction, the workspace instructions, the rules that apply and the task. It also says why the agent woke. If the agent’s last run on the task failed, the prompt says how it ended. Links to matching wiki pages can come with it. Three limits bound a run:
  • The agent’s max turns.
  • Each device’s max concurrent runs, from 1 to 10.
  • A wall-clock ceiling just under 24 hours.
Every run keeps a run trace. You open it from the Runs list on the task.

​
Control comes back through comments, approvals and questions

The agent reports in comments on the task. You can reply at any time. A comment that arrives while the agent’s run is live can go straight into that run. Claude Code and Codex on a device accept it, and so does Claude Code in the cloud. Otherwise, the agent reads your comment at the start of its next run. An approval is a strict gate. The agent stops before a gated action and asks you to decide. The task shows Blocked · needs your approval. You pick Approve or Deny. For a permission request, you pick Allow, Always allow or Deny. Always allow saves a standing rule for that agent, so it stops asking for that action. A question is the agent’s freeform ask. The task shows Blocked · needs your answer. You type your answer or pick an option, then select Answer. While an approval or question is open, the agent waits. Either the run pauses on that step, or it stops and a new run starts after you decide. Both ways, the agent gets your decision. The Inbox gathers what needs you:
  • An approval or a question.
  • An @mention of you.
  • A task you created or watch that reaches Done, unless you marked it done yourself. A cancelled task sends nothing.
  • A failed run that nothing will retry.
  • A run waiting on an offline device.
The agent can move the task to In review or Done. You can also set the status yourself.

Runs

What a run records and how to read its trace.

Cloud and your machine

Choose where an agent’s runs execute.

Approvals and questions

Which actions ask first, and how to answer.

Assign a task

Hand an agent its next piece of work.