Editing and cancelling tasks

Once a task is created you can update its details at any time — no need to cancel and re-create. This page covers every edit surface: the web app and the ch task edit command for title, priority, description, and due date; ch task field for per-task schema fields; and the status transitions that close, cancel, or reopen a task.

Editing native fields with ch task edit

ch task edit updates a task’s title, description, priority, and due date — the fields every task type has in common, regardless of workflow. Pass one or more flags; only the fields you pass change:

ch task edit <taskId> --title "Renamed title"

Each flag also works from the web app, described in the sections below. Use whichever is convenient — both write to the same task.

Editing the title

From the web app, open the task. The title appears at the top of the task detail page as an editable field — click it to begin typing, then click away or press Enter to save. The change takes effect immediately.

From the CLI:

ch task edit <taskId> --title "Renamed title"

Editing priority

From the web app, priority is shown in the detail panel on the task page. Click the priority badge to open a dropdown and select high, normal, or low. CodeHerder saves the change immediately and re-sorts the task in the queue.

From the CLI, --priority accepts exactly high, normal, or low:

ch task edit <taskId> --priority high

Editing the description

From the web app, the Description section appears below the task metadata on the detail page. To add or change it, click the Edit (or + Add) button, write your markdown in the editor that appears, then click Save. To discard your changes, click Cancel.

From the CLI, per house convention, pass the body with --from-file rather than inline (this avoids shell-escaping problems with long or multi-line text):

ch task edit <taskId> --description --from-file description.md

Setting or clearing the due date

--due-at takes an RFC 3339 timestamp:

ch task edit <taskId> --due-at 2026-08-01T00:00:00Z

To clear a due date, pass an empty string:

ch task edit <taskId> --due-at ""

Editing per-task fields (acceptance criteria, repro steps, and others)

The fields above are the same for every task type. Per-task schema fields are different: which ones exist depends on the task’s type — acceptance criteria for stories and features, reproduction steps for bugs, proposal/design/spec for epics, and so on. Use ch task field, not ch task edit, to update these from the CLI at any time:

ch task field <taskId> <fieldKey> --from-file <path>

For example, to revise the acceptance criteria on a story:

ch task field <taskId> acceptance --from-file updated-criteria.md

For full details on field keys, which fields each type requires, and how to read back a field’s current value, see Writing tasks an agent can build.

This page covers editing the task itself. To correct a comment already posted on a task — a workspace-owner, web-app-only action — see Collaborating.

Completing a task early

Normally a task walks its full pipeline — plan, code, review, and so on — one stage at a time until it reaches done. But sometimes the work is already finished, or the rest of the pipeline no longer applies, before the task gets there on its own. In that case you can move the task straight to done from whatever stage it’s currently on, without walking the remaining stages.

Done vs. cancelled: these are the two ways a task’s active work ends, and they mean different things. Use done when the work was completed successfully — even if it finished early, outside the normal pipeline order. Use cancelled when the task is being abandoned without completing the work; cancelling always requires a reason (see below). Picking the right one keeps your task history honest about what actually happened.

Completing early doesn’t skip the checks that normally gate a close: the current stage’s required field must still be filled, every item on the task’s acceptance-criteria checklist must still be ticked, and any child tasks must still be finished or cancelled first. If one of those is unmet, the jump to done is rejected the same way a normal advance to done would be.

From the web app

Find the status dropdown — it’s on the task’s own page, on each row of the Tasks list, and on each card on the board view — and select → Done.

From the CLI

ch task status <taskId> done

No --reason is required to complete a task — unlike cancelling, below.

Cancelling a task

From the web app

Open the task, find the status dropdown, and select → Cancelled. A dialog appears asking for a reason — enter a brief explanation and click Confirm. The reason is posted as a comment on the task so there is a record of why the work was stopped.

From the CLI

ch task status <taskId> cancelled --reason "Superseded by task 019abc"

The --reason flag is required when cancelling — the server rejects the request without one. Keep the reason short and specific so future readers understand why the work stopped.

Cancelled is a terminal status: the task is no longer active and agents will not pick it up. From cancelled, the only status the dropdown offers is in_progress — see below for what that does and doesn’t do.

Archiving a finished task

Archiving is how you move a finished task out of the way for record-keeping. It drops out of the default Tasks list and board view, but it isn’t hidden forever — ch task list --all (and the equivalent filters in the web app) still include it, and opening it directly always works.

Archiving is reachable from done or in_progress only — a task still working its way through review, merge, or verify has to finish first. There’s no separate archive command or button: you archive a task the same way you change any other status.

From the web app

Find the status dropdown and select → Archived.

From the CLI

ch task status <taskId> archived

Archiving is reversible — see below.

Reopening a cancelled or completed task

Which status a task can go back to depends on how it finished. A cancelled or archived task has exactly one way back: in_progress. A done task has two: in_progress reopens it, or → Archived files it away instead (see above). Completing a task and archiving it are separate steps, both reachable from done.

What reopening to in_progress gets you depends on the task’s type.

For an initiative or an epic, this is exactly right: in_progress is that pipeline’s normal holding stage, so the container simply returns to “children are being worked” and closes again once they finish. See How work flows for the container pipeline.

For a story, feature, bug, or task, in_progress is not a stage in that type’s pipeline. Reopening still moves it there, so the task shows as active again everywhere you look — but no agent starts on it, and it can’t be moved back to plan or code to actually continue the work: there’s no route back into the pipeline. Parking it at blocked doesn’t help either — unblocking returns a task to the stage it was at when it was blocked, which is in_progress again. The only way out is to close it again, by completing it or cancelling it. In practice, reopening one of these four types closes it again rather than resuming it — use the alternatives below instead.

From the web app

Open the task, find the status dropdown, and select → In progress.

From the CLI

ch task status <taskId> in_progress

If a finished story, feature, bug, or task needs more work

Don’t reopen it — file a new task for the follow-up instead, so an agent can actually pick it up:

ch task create --title "Follow-up: …" --type story --parent <parentId>

and reference the original task in the new one’s description. If you want to record that the follow-up builds on the original, --depends-on against a cancelled or archived original is safe to use — a dependency clears once its upstream finishes, no matter how, so it won’t hold the follow-up back. It just won’t gate anything either, since the original is already finished. See Task dependencies for the full model.

If the task hasn’t reached a terminal status yet — it’s still sitting at review or verify — send it back for another build round instead of letting it finish and reopening it afterward:

ch task status <taskId> code --reason "…"

See Sending work back for rework in Reviewing an agent’s work.

---

For the full list of pipeline stages and how tasks move between them, see How work flows. To route or assign an active task to a specific agent or person, see Assigning and claiming work.