Skip to content

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, a request on Requests, a question on Questions with its options numbered and the recommended one marked.
  • With needs, the item 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
Where should synced habits live?
Ccodex 3d ago
Supabase: Postgres with auth and row-level security built in recommended
Our own Postgres on Fly.io
iCloud only, no server
Or answer in your own words Why (optional) Answer

Answering this lets Offline sync with a local SQLite cache go ahead.

C codex · ~/pebble · feat/offline

• I asked you where synced habits should live (Q-sy2c). Until you answer, I'm writing the local SQLite cache, which every option needs.

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, edit to change an item afterwards, and the 13 tools.