---
title: lists
description: 'The lists tool: how an agent adds, renames or removes a list of your own, such as ideas or bugs, beside Tasks, Requests and Questions.'
url: https://hamloy.com/docs/tool-lists
---

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

# The lists tool

How an agent adds, renames or removes a list of your own, such as ideas or bugs, beside Tasks, Requests and Questions.

`lists` looks after the lists of your own. Its title is **Lists of your own** , and its description, as the agent reads it:

> Add, rename or remove one of the human's own lists (ideas, bugs) when they ask, rather than a heading in the backlog; list shows them all. Its items work like tasks; pass its name as kind.

Every project has three lists: the backlog of tasks, requests and questions. You can add more, such as ideas, bugs or someday. Each gets a key letter of its own, and its items work like tasks: they can be claimed, ticked, have subtasks and wait on other items. See [Lists of your own](https://hamloy.com/docs/lists).

## Arguments

| Argument | Type | What the agent is told |
| --- | --- | --- |
| `add` | string | a lowercase name like ideas: makes a task list of that name, with its own key letter |
| `rename` | string | one of your lists to rename; give the new name as to |
| `to` | string | the new name, with rename |
| `remove` | string | one of your lists to remove, with everything in it; refused while it has open items unless force |
| `force` | boolean | |

With no arguments it names every list and its key letter, and only reads.

## What it does

- `add` makes the list, and says which letter its keys take. Adding one that is there already says so, and changes nothing.
- After that, [add](https://hamloy.com/docs/tool-add) and [list](https://hamloy.com/docs/tool-list) take the list's name as `kind`, and a [view](https://hamloy.com/docs/tool-view) takes it as `list`.
- `rename` keeps the key letter, so every key stays the same.
- `remove` takes the list with everything in it, and the views of it. While it has open items, it needs `force`.
- The other agents hear of each change in their news.
- The three lists every project has can't be renamed or removed.

The rules ask agents to make a list only when you ask for one; a heading in the backlog is often enough.

## Calls and replies

In Claude Code:

```
⏺ hamloy - Lists of your own (MCP)
  ⎿ Pebble's lists, with the kind that adds to each:
     backlog (task) keys B-
     requests (request) keys R-
     questions (question) keys Q-

⏺ hamloy - Lists of your own (MCP)(add: "ideas")
  ⎿ added ideas (keys I-); add to it with kind ideas

⏺ hamloy - Add an item (MCP)(title: "Habit stacking: one habit after another", kind: "ideas")
  ⎿ I-2zub@1 Habit stacking: one habit after another
```

Renaming it, then removing it with what's in it, in Codex:

```
• Called hamloy.lists({"rename":"ideas","to":"someday"})
  └ renamed to someday (keys still I-)

• Called hamloy.lists({"remove":"someday"})
  └ someday still has 1 open item; finish or move it first, or pass force to remove it anyway

• Called hamloy.lists({"remove":"someday","force":true})
  └ removed someday and its views (Someday)
```

What another agent reads in its news:

```
Hamloy news (what changed since you last looked):
- claude (session 3f9a2c71) added the list ideas (keys I-); the list tool shows it
- claude (session 3f9a2c71) renamed the list ideas to someday; use kind someday now
- claude (session 3f9a2c71) removed the list someday
```

## What it refuses

```
backlog is taken; pick another name
a list's name is a lowercase word like ideas or bugs, not "%%%"
backlog is one of Hamloy's own lists; only lists you made can be renamed or removed
there's no list called bugs (the lists tool shows them)
there's already a list called someday
```

A list is named by a word. A name given with capitals or a mark, like `Bugs!`, is made into the word (`bugs`). A project has as many lists of its own as there are key letters left.

A kind that names no list is refused by `add`, with the way to make it:

```
kind is task, request, question or one of your lists (ideas), not "idea"; to start a list called idea, make it first (the lists tool with add: "idea")
```

## In your assistant

Claude Code shows `hamloy - Lists of your own (MCP)`; Codex shows `Called hamloy.lists`. The board shows a new list as soon as it is made.