---
title: list
description: '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.'
url: https://hamloy.com/docs/tool-list
---

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

# 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](https://hamloy.com/docs/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](https://hamloy.com/docs/lists) 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](https://hamloy.com/docs/tool-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](https://hamloy.com/docs/the-program) adds shows the same lists without asking the model. To keep reading after the first look, agents call [news](https://hamloy.com/docs/tool-news), which tells only what changed.