The list tool

How an agent reads the open tasks, requests and questions, one item in full with its history, or every item with some words.

list is how an agent reads the lists. Its title is See the lists, and its description, as the agent reads it:

The project's open tasks, requests and questions; key reads one item, open or done. Answer every question about the work and the lists with it. Shows 50 items at a time and says where the next ones start.

It only reads, so it answers on a project that is read-only for you too. The rules ask agents to call it when they start.

Arguments

Argument	Type	What the agent is told
`kind`	string	task, request, question, one of your own lists by name, or all (default)
`status`	string	open (default), ready (open, waits on nothing), done or all
`section`	string	only items under this heading
`key`	string	one item, e.g. B-k3f9, with its notes, what it waits on and frees, and its history
`find`	string	words to look for: items with all of them, else titles with any; searches done items too unless status is set
`from`	integer	start at this item (from 0)
`limit`	integer	how many items to show, 50 by default
`history`	boolean	`true`: what changed lately instead, who did it and when, deletions too; with `find`, only the items it names

What it shows

The first line counts what is open and done. With git, it also says what is done on a branch but not merged yet.
Then each list, by heading. Each item is one line: done or not, key and version, title, fields, and in brackets who it's for, its subtasks, what it waits on and who is on it. A summary sits under its line.
key shows one item in full: where it is, its state, what it waits on and what it frees, its summary, notes, options and answer, and its last changes. An old key of an item that moved list still finds it.
find searches open and done items, and lists deleted ones that match apart, so they can be brought back.
On a project shared with other people, the first page says who is on it and whom the agent works for.
history shows the project's changes, the latest first, by day: the time, the item, who did what to it. 40 at a time, with from for older ones. A deletion shows there, so an agent asked what happened overnight finds what was deleted and brings it back with edit's restore. With find, only the changes of the items it names, by key or by words of any title they had.

Calls and replies

What's ready to start, three at a time. In Codex:

• Called hamloy.list({"status":"ready","limit":3})
  └ Pebble · 12 open, 0 done
    backlog
      ## Home
      [ ] B-u5oh@2   Streak counter on the home screen  prio:high
      [ ] B-cxkr@1   Clean up the settings screen  (1 note)
          Drop the three toggles nobody uses
      [ ] B-txqk@1   Show the streak counter on the widget
    Showing items 1–3 of 10. The next ones: from 3. Or narrow it with find, kind, section or ready.

A request in full. In Claude Code:

⏺ hamloy - See the lists (MCP)(key: "R-j51a")
  ⎿  ○ R-j51a@1  request
     Make an APNs key for push reminders
     Waiting for you · added by claude on 2026-10-10

     Unblocks
       ⊘ B-xtiv Push reminders at the habit's time  waits on R-j51a, Q-q0ae

     Summary
       Reminders can't be sent without it

     Notes
       1. In the Apple Developer account, open Certificates, Identifiers & Profiles › Keys.
       2. Make a key with Apple Push Notifications service on.
       3. Put its ID in APNS_KEY_ID and the .p8 file's text in APNS_KEY on the server.

     History (UTC)
       2026-10-10 00:08  claude added it

What's done, with a task ticked on a branch that isn't merged:

⏺ hamloy - See the lists (MCP)(status: "done")
  ⎿  Pebble · 0 open, 1 done, 1 not merged yet (B-chzz)
     backlog
       ## Home
       [x] B-chzz@3   Streak counter on the home screen  prio:high  (done by claude on 2026-10-10; on streak-counter, not merged into main yet)

A search that finds a deleted item:

⏺ hamloy - See the lists (MCP)(find: "weekly")
  ⎿  Pebble · 1 open, 0 done
     Deleted; edit's restore brings one back where it was:
       B-paz4     Weekly summary email  (deleted by claude on 2026-10-10, was under ## Later)

What it refuses

"menu page" isn't a key; keys look like B-k3f9 (tasks), R-2m8a (requests) or Q-7x1c (questions)
status is open, ready, done or all, not "blocked"
list takes kind, status, section, key, find, from, limit, not ready; for ready, give status: ready

A key given to list that belongs to a saved view (V-…) shows that view, as view does.

In your assistant

Claude Code shows hamloy - See the lists (MCP); Codex shows Called hamloy.list. In Claude Code, the /hamloy command that the program adds shows the same lists without asking the model. To keep reading after the first look, agents call news, which tells only what changed.