---
title: add
description: 'The add tool: how an agent adds a task, a request for you or a question for you, with every argument, real replies and what it refuses.'
url: https://hamloy.com/docs/tool-add
---

[Docs](https://hamloy.com/docs)

# The add tool

How an agent adds a task, a request for you or a question for you, with every argument, real replies and what it refuses.

`add` puts a new item on a list. Its title is **Add an item** , and its description, as the agent reads it:

> Add a task, a request for the human, or a question for the human. It stays open: claim it only if you start on it now, and tick it once the work itself is done, not for adding it.

## Arguments

| Argument | Type | What the agent is told |
| --- | --- | --- |
| `title` | string, required | one line |
| `kind` | string | task (default), request (only the human can do it), question (the human decides), or one of your own lists by name |
| `section` | string | heading to put it under; made if missing |
| `summary` | string | one short line, the TLDR others read in the list; body holds the full detail |
| `body` | string | its notes, one line each: a request's exact steps, a task's notes (with notes, summary is required); an empty line starts a new paragraph |
| `options` | array | a question's answers to choose from; they can change later with edit |
| `recommended` | integer | the option you recommend (1-based) |
| `needs` | array | keys it waits on |
| `fields` | object | fields, e.g. `{"prio": "high"}`; 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) |
| `parent` | string | a task or request key: add this as its subtask |
| `subtasks` | array | titles of subtasks to add under it, with the same fields |

## What it does

- The reply is the new item's line: its key and version, title and fields, and the summary under it. Subtasks follow, one line each, and take the parent's fields.
- A task goes on [Tasks](https://hamloy.com/docs/tasks), a request on [Requests](https://hamloy.com/docs/requests), a question on [Questions](https://hamloy.com/docs/questions) with its options numbered and the recommended one marked.
- With `needs`, the item [waits on](https://hamloy.com/docs/waits-on) those keys until they're done or answered.
- A field value that is a slip of one in use gets a "did you mean" note.
- If an open item has the same words, the reply says so, in case it's the same work. The same title ticked done in the past week gets a note too.

## Calls and replies

A task with a field, in Claude Code:

```
⏺ hamloy - Add an item (MCP)(title: "Streak counter on the home screen", section: "Home", fields: {"prio":"high"})
  ⎿ B-u5oh@2 Streak counter on the home screen prio:high
```

A question with options and the one the agent recommends, in Codex:

```
• Called hamloy.add({"title":"Where should synced habits live?","kind":"question","options":["Supabase: Postgres with auth built in","CloudKit: free, Apple only","Firebase"],"recommended":1,"summary":"Decides the sync backend and whether Android can follow","body":["Supabase works on Android later too; CloudKit is free but Apple only."]})
  └ Q-q0ae@1 Where should synced habits live? options: 1) Supabase: Postgres with auth built in (recommended) 2) CloudKit: free, Apple only 3) Firebase
          Decides the sync backend and whether Android can follow
```

A task with subtasks, and one that looks like work already on the list:

```
⏺ hamloy - Add an item (MCP)(title: "Sync habits across devices", section: "Sync", subtasks: ["Pick a sync backend","Sign in with Apple","Merge edits made offline"])
  ⎿ B-mh1c@1 Sync habits across devices (0 of 3 subtasks done)
       B-nh37@1 Pick a sync backend (subtask of B-mh1c)
       B-4yo9@1 Sign in with Apple (subtask of B-mh1c)
       B-giwo@1 Merge edits made offline (subtask of B-mh1c)

⏺ hamloy - Add an item (MCP)(title: "Show the streak counter on the widget")
  ⎿ B-txqk@1 Show the streak counter on the widget
     note: B-u5oh "Streak counter on the home screen" is open too; if it is the same work, delete this one (edit with delete) and take that one
```

## What it refuses

```
options are for questions; set kind to question
give it a summary with its notes: one short line others read in the list (add's summary); the notes keep the full detail
the summary repeats the title; give the gist of the notes instead: what you plan, found or decided, in one short line
kind is task, request or question, not "bugz"; to start a list called bugz, make it first (the lists tool with add: "bugz")
recommended is the number of an option, 1 to 2
questions can't have subtasks
no item B-zzzz to wait on
done is set by Hamloy itself; use tick, claim, rename, needs, answer or move for it
```

Limits: a title is one line of up to 1,000 characters, a summary up to 160, a field's value up to 200, a question up to 20 options, and an item's notes up to 20,000 characters in all.

An item for you is marked so on its line, and agents leave it alone:

```
B-vz8m@2 Approve the App Store screenshots (for the human, not for agents)
```

Two things are notes, not refusals. A `for` field that names nobody on the project is kept, with a hint:

```
note: for=sara names nobody here; write you for the human, or an assistant (claude, codex, cursor, chatgpt) or a session's name
```

And a new word close to one in use:

```
B-rfko@2 Fix the dark mode colours prio:hihg
note: prio=hihg is a new word; did you mean high?
```

See also [fields](https://hamloy.com/docs/fields), [edit](https://hamloy.com/docs/tool-edit) to change an item afterwards, and [the 13 tools](https://hamloy.com/docs/tools).