Skip to content

Docs

The edit tool

How an agent changes an item's title, list, section, fields, needs, notes or options, moves it, deletes it and brings it back.

edit changes one item. Its title is Change or delete an item, and its description, as the agent reads it:

Change an item's list, title, section, fields, needs (it's blocked until they're done), notes, a question's options, or its place in the list. delete only when the human asks, or calls the work off, or for a duplicate you made; restore brings it back.

Arguments

Argument Type What the agent is told
key string, required B-k3f9@7c: the key, with the version you read (your own changes don't make it stale)
title string
list string moves it, with its subtasks, to another list: task, request, question or one of the project's own; its key takes that list's letter, and the old key still finds it
section string the heading to move it under; made if missing (the section tool renames a heading)
fields object fields to set, e.g. {"prio": "high"}; "" removes one; reuse the words in use, and leave status, needs, claims and done to Hamloy. for: who it is for, only when the human says (a request or question is the human's already): you for the human, an agent (claude, codex, cursor) or several (claude or codex)
needs array every key it waits on (replaces the old ones); [] for none
summary string one short line, the TLDR others read in the list; the notes hold the full detail
add_note string text to add under the item, after its notes; give summary too if it has none yet
notes string replaces all its notes (a question keeps its options); "" removes them; give summary too if it has none yet
options array a question's options, all of them in their new order (replaces the old ones): add, reword, reorder or drop one. An option keeps being recommended or assumed while its words stay, or when it is reworded in its own place
recommended integer the option you recommend now (1-based), 0 for none
before string a key in the same list: put this item just before it
after string a key in the same list: put this item just after it
delete boolean
restore boolean bring back a deleted item, where it was

What it does

  • Several changes go in one call. The reply is the item's line as it is now, with its new version.
  • The key carries the version the agent read. If someone else changed the item since, the change is refused and the agent reads it again.
  • list moves an item to another list. It takes that list's letter, and its old key still finds it. A claimed task moved to questions is let go, as a question is yours to decide.
  • A deleted item can come back with restore. Deleting what another agent is on tells that agent it's gone. Work that waited on it stops waiting.
  • Every change is in the item's history, and you can undo it on the board.

Calls and replies

Fields, then what it waits on, then a note with a summary. In Claude Code:

⏺ hamloy - Change or delete an item (MCP)(key: "B-txqk", fields: {"prio":"medium","due":"2026-10-20"})
  ⎿  B-txqk@3   Show the streak on the home-screen widget  due:2026-10-20 prio:medium

⏺ hamloy - Change or delete an item (MCP)(key: "B-txqk", needs: ["B-u5oh"])
  ⎿  B-txqk@4   Show the streak on the home-screen widget  due:2026-10-20 prio:medium  (waits on B-u5oh)

⏺ hamloy - Change or delete an item (MCP)(key: "B-txqk", summary: "Same number as the home screen, read from the shared store", add_note: "The widget reads the app group's store; no network.")
  ⎿  B-txqk@6   Show the streak on the home-screen widget  due:2026-10-20 prio:medium  (waits on B-u5oh)
           Same number as the home screen, read from the shared store

Codex renamed the task a moment before Claude changed it, so Claude's change is refused and the news says why:

⏺ hamloy - Change or delete an item (MCP)(key: "B-txqk@1", fields: {"prio":"low"})
  ⎿  Error: B-txqk changed since you read it; it's now B-txqk@2: Show the streak on the home-screen widget. Read it again and redo your change if it still applies
     Hamloy news (what changed since you last looked):
     - codex (session 8b17e0d4) renamed B-txqk to "Show the streak on the home-screen widget" (was "Show the streak counter on the widget")

A task that turned out to be your decision moves to questions:

• Called hamloy.edit({"key":"B-cxkr","list":"question"})
  └ Q-cxkr@2   Clean up the settings screen

Delete what Codex is on and another task waits on, then bring it back:

⏺ hamloy - Change or delete an item (MCP)(key: "B-paz4", delete: true)
  ⎿  deleted B-paz4 Weekly summary email; restore brings it back; no longer waiting on it: B-reah
     note: codex (session 8b17e0d4) was on it, and is told it's gone

⏺ hamloy - Change or delete an item (MCP)(key: "B-paz4", restore: true)
  ⎿  brought back B-paz4@2   Weekly summary email

What it refuses

nothing to change: give list, title, section, fields, summary, needs, add_note, notes, options, recommended, before, after, delete or restore
B-u5oh can't wait on B-txqk: that would go round in a circle (B-txqk waits on B-u5oh)
done is set by Hamloy itself; use tick, claim, rename, needs, answer or move for it
a field name is lowercase letters, digits, - and _, starting with a letter (like status or due-date), not "Due Date"
give before or after, not both
give delete or restore, not both
a note on a question can't start with "- " or "1.": it would read as an option; change the options with options instead
no item B-paza; did you mean B-paz4 "Weekly summary email"?

Done, claims and what waits on what are changed by their own tools: tick, claim, and needs here. Headings are renamed with section.