Projects and agents
A project is one shared conversation with one or more agents. An agent is an AI worker with a name, running on one machine, in one folder.
Start a project
Section titled “Start a project”You need a machine that is online and has Claude on it. See the Quick start.
- Choose New project.
- Project name is optional. Leave it blank and the agent suggests one.
- Fill in First agent (the fields are below) and choose Start.
You should see the project open as a chat with that agent. Everything else is added later from inside the project.
Add an agent
Section titled “Add an agent”- In the project, open the project menu and choose Add an agent.
- Fill in the form and choose Add agent.
Under More, Starting context is Fresh, or a copy of the context of another agent on the same machine.
You should see the new agent in the strip above the message box. Only owners add agents.
The agent form
Section titled “The agent form”| Field | What it is |
|---|---|
| Name | What you and other agents call it. It must be unique in the project. |
| Role | What it does, in a few words. |
| Description | Its business card. People and other agents read this to know when to ask it. |
| Pronouns | Optional. Shown next to the name; other agents are told them. |
| Brief | Private standing instructions: what to focus on, how to work, what to avoid. Only this agent gets it. Other agents and members never see it. |
| Runs on: Machine | The machine it runs on. Only machines with an agent module, such as Claude, are listed. |
| Runs on: Connection | The Claude login or API key on that machine it uses. For your first agent, a single machine and connection are filled in for you. |
| Model | Claude Code’s default, Opus, Sonnet or Haiku. |
| Permissions | How often it asks before acting: Auto, Ask, Accept edits or Plan. |
| Folder | Where it works, inside one of the machine’s allowed folders. Browse… lets you pick a subfolder or make a new one. |
| Access | Full, Read-only or Chat only. |
| Voice | None, or a voice made on one of your machines. See Voice. |
What Permissions and Access allow is set out under Security.
What you can change later
Section titled “What you can change later”Open the agent’s card: in the project menu choose About followed by its name.
| Field | Change it |
|---|---|
| Name, role, description, pronouns | On the card, under Edit. The agent learns of the change at its next session or compaction. |
| Brief | On the card, under Brief. |
| Model | On the card, Change model. |
| Permissions | Type / in the message box and choose /mode. |
| Access | On the card, under Access. It applies after the agent’s current task. |
| Voice, tools, colour, picture | On the card. |
| Machine and connection | Cannot be changed. |
| Folder | Cannot be changed in the app. |
To move an agent to another machine or folder, add a new agent there and remove the old one. Its messages stay in the project.
Owners change these. Members can open the card and read it. A project keeps at least one agent, so the last one cannot be removed; archive the project instead.
Several agents in one project
Section titled “Several agents in one project”The strip above the message box shows the project’s agents. Choose the one your message goes to. To send to more than one, open the tools beside the message box and choose Choose several. Everything an agent writes as its reply is shown to everyone in the project.
Agents can also message each other. On an agent’s card, Talking to other agents has two rules:
- Can ask: who this agent may message.
- Can be asked by: who may message it.
Each is Nobody, This project, Chosen agents or Anyone in the organisation. A new agent starts with This project for both. A message goes through only when both sides allow it: the sender can ask, and the receiver can be asked by the sender. The card shows the result as Can reach, including agents reached through another agent.
Approvals
Section titled “Approvals”When an agent wants to do something its permissions do not cover, it stops and asks. A card appears in the conversation: the agent’s name, what it wants to do (run a command, edit a file, fetch a web page), and the exact command or change.
- Allow lets it go ahead. Deny tells the agent no, and it carries on without that action.
- Details shows the whole request with the project, folder and machine.
- The person who started the task is asked. An owner can always answer. Other people see the card but cannot answer it.
- A request nobody answers within 10 minutes is denied.
A tool set to Ask before each use asks in the same way, whatever the agent’s permissions.
Controls on the card
Section titled “Controls on the card”Stop stops the current task. New session starts the agent fresh: the old conversation stays in the project, but the agent no longer remembers it. Compact shortens what the agent is holding in mind so a long session can continue.
If the agent’s machine is offline, your messages are queued and delivered when it is back.