Skip to content

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.

You need a machine that is online and has Claude on it. See the Quick start.

  1. Choose New project.
  2. Project name is optional. Leave it blank and the agent suggests one.
  3. 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.

  1. In the project, open the project menu and choose Add an agent.
  2. 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.

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.

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.

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.

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.

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.