CodeHerderSearch⌘KRequest access →

Editing and cancelling tasks

How to edit a task's fields, complete it early, or cancel, archive, and reopen it.

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 ch task edit — the one command that writes any field on a task, whether it’s a column every type shares (title, priority, description, due date, base branch) or a per-task field like acceptance criteria. ch task field reads a field’s current value back. This page also covers the status transitions that close, cancel, or reopen a task.

Editing a task with ch task edit

ch task edit takes one flag per field you want to change, native or per-task. Only the flags you pass are updated:

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

Each flag accepts its value three ways: inline as shown above, from a file with --<flag>-file <path>, or from stdin with --<flag>-file - (or a bare - as the value). The one exception is --base-branch, which takes an inline value only. There’s no standalone --from-file flag on ch task edit itself. A single call can touch several freeform fields at once, so the file and stdin forms are always tied to the flag they belong to:

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

Get a flag name wrong and ch task edit tells you what it accepts. An unrecognised flag lists every flag it accepts, plus every field key this task’s type declares. A near miss such as --name gets a suggestion instead, for example “did you mean –title?”.

Of the native columns below, title, priority, description, and base branch also have their own controls in the web app, described in the sections that follow — use whichever is convenient; both write to the same task. The due date is the exception: it has no web-app control, and is set, cleared, and viewed from the CLI only (see below).

ch task edit also takes --cap/--clear-caps and --device-cap/--clear-device-caps to replace a task’s required capabilities wholesale — see Capabilities for what a capability label means and when to reach for a device capability instead of a task one.

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. Press Enter or click Save to save your change, or press Escape or click Cancel to discard it. Clicking elsewhere on the page doesn’t save or discard anything — the field stays open until you use one of those four. A blank title is refused with “Title cannot be empty.” and the field stays open.

From the CLI:

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

Editing priority

From the web app, the task page has a Priority row that shows High, Normal, or Low with a pencil icon. Click it to open a select. Picking a value with the mouse saves it at once. With the keyboard, the arrow keys only change the choice. Press Enter, or leave the field, to save it, or press Escape to put the old value back.

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

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. Click Edit (or Add, if there’s no description yet), write your markdown in the editor that appears, then click Save changes or press Ctrl+Enter (Cmd+Enter on a Mac). To discard your changes, click Cancel or press Escape. A task with no description shows “No description yet.”

Paste a record’s ID into the description and the web app turns it into a titled link. See Linking to tasks and other records.

CodeHerder keeps an unsaved draft. If you reload the page, the editor reopens with “Draft restored from your last visit.” If you cancel a changed draft, a “Draft discarded.” notice appears with an Undo button. See Unsaved changes and drafts for the details.

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

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

Setting or clearing the due date

From the CLI only — there’s no web-app control for a task’s due date, and it isn’t shown anywhere in the web app either. A scheduled task can give each task it creates a due date through its due offset.

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

Changing the base branch

From the web app, the task page has an editable Base branch row alongside the task’s other details — click it to set or clear the value. When no base branch is set, the row shows the repo’s default branch. Saving an empty value clears it.

From the CLI:

ch task edit <taskId> --base-branch release/2.1

Pass an empty string to clear it and fall back to the repo’s default branch:

ch task edit <taskId> --base-branch ""

While the task has a live sandbox, its base branch is fixed. The worktree is already checked out from wherever it started, and CodeHerder refuses the change:

baseBranch cannot change while the task has a live sandbox; the worktree is already checked out from the current base

See Choosing a task’s base branch for what a base branch is, how CodeHerder resolves one when a task doesn’t set it, and what happens once work has started.

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

The fields above are the same for every type. Per-task 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. Run ch task fields <taskId> to see this task’s own list.

Write one the same way as any native field, by passing it as a flag named after its key:

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

To tick one item, change its proof stage, or defer it, use ch task acceptance. See Work on one item from the CLI.

Read the current value back with ch task field:

ch task field <taskId> acceptance

