--- title: import description: 'The import tool: how an agent brings in work kept somewhere else, a TODO file, a plan, notes, issues or another tool''s lists, in one call.' url: https://hamloy.com/docs/tool-import --- [Docs](https://hamloy.com/docs) # The import tool How an agent brings in work kept somewhere else, a TODO file, a plan, notes, issues or another tool's lists, in one call. `import` brings in work that was kept somewhere else until now. Its title is **Bring in work kept elsewhere** , and its description, as the agent reads it: > Bring work kept somewhere else (a TODO or plan file, notes, issues, a checklist, your own todo list, another tool's lists) into the lists in one call, once the human says yes. Sort it as it comes in: what only the human can do (an account, a key, money) is a request, a decision of theirs a question, each in that list and not also a task. Write each list's items as Markdown, done ones too: ## Heading, - [] Title (- [x] when done), indented lines under it its notes, indented - [] its subtasks. A question's options are its indented - lines, (recommended) after one; its notes there have no dash. A file's # title is left out; text before the first item is the list's intro. Notes hold up to 20,000 characters an item. What else the source says goes in a comment ending the line, all of it: ; needs names items by those ids or by keys here. Lists already in this form (another tool's export) go in as they are. A log of past work (test rounds, a changelog) stays in its file: bring in only the open work it names. Work found in two places is one item; group it by what it is about, not by where you found it. An item its list already has by title is left out. All of it comes in, or nothing, into this one project: another repo's work goes into that repo's own project. The agent reads the work wherever it is, in whatever form, and writes it out as checklists, one per list. A plain bullet or a numbered line counts as an open item too. For people, see [Import](https://hamloy.com/docs/import). ## Arguments | Argument | Type | What the agent is told | | --- | --- | --- | | `lists` | object of texts, required | each list with its items as Markdown: task, request, question or another list here. A group of items is a ## heading in its list's text, not a list. | A list's name can be `task`, `request`, `question`, their plural, a file name like `backlog.md`, or the name of another list here. An import makes no list: any other name is refused, so a group of items becomes a heading, and a list the human wants of its own is made first with [lists](https://hamloy.com/docs/tool-lists). ## What it does - Everything comes in at once, as one change in the history, or nothing does. - A heading with the name of one the list has already is that one; a new one goes after the others. - `parent:T1` in an item's comment makes it a subtask of the item with that id, as if it stood indented under it; `recommended:2` in a question's marks its second option, and "(recommended for launch)" after an option marks it with its reason kept. - A comment of fields at the end of an item's notes, rather than its own line, is the item's all the same. - A question's lines with a letter or number before each and no dash, like `**A (recommended):** Postgres`, are its options. Bold is left off titles and options, so they read as plain words. The reply names the questions that came in with no recommended option. - A done item whose title ends with when, like ` ~~Move to Postgres~~ done 2026-10-02`, was done that day, as `done:2026-10-02` in its comment says. - A file's one `#` title over its items is its name, not a heading. Text before the first item becomes the list's intro, when it has none. - Every item longer than the tools allow is named in one refusal. - It all goes into the one project the call is for. Another repo's work goes into that repo's own project, from an assistant working there. - One title twice in an import is refused, unless each has a key of its own, as an export gives them. - An item whose list (or, for a subtask, whose parent) already has one of that title is left out. Its subtasks that are new still come in, under the item that is there; an open one opens a done parent again. - An `id` that is a key of its list and free here stays the item's key. Any other id, like `T1` or `#12`, gets a fresh key, and `needs` by that id still finds it. - Who added or finished an item, by `by` and `done-by`, is the caller's person for any name not on the project. `done-by:git` stays git, which only ever finishes work. ## Calls and replies In Claude Code: ``` ⏺ hamloy - Bring in work kept elsewhere (MCP)(lists: {"task": "## Shop\n\n- [] Put the price list on the menu page \n- Fix the footer", "ideas": "- A loyalty card"}) ⎿ brought in 2 tasks and 1 in ideas The list tool shows them, in Bakery. This work lives here from now on: keep it here, not in the old place. If it came from a file or another tool, tell the human, and ask whether to delete the old file or leave one line in it saying the work moved to Hamloy, so no one keeps using it. ``` Bringing the same file in again, in Codex: ``` • Called hamloy.import({"lists":{"task":"- [] Put the price list on the menu page\n- [] Write the about page"}}) └ brought in 1 task left out, already here: B-k2m4 "Put the price list on the menu page" The list tool shows them, in Bakery. This work lives here from now on: keep it here, not in the old place. If it came from a file or another tool, tell the human, and ask whether to delete the old file or leave one line in it saying the work moved to Hamloy, so no one keeps using it. ``` What another agent reads: ``` Hamloy news (what changed since you last looked): - claude (session 3f9a2c71) brought in 2 tasks and 1 in ideas; the list tool shows them ``` ## What it refuses ``` Nothing was brought in: the lists have no items: write each as a line like - [] Ship it. Nothing was brought in: in backlog, an item has no title (a - [] line with nothing after it); give it one or leave it out. Nothing was brought in: backlog is given twice; put its items in one text. Nothing was brought in: there is no list "code" here; put those items in task, request or question, under a ## heading if they belong together. Only for a list the human wants of its own, make it first with lists. Nothing was brought in: “Ask Tom for his camera” is given in backlog and requests; give it once, in the list it belongs to. Nothing was brought in: “Order form for cakes” is given twice in backlog; give it once, in the list it belongs to. Nothing was brought in: the text for backlog has an unfinished merge in it (the lines from <<<<<<< to >>>>>>>); keep one version of those lines. Nothing was brought in: in backlog, B-aaaa has 161 characters in its summary field, and the most is 160. Nothing was brought in: in backlog, “Checkout” needs issue-7, and no item given has that id, nor is it a key here; give that item id:issue-7. Nothing was brought in: its items wait on each other in a circle (B-aaaa waits on B-bbbb waits on B-aaaa), so none of them would ever be free. Nothing was brought in: that is more than 2,000 items, the most one import holds. ``` Every item too long is named at once, with a way through: ``` Nothing was brought in: “Round log” in backlog has 48,210 characters in its notes (the most is 20,000). Cut each to what still matters (the newest part of a log), or keep the long text in a file in the repo and say in the notes where it is. ``` ## When an agent uses it On a project with nothing in it, the [list](https://hamloy.com/docs/tool-list) reply and the start of a session tell the agent to look for how the work was kept until now, tell you what it found, and bring it in once you say yes.