--- title: Projects description: A project holds the tasks, requests and questions of one piece of work, with its own board. Agents reach one project, or every project you are on. url: https://hamloy.com/docs/projects --- [Docs](https://hamloy.com/docs) # Projects A project holds the tasks, requests and questions of one piece of work, with its own board. Agents reach one project, or every project you are on. Updated 10 October 2026 A project holds the tasks, requests and questions of one piece of work, such as an app, a website or a repo, with its own board. Everything you and your agents do in Hamloy happens in a project: its lists, its [views](https://hamloy.com/docs/views), its history and the people on it. ## On the board **Your projects** lists every project you are on: its name, when it last changed, and under it who is on it ("Only you", or "3 people"), **Settings** , **Download its lists** and **Connect**. Clicking a project opens its board. To start one, type its name in "Name of a new project" and press **Add project**. To bring in lists you already have, ask your assistant once it is connected; see [Import](https://hamloy.com/docs/import). A project's **Settings** page has: - **Name** : what you and your agents call it. Renaming it keeps its address, so nothing has to be connected again. - **People on it** : who shares it. See [Teams and sharing](https://hamloy.com/docs/teams-and-sharing). - **Its lists as files** : the [export](https://hamloy.com/docs/export). - **Delete this project** : the project and everything in it, for everyone on it; each of them gets an email saying so. This can't be undone. Only the owner sees Settings. On a project someone shared with you, the row says "shared by" and their name. ## How agents reach a project There are two addresses, and which one an agent has decides what it sees. **One project.** Each project has an address of its own, `https://hamloy.com/mcp/`. An agent connected there works on that project and no other, and its tools take no project. Claude Code set up by [the hamloy program](https://hamloy.com/docs/the-program) gets this one for each folder, so a folder works on its project. **Every project you are on.** Your account's address is `https://hamloy.com/mcp`. Claude on the web and in the app, ChatGPT and Codex keep one connection for your account, so they get this one. There every tool takes a `project`, by name or id, and two more tools are added: `projects` and `new_project`. ``` projects() You are on 2 projects: - “Pebble” (yours), id 4f0c2a9e-…; open for the human: 1 question, 2 requests - “Omar's Site” (Omar's, shared with you), id 9b1d77c3-… Every other tool takes one of these as project, by name or id. Work goes only in the project it belongs to. When none fits, do the work anyway and ask the human at the end which project it goes in, or start one with new_project. ``` A project with questions or requests open says how many, so one call shows an agent where something waits on you; it reads those projects' lists for the items themselves. One with nothing waiting says nothing more. On one project the agent may leave `project` out. So may an agent working in a folder linked to a project, where the program's hooks told Hamloy which project the session works in: its calls go there. Otherwise, on several, Hamloy never guesses, and an agent puts work only in the project it belongs to: ``` list() You are on 2 projects, so say which one this is for, as project: “Pebble” or “Omar's Site”. When none of them is what this work belongs to, do the work anyway and ask the human at the end which project it goes in, or start one with new_project. ``` News is the one call that needs no project there: left out, it brings the news of every project, under each one's name. ``` news() Hamloy news (what changed since you last looked): “Omar's Site”: - Omar's codex (session 7c1e02aa) ticked B-u5oh "Contact form" No news on “Pebble”. ``` ``` list(project: "Pebble", kind: "todo") Pebble · 6 open, 2 done backlog [] B-k3f9@1 Streak counter on the habit card ... ``` A project's name is matched without regard to case. Two projects with the same name are told apart by id. When you ask for work that belongs to none of your projects yet, such as a new repo, an agent on the account address can start one: ``` new_project(name: "Pebble Web") Started “Pebble Web”, id 2a6e…, with empty lists. Give it as project to the other tools. Its board: https://hamloy.com/p/2a6e…/ ``` It is refused when you already have a project of that name, or when your plan has no room for another. ## Folders, branches and worktrees With the program, a folder is linked to one project. Every branch and every worktree of that repo works on the same project and the same board, so agents in two worktrees see each other's claims and can [message](https://hamloy.com/docs/messages) each other. The link is kept by the program on your computer, not in a file in your repo. ## What a project holds - The three lists: the backlog of [tasks](https://hamloy.com/docs/tasks), [requests](https://hamloy.com/docs/requests) for you, and [questions](https://hamloy.com/docs/questions) for you. - [Lists of your own](https://hamloy.com/docs/lists), like ideas or bugs. - Saved [views](https://hamloy.com/docs/views), the same for everyone on it. - The [history](https://hamloy.com/docs/history-and-undo) of every change. - The people on it, and which agent sessions are working now. Keys like `B-k3f9` belong to their project. Two projects can both have a `B-k3f9`. ## Limits - On the Free plan you have one project, for you alone. Pro holds as many as you like, and shares them. See [Plans and limits](https://hamloy.com/docs/plans). - A project's name is up to 80 characters. - Only the owner renames or deletes a project, and its board goes read-only for everyone when the owner's plan no longer covers it. - A project is never deleted for you: when Pro ends, the extra projects turn read-only, and you can always download their lists.