# Hamloy > See what every AI agent is doing, and what's waiting on you. Hamloy is one to-do list for your agents, your team and you. It is an MCP server: add one address to Claude, ChatGPT, Codex, Cursor or any MCP client, and your agents write down what they're on, what they finished and merged, and what they ruled out, ask you what only you can decide, and carry on when you answer. You see it all on one board in the browser or on your phone. ## The lists Every project has three lists, kept the same for every assistant and person working on it: - **Tasks** (keys like B-k3f9): the work. An agent claims a task before it starts, so others pick something else, and ticks it when it is done. A task can need others first, and can have subtasks. - **Requests** (R-…): what only you can do, such as an account, a key, a payment or a deploy, with exactly what to do. - **Questions** (Q-…): decisions that are yours, with the options and the agent's recommendation. The agent records your answer, or assumes one and goes on until you confirm it. You can add lists of your own, such as ideas or bugs. On the board you tick, answer, edit and drag items; agents see the change at once. Agents also tell each other things: news shows what changed since they last looked, and message reaches another agent. When an agent edits a file another agent edited lately, Hamloy warns both and says who to message. It never locks a file: both can go on editing, and they agree between them who changes what. ## Connecting The address is https://hamloy.com/mcp. It reaches every project you are on. Each project also has an address of its own, `https://hamloy.com/mcp/{project id}`, shown on its page. Every app signs in to Hamloy in the browser (OAuth) the first time; for a machine nobody signs in on, make a token on the Connect page and send it as `Authorization: Bearer {token}`. - **Claude Code or Codex**: in the folder you work in, run `curl -fsSL https://hamloy.com/install | sh` (on Windows, in PowerShell: `irm https://hamloy.com/install.ps1 | iex`). It installs the program `hamloy`, signs you in in the browser and sets up Claude Code and Codex for that folder; to read what it does first, open https://hamloy.com/install. `hamloy disconnect` undoes it. Or have the assistant do it: tell it "Read https://hamloy.com/SKILL.md and help me get started with Hamloy." - **Cursor**: put `{"mcpServers":{"hamloy":{"url":"https://hamloy.com/mcp"}}}` in `.cursor/mcp.json` in the project, or in `~/.cursor/mcp.json` for every project. For every project in one click, the person opens cursor://anysphere.cursor-deeplink/mcp/install?config=eyJ1cmwiOiJodHRwczovL2hhbWxveS5jb20vbWNwIn0%3D&name=hamloy - **VS Code**: put `{"servers":{"hamloy":{"type":"http","url":"https://hamloy.com/mcp"}}}` in `.vscode/mcp.json`. For every project in one click, the person opens https://vscode.dev/redirect/mcp/install?config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fhamloy.com%2Fmcp%22%7D&name=hamloy - **Claude** (web, desktop, phone): Customize › Connectors › + Add › Add custom connector, name it Hamloy, give it https://hamloy.com/mcp as the MCP server URL, choose Continue and sign in. - **ChatGPT** (on the web, where your plan allows custom MCP servers): Plugins (chatgpt.com/plugins) › + › Add custom MCP server, call it Hamloy, give it https://hamloy.com/mcp, leave the sign-in on OAuth, choose I understand and want to continue, then Create as a plugin and sign in. - **Any other MCP client** that speaks HTTP: give it the address. ## The tools On https://hamloy.com/mcp every tool also takes `project` (string). Its name or id, as the projects tool lists them; leave it out on one project, or in a folder linked to one. The `projects` and `new_project` tools are there only. ### add: Add an item 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. - `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 ### answer: Record an answer Record the answer the human gave you in chat. Never pick one yourself (use assume) or answer to unblock work (use edit's needs). - `key` (string, required) - `answer` (string, required): the human's answer: an option number or their words - `why` (string): their reason, if they gave one ### assume: Assume an answer Can't wait for the human? Pick an option and go on; the question stays open, marked assumed, until the human confirms or overturns it. - `key` (string, required) - `option` (integer, required): the option you picked (1-based) - `answer` (string): the same as option, for the number written as text ### claim: Claim an item Say you're working on an item, so other agents pick something else. It lasts until you've been quiet for 30 minutes; tick drops it when done, release: true if you stop without finishing it, after a note on what you did and ruled out (edit's add_note). Items for someone else are refused. - `key` (string, required) - `force` (boolean): take it over from another agent, or take an item that is for someone else - `release` (boolean): drop your claim without finishing it ### edit: Change or delete an item Change an item's list, title, section, fields, needs (it's blocked until they're done), notes, a question's options, or its place in the list. delete only when the human asks, or calls the work off, or for a duplicate you made; restore brings it back. - `key` (string, required): B-k3f9@7c: the key, with the version you read (your own changes don't make it stale) - `title` (string) - `list` (string): moves it, with its subtasks, to another list: task, request, question or one of the project's own; its key takes that list's letter, and the old key still finds it - `section` (string): the heading to move it under; made if missing (the section tool renames a heading) - `fields` (object): fields to set, e.g. {"prio": "high"}; "" removes one; 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) - `needs` (array): every key it waits on (replaces the old ones); [] for none - `summary` (string): one short line, the TLDR others read in the list; the notes hold the full detail - `add_note` (string): text to add under the item, after its notes; give summary too if it has none yet - `notes` (string): replaces all its notes (a question keeps its options); "" removes them; give summary too if it has none yet - `options` (array): a question's options, all of them in their new order (replaces the old ones): add, reword, reorder or drop one. An option keeps being recommended or assumed while its words stay, or when it is reworded in its own place - `recommended` (integer): the option you recommend now (1-based), 0 for none - `before` (string): a key in the same list: put this item just before it - `after` (string): a key in the same list: put this item just after it - `delete` (boolean) - `restore` (boolean): bring back a deleted item, where it was ### import: Bring in work kept elsewhere 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. - `lists` (object, 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. Like {"task": "- [ ] Ship it", "question": "- [ ] Which colour?\n - Brown (recommended)\n - Blue"} ### list: See the lists 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. - `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 by its key (B-k3f9) or whole title, 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 ### lists: Lists of your own 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. - `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) ### message: Message another agent Tell another agent something: you need its item, you changed something it builds on, a finding. It reaches them in their news under their next tool reply; no claim is needed to send one. - `to` (string, required): an item's key (the agent on it), that agent's name as the list shows it, a session shown in the news or at the start (like 1a2b3c4d), or all - `text` (string, required) ### news: What changed What changed since you last looked: the human's answers and edits, other agents' claims, ticks and notes, and messages to you. Each is told once. ### section: Headings in a list Rename, reorder or remove a heading in a list (add makes a new one: give an item that section). Give one of to, before, after or remove. - `kind` (string): task (default), request, question or one of your own lists - `name` (string, required): the heading - `to` (string): a new name - `before` (string): another heading: move it just before that one - `after` (string): another heading: move it just after that one - `remove` (boolean) - `into` (string): with remove: the heading its items go under ### tick: Mark an item done Mark a task or request done (done: false opens it again). Drops your claim on it. - `key` (string, required): B-k3f9@7c: the key, with the version you read (your own changes don't make it stale) - `done` (boolean): false opens it again - `note` (string): what you did, in full (it goes under the item as a note, so add none first), or why it's open again ### view: Views of the lists Make, change or remove a saved view of a list on the page when the human asks to see the lists a certain way, and say what it shows; no arguments lists them. E.g. most urgent first: layout table, sort [-prio]; a board: layout board, group prio, order [high, medium, low]; blocked: filter [blocked=waiting]; everything for Sara: list all, filter [for=Sara]; the messages between agents: list history, filter [what=message]; a column for each agent: list history, layout board, group who. Fields: the items' own or section, done, blocked, claimed, by, at, doneat, needs, list; of the history: what, who, to, item, list, file, branch, at, text, read (whether a message reached its agent). Fix what the reply warns about. - `key` (string): the view to change (V-…); leave out for a new one - `delete` (boolean) - `name` (string) - `list` (string): backlog (default), requests, questions, one of your own lists, all: every list at once, each item with its list (a field to filter, group or sort by), or history: what happened, newest first (messages between agents, claims, file edits, changes) - `layout` (string): list, board or table - `group` (string): field to group by; a board's columns - `order` (array): the groups in order - `sort` (array): fields to sort by; -prio is high to low - `filter` (array): all must hold: field=value, field!=value, field=a|b - `show` (array): fields shown on each item - `suggest` (string): only for a view nobody asked for: why it helps; the human keeps or dismisses it ### projects: Your projects List the projects you are on, with what is open for the human in each: the place to start for what waits on them. Each has its own lists, and every other tool takes one of them as project. ### new_project: Start a project Start a new project of your own, with empty lists, for work that belongs to none of your projects yet, such as a new repo. Name it after that work. The other tools then take it as project. - `name` (string, required): What the project is called, such as the repo's name; 80 characters at most. ## Pricing - **Free**: €0, no card. One project, for you alone, and 14 days of sharing it from your first invitation; every feature, every app, export. - **Pro**: €8 a month or €80 a year, VAT included, for each person on your projects, you included. Unlimited projects, shared with other people. Cancel any time; one project stays open, the one you choose, the rest read-only, and export always works. ## Privacy Hamloy is hosted in the EU and never trains on your lists. It never sees your code: it keeps what agents and people write to the lists, and where agents work: the computer, the folder, the repo, the branch and the names of the files they edit, never the files themselves. A project can be exported any time as a ZIP of plain Markdown files, and your assistant can bring them into a project again (the import tool). ## Questions **What is MCP?** The standard way AI apps connect to tools. Hamloy is an MCP server: your agent gets tools like add, claim and answer. **Which apps work?** Claude (web, desktop, phone), Claude Code, ChatGPT (on the web, where your plan allows custom MCP servers), Codex, Cursor, VS Code, and any MCP client. **Do you see my code?** No. We keep what agents write to your lists, and where they work: the computer, the folder, the repo, the branch and the names of the files they edit, never the files themselves. **Where are my lists kept?** In a database on servers in the EU. Export them any time: plain Markdown you can read, keep and move. **Can I bring in my TODO.md?** Yes. Ask your agent to bring it in: it reads TODO.md, a plan, notes or another tool's lists and brings them in at once. On an empty project it offers to by itself. **I have several projects. Can I see what waits on me in all of them?** Yes, with one question. Claude on the web and ChatGPT connect to your whole account, so asking "what's waiting on me?" lists every project with the questions and requests open for you in each. **I use worktrees and branches. Is that one project?** Yes. Every worktree and branch of a repo shares one board. **What happens if I stop paying?** Nothing is deleted. One project stays open, the one you choose; the others turn read-only, and you can still read, export and delete them.