ch task fields <taskId> ends with a hint line when any field has earlier versions: some fields have prior versions: ch task fields versions <id> <key>.

ch task field is a frozen alias for the show op of the nested ch task fields child collection — see Managing a record’s child collections. ch task edit --<key>-file is the canonical writer; ch task field <taskId> <key> --value <text> still writes too, but reach for it only when the field’s key clashes with one of the CLI’s own global flag names (see Customising workflows).

For full details on field keys and which fields each type requires, see Writing tasks an agent can build.

When a field can be written

Some per-task fields only accept a write while the task sits at the stage that produces them. ch task fields <taskId> shows, for every field this task’s type declares, whether it’s required and whether it’s writable right now:

KEY           TYPE       REQUIRED         WRITABLE                  VALUE (preview — see `ch task fields show` for the full body)
acceptance    checklist  required@plan    writable                  - [ ] Login form accepts… [2 outstanding]
plan          markdown   required@plan    locked (writable@plan)    (unset)
artifact      markdown   required@code    locked (writable@code)    (unset)
verification  markdown   required@verify  locked (writable@verify)  (unset)

On the built-in story and feature types, acceptance is writable at any stage. A bug follows the same shape, with repro in place of acceptance — and no plan field at all. plan, artifact, and verification are more restricted: plan only while the task is at plan, artifact only at code, verification only at verify — each opens at the one stage that produces it and locks again once the task moves past it. A workspace that has customised its story or feature workflow may not carry a plan field; this sample reflects the built-in one.

Write to plan, artifact, or verification at any other stage and ch task edit refuses, naming the stage that does accept it — including after the task has moved past it, not just before it arrives:

edit task: HTTP 409: field "artifact" cannot be written while the task is at stage "review"
  hint: this field is writable only at stage(s): code

The web app shows the same rule as a lock icon next to a markdown or checklist field that isn’t writable at the task’s current stage. Hover it to read “Writable only at: .” A checklist field like acceptance also carries a ticked/total progress badge once it has items, such as 2/5, plus “(N deferred)” for unticked items whose proof stage is still ahead. A checklist field with no items shows No checklist items.

Sending a task backward — a rejected review, say — can archive a field’s current value and reset it, so whoever picks the work back up can still see what was there before. ch task fields versions <taskId> <key> reads that history; it’s read-only, with no way to restore an old value. The web app shows the same history under a field as a “Show N prior versions” disclosure, also read-only. See Version history and going back for how a task field’s history compares with a workflow’s, a stage’s, a wiki page’s, a task’s own definition, and a stage rubric.

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.

A task’s own definition history

Separately from its per-task fields, CodeHerder keeps a saved history of a task’s own definition — its title, description, type, status, priority, required capabilities, required device capabilities, due date, parent, workflow override, requested agent, cost budget, and base branch. Every edit that changes one of those saves a new version automatically; you don’t have to do anything to turn it on.

ch task versions <taskId>
ch task versions <taskId> --version 5

ch task versions <taskId> lists the saved versions newest first, paged with --limit and --cursor. Add --version N to read one version’s full definition instead of listing. This is CLI-only and read-only. There’s no app panel for it and no way to restore an old version. See Version history and going back for what counts as a change and what the version number actually means.

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 — including one you deferred to a later stage — and any child tasks must still be finished or cancelled first. Any check the current stage sets itself still applies too, such as a required verification or an approval. 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 Move to 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 Move to Cancelled. A Reason required dialog appears — enter a brief explanation and click Change status. 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. Without one, the server answers “transition to ‘cancelled’ requires a comment explaining why”. --reason-file <path> and - also work. The dialog appears for any status the workflow marks as needing a reason, and cancelled is the built-in default. 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. Whatever its type, the dropdown on a cancelled task is disabled. Hover it to read “This is a terminal status — no further transitions are available.” The status dropdown and ch task status can’t bring a cancelled task back. To pick the work up again, reopen it (see below).

Archiving a finished task

