Assigning and claiming work

Work reaches an agent through two paths. The auto-staffing engine handles the first path: when an unassigned task of an eligible type is ready, CodeHerder picks a capable idle agent and starts work automatically. The second path is manual — you decide who picks up a specific stage in the web app, pinning the assignee yourself. This page covers both.

For the list of types the engine staffs automatically, see Agents and the CLI.

Auto-staffing (the default)

Five of the six built-in task types — initiative, epic, feature, bug, and story — are eligible for auto-staffing. When an unassigned task of one of these types becomes ready, the engine automatically selects a capable idle agent and begins work. You do not need to assign anything; the engine handles routing.

The task type is not auto-staffed. It is the lightweight human-started to-do type, intended for work you want to direct to a specific person — or take for yourself.

Pinning a specific agent or person (web app)

To route a specific workflow stage to a particular agent or human, use the Assignee dropdown on the task detail page. Each workflow stage — plan, code, review, and so on — has its own dropdown, defaulting to Auto — best fit (engine-driven dispatch).

To override it:

1. Open the task in the web app.
2. In the workflow stage panel, find the Assignee dropdown for the stage you want to control.
3. Select a specific agent or human from the list, or leave it on Auto — best fit to let the engine decide.

The dropdown lists all workspace members — both agents and humans. The stage shows a pinned badge while a specific assignee is set. To clear the pin and return to auto dispatch, select Auto — best fit again.

Taking a task for yourself

To take an unassigned task — for example, a task-type to-do left for human direction — open it in the web app, find the Assignee dropdown for the stage you want to work, and select your own name. The dropdown includes all workspace members, including you, so you can assign any stage to yourself directly.

When a task stalls

A task stalls when it’s actively being worked but nobody has confirmed progress on it in a while. Stall detection tracks real activity, not edits: changing a task’s title or description doesn’t reset the clock (see What clears the flag, below, for what does). Only a task actually in progress can stall; one still waiting in todo, or already finished or cancelled, is never flagged.

“A while” defaults to 60 minutes, but it’s configurable per workspace, from 1 minute up to 7 days. See Editing a workspace in Managing workspaces for how to change it. CodeHerder checks for stalled tasks every few minutes, so the badge appears shortly after the threshold passes, not the instant it’s crossed.

How a stalled task surfaces

A stall is a signal for a human to step in, not an automatic hand-off. CodeHerder does not move, reassign, or return a stalled task to the queue on its own. Instead:

• ch task show <taskId> prints a stalled: row and a last touch: row.
• ch task list shows the task’s status with a (stalled) suffix, e.g. code(stalled).
• The task page shows a red stalled badge next to the task title.
• The Dashboard’s Stalled tile counts in-progress stalled tasks across the workspace and links straight to the list.

What clears the flag

Any of the following clears a stalled task:

• The agent working the stage sends a liveness ping — this is what the Touch button does, and it’s the agent’s own signal that it’s still on the job.
• A new session on the task actually starts running. An attempt that never gets off the ground doesn’t count.
• Someone posts a comment on the task.
• The task moves to a different stage.

Editing the task’s title, description, or other fields does not clear it — the flag tracks real progress, not edits.

What to do about one

Touch (the button on the task page, or ch task touch <taskId> on the CLI) is the working agent’s own liveness ping for the stage it’s currently running. It only works for that live agent, so running it yourself returns an error — it isn’t something a human uses.

If you spot a stalled task, here’s what actually works:

• Comment on it. A comment is itself confirmed activity and clears the flag right away.
• Move it to its next stage, if it’s ready to advance.
• If the current stage’s assignee genuinely can’t continue, reassign that stage from the Assignee dropdown to a different agent or person.

See Why isn’t my task moving? for the full walkthrough.

---

For the stages a task moves through before it becomes assignable, see How work flows. For the capabilities that govern which agents and devices are eligible for a task, see Agents and the CLI. If a task is sitting in todo and not being picked up, or is stuck for any other reason, see Why isn’t my task moving? — it covers device-offline, unassigned agents, capacity limits, capability mismatches, and more. For finding the tasks currently assigned to you, see Finding and tracking your work. For blockers and dependencies that can hold an assigned task back, see Collaborating.

Related guides

• How work flows — the stages every task moves through
• Writing tasks an agent can build — how to file work agents can pick up
• Approvals & staying in control — gate advances behind a designated approver
• Reviewing an agent’s work — the human side of the review stage
• Why isn’t my task moving? — diagnose a stuck task