Projects, hosts and worktrees¶
Every agent works in a project, every project lives on a host, and inside a project an agent can have a worktree of its own. This page explains what each of those is and why the app draws the lines where it does.
A project is a folder¶
A project is one folder you work in, named after that folder. The app does not copy it, import it or keep a second version of it: the agents work on the files in that folder, and what they change is there when you look with any other tool. The app keeps only what the folder cannot tell it, such as whether you have archived the project.
A project's agents are listed beside it on its page, grouped by what needs you, what is working and what is done.
An agent is filed under one project, but it need not stay inside that one folder. Work that spans two repositories is ordinary, so a new agent can be given more folders to reach, and MCP servers of its own, before it starts. It is still listed under the project it started in. See Give an agent more folders and MCP servers.
A project need not be a Git repository. Worktrees, branches and the git half of an agent's changes need one, and are simply not offered in a folder that is not; everything else works the same.
One project is made for you: chat, at ~/.agents/chat on each host. A chat is an
ordinary session of it, so a quick question needs no project picked, and the folder every
chat shares is where one keeps a file for the next. Each host makes its own the first time
it starts, and leaves it alone after that: archived stays archived, and its files and
AGENTS.md are yours. See Chat without a project.
A project lives on one host¶
A host is a machine where agents can do their work. Your Mac is one, once Agents Host runs on it. A Linux server can be another, and so can a second Mac, once it joins your control plane (see The control plane).
Each project belongs to exactly one host, and its folder is a path on that host. An agent in a project on a server runs on the server: its commands run there, its edits land there, and the runtimes you can pick from are the ones installed and signed in on that server, not on your Mac. The files pane, the terminal and the worktrees all show the server's copy. The same is true of a project on this Mac: the window asks this Mac's host for its files just as it asks a server's.
Projects on every host sit in the same list, each under its host's heading, in every window and on every phone and iPad. There is no switch that turns the whole window into a view of one host.
The reason for one host per project is that a folder is only ever in one place. Keeping two copies of it on two machines in step would mean deciding, every time they differ, which one is right, and an agent's half-finished edit is exactly the kind of difference nobody can decide about. So the work happens where the folder is, and the window goes to it.
Hosts join by connecting out¶
A host is never reached by anything. It connects out to your control plane over HTTPS, with a key of its own, and keeps that connection open. To add a server, you run one command on it, which a window shows you with a code that works once; it installs the host there in your home folder, and the host joins. A window can instead install it for you over ssh with a key you give for that install only; afterwards the control plane keeps neither the key nor the session, and the server connects out like any other. See Add a server.
Connecting out means a server behind a firewall or a home router joins without a port being opened to it, and a server you add once is seen by every window and device, with nothing to set up on each.
Why put a project on a server¶
That buys three things. The agents on a server keep working while your Mac sleeps, loses its network, or has the window closed, because nothing they need is on the Mac. The work can happen on Linux, or on a machine with more room than a laptop. And the Mac stays quiet while four agents build at once somewhere else.
When a host is offline, its projects show what the app last knew, marked as not current, and the app does not take a prompt or an answer for them that it cannot deliver. A host that loses its connection keeps its agents working, and reconnects by itself when it can. When it does, you see everything that happened meanwhile. A host never stops for being idle, so it is still there for the next connection.
If your control plane runs on your Mac, a server's agents keep working while the Mac sleeps, but you cannot see or answer them until the Mac is back. Running the control plane as copies on hosting of your own removes that gap; see Run the control plane as several copies.
Why worktrees¶
Every agent in a project works in the project's folder unless you say otherwise. Two agents changing code at once are then changing the same files: one's half-finished edit breaks the other's build, a test run picks up both sets of changes, and nobody can say afterwards which change came from which agent.
A git worktree is a second checkout of the same repository, in its own folder, on its own branch, sharing one history. Changes made in one stay out of the others until someone merges them. So when a project is a git repository, you can start an agent in a new worktree, or send it into one that already exists, for instance to review what another agent did there.
Each runtime has a worktree option of its own, but none of them could be relied on when the app starts them. What every runtime does honour is the folder the app starts it in. So the app makes the worktree itself and starts the agent there. The behaviour is the same whichever runtime you pick.
A new worktree is named from the first few words of the prompt that starts it, and its
branch has the same name under agents/. It starts from the commit your project folder
has checked out, and it lives inside the repository, under .agents/worktrees. An agent
in a worktree is still listed in the same project, with the worktree's name on its row.
An agent that starts helpers of its own can put each one in a worktree too.
A project has one set of pins, whichever checkout its agents work in. When an agent in a
worktree pins a page, the app writes it to .agents/pins.json in the project folder, never
the worktree's copy, and it never reads a worktree's copy either. The app doesn't commit
this file: a changed pin shows in the project folder's changes and goes in with whatever is
committed there next. See Pin a page to a project.
An agent can change where it works¶
Where an agent works is not fixed when it starts. An agent that finds its task has grown into something that needs its own branch can move into a worktree, or you can move it, and it can move back to the project folder later. The app makes the move between turns, because changing a runtime's folder while it is working is not something any runtime offers. The app already starts the runtime afresh for each turn, so the next turn simply starts in the new folder and picks up the same conversation.
Everything that follows an agent's folder follows the move: its files and changes, a restart or resume, and archiving, which cleans up the worktree it moved into just as if it had started there. A shell you had open stays where it is, since it is yours.
A runtime has to be able to pick its conversation back up in another folder for this to work. Claude, Copilot, Cursor and Codex can. Grok cannot, and Gemini and Antigravity have not been checked, so their agents are never moved: they would carry on having forgotten everything.
Worktrees are never removed by accident¶
Archiving an agent never throws work away. When you archive the last agent in a worktree the app made, the worktree's folder goes only if everything in it is committed, and its branch goes only if it has been merged. Otherwise both are left exactly as they are.
You can also remove a worktree yourself. The app refuses while an agent is working in it, and tells you what would be lost, and asks you to confirm, if it has changes that are not committed or a branch that is not merged.
Your own set, and a project's¶
A project can carry its own .agents folder, with skills, instructions and plugins that
belong to that project and apply only inside it. A plugin there that is new or has changed
waits for your OK on the project's page before any agent is handed it — the same check as
a workflow file — because it can run hooks and MCP servers when a session starts. See
A project's own plugins.
~/.agents in your home folder is the same idea one level up: your own set, which every
agent the app starts gets, in every project and on every runtime. The app lays it out on
your Mac only; a project on a server gets the project's own folder, and the runtimes on
the server keep whatever they were set up with there.
Your set goes to each runtime the way that runtime can take it, which differs. Some read
~/.agents/skills themselves; for others the app places links, which it never puts back
once you delete them; MCP servers go with each conversation as it starts, so nothing is
written into a runtime's own config. Settings ▸ Agent Configuration shows what each runtime ends up
with. See Share skills, instructions and servers with every agent.
A project's instructions, skills, MCP servers and plugins are set up in Project Settings ▸
Agent Configuration, a sheet opened from the project page's toolbar, the project's context
menu in the sidebar, or File ▸ Project Settings… (Option-Command-comma). Its pages are the
same as Settings ▸ Agent Configuration: Overview, Instructions, Skills, MCP servers,
Plugins and Other files, between the project's own General and Worktrees. The folder
is the difference: yours is ~/.agents, the project's is its .agents, and its instructions
are AGENTS.md at the top of the project. A project's Overview counts what is there, where
yours also shows what each runtime gets. Because that folder is committed,
a skill added there reaches everyone who clones the project; one added in Settings ▸ Agent Configuration
is yours alone. A worktree has its own .agents, so a change there stays on that branch until
it is merged. General also holds the project's two limits on agents that other agents start: how many may be running (3 unless you change it) and how many may be kept until you archive them (5). They are saved in the project's own .agents/project.json, so they go wherever the project goes. A change to that file, or to .agents/pins.json, made outside the app is not used until you keep it there; see Settings. See Agent tools. On a server, Project Settings shows only General. See
Add a skill from a catalogue.
A project's MCP servers live in .agents/mcp.json, on that same page. The file is committed, so it names each secret as ${NAME} and never
holds the value. Each person sets their own in ~/.agents/secrets.env. A server added from
the sheet is approved as it goes in. One that arrives with a pull waits, marked waiting
for your OK, until you choose Approve; no agent is given it before that. Where you and
the project both have a server of the same name, agents in the project get the project's. A
missing secret is named on the row, and agents start without that server rather than with an
empty key. Projects on a server don't show the section. See
Add an MCP server from the registry.
Nothing from a catalogue is taken on trust. skills.sh does not review what it lists, so the app shows every file before anything is written, points out scripts an agent could run, pins the commit it took, and checks each file against GitHub's own record of it at that commit.