Archiving is how you move a finished task out of the way for record-keeping. The default Tasks list and board view already hide finished tasks, so archiving doesn’t change what you see there — it just marks the task done-and-filed. ch task list --all (and the equivalent filters in the web app) still include an archived task, and opening it directly always works.

For a story, feature, bug, or task, archiving is reachable only from done — the task still working its way through review, merge, or verify has to finish first. Initiatives and epics can also archive from in_progress, since that’s their own normal holding stage. So can a story stranded there (see below). 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 Move to Archived.

From the CLI

ch task status <taskId> archived

Archiving is reversible — see below.

Reopening a cancelled or completed task

ch task reopen sends a done, cancelled, or archived task back to an earlier stage in its pipeline. An agent can then pick up the work instead of you starting over. It also works on a task that’s still active, along any backward edge — for the common case of sending a task at review or verify back to code for another build round, see Sending work back for rework in Reviewing an agent’s work.

ch task reopen <taskId> <stage> --reason "why this needs another pass"

Reopening is the only way out of a finished status. The status dropdown and ch task status never move a done, cancelled, or archived task, except that a done task can still be archived. The refusal also names the way out. For example, ch task status <taskId> code on a done story answers transition from done to code is not allowed (...), followed by to reopen, use ch task reopen <id> code --reason-file <f>. If the stage you named is not one the task can reopen to, the refusal lists the stages it can reopen to.

Use --reason-file <path> for a longer explanation. The reason is required — the command refuses without one. CodeHerder stores it as a comment on the task, and the next agent reads it as part of its brief.

Only a human can run this — an agent that tries gets a permission error. The web app has its own control too: open the task and check the More menu next to the status dropdown. On a finished task it reads Reopen; on a task still active at an earlier stage it reads Send back. The item shows only when the task has stages to go back to. Both open a panel with a stage picker (“Reopen at” or “Send back to”) and a required Reason field. The buttons read Reopen task and Send task back. Both warn that output fields from the target stage onward are cleared for a fresh attempt (their old values are kept as versions, and a required checklist comes back unticked with its text intact).

Which stages you can reach depends on the task’s type:

  • Story, feature, or bug — any of todo, plan, code, review, merge, verify.
  • The lightweight task type — todo, code, or merge.
  • Initiative or epic — todo, planning, or in_progress. in_progress is a genuine target here: it’s that pipeline’s normal holding stage, so the container returns to “children are being worked” and closes again once they finish. See How work flows for the container pipeline.

You’re not limited to the stage immediately before the one the task finished at. A story that reached verify before it closed can reopen straight back to plan. Run ch task show <taskId> and read its reopen targets row for the exact set this task can reach right now — that’s the same list the server checks. Naming a stage the task can’t reach is rejected, and the error names the ones that are.

Reopening a task that has unfinished upstream tasks

If the task depends on an upstream task whose dependency has not released, a reopen into a working stage such as plan or code is refused with “task has unmet upstream dependencies; it will proceed automatically once they land”. Reopen it at todo instead, or wait until every dependency releases. An initiative or epic can reopen at in_progress regardless. See Task dependencies.

A task stranded at in_progress

For a story, feature, bug, or task, in_progress is not a stage in that type’s pipeline — it’s the holding stage for initiatives and epics while their children work, and CodeHerder refuses to move one of these four types there directly. If you’re looking at a task that got left at in_progress some other way, reopen it straight into a real stage:

ch task reopen <taskId> code --reason "picking this back up"

There’s no need to cancel it first. Blocked has its own way out — unblocking a task returns it to the stage it was working when the blocker was filed, so it never needs this treatment.

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

Reopen it when the work is a continuation of the same task — that’s exactly what the command above is for. File a new task only when the follow-up is genuinely separate work, not as a stand-in for reopening:

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

A story’s parent must be an epic, so leave --parent out if the original had none. 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 finished upstream always releases its dependency, no matter how it finished, 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.

For the length limit on each field, see Field limits.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close