--- title: edit description: '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.' url: https://hamloy.com/docs/tool-edit --- [Docs](https://hamloy.com/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](https://hamloy.com/docs/lists). 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](https://hamloy.com/docs/history-and-undo), 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](https://hamloy.com/docs/tool-tick), [claim](https://hamloy.com/docs/tool-claim), and `needs` here. Headings are renamed with [section](https://hamloy.com/docs/tool-section).