In this guide I teach you how to build a team of AI agents that works together, without explaining yourself to every chat again and again, without writing a line of code, and without losing track of who is doing what.
You build it by pasting 7 prompts, one per step, plus an extra and a bonus.
Let's start:
This guide is for you if
- Every chat seems to start from zero. You have to explain yourself over and over again.
- One chat does everything, gets long and slow, and loses the thread.
- You are the middleman. You carry messages between chats by hand.
- Your projects overlap. Two chats touch the same files and you find out too late, and they tend to mix up the context of different projects.
- You understand the power of having multiple agents and orchestrating them, but you don't know where to start and you feel intimidated.
By the end you'll have
- A central brain you talk to, which sends each job to the right place.
- One Lead per area of your work, each with its own folders and rules.
- Specialists that Leads open for a job and that report back by themselves.
- A shared memory every chat reads, so nobody asks you the same thing twice.
- Team rules that stop chats from stepping on each other.
- A check that proves the whole setup works.
- Optional: an outside agency, and a live page that shows your team at work.
You'll need:
- Claude Code Desktop, signed in with a Claude subscription.
- An empty folder on your computer for your workspace.
- Optional, for the Extra only: a ChatGPT subscription and the Codex app.
Read this first
This is my way of setting up an agent team. There are a thousand others.
- What matters is the concepts: what is possible and what it unlocks.
- Copy my setup, then change the names, the areas and the rules until it fits your work.
- Nothing here needs code skills. You paste a prompt, answer a few questions, and Claude Code writes the files.
- There is a faster way, with less control. Give Claude the URL of this page and ask it to build the team for you. It is quicker, but you decide less along the way. The step-by-step path below is the one that teaches you how your team works.
How it works
Four layers. Each one is a chat in Claude Code Desktop, with a short card (a .md file) that tells it who it is.
- The Brain. The chat you talk to. It sends work to the right place and keeps the team organised. It does no project work itself.
- Leads. One per area of your work. Each Lead is the only one allowed to write in its own folders (its zone).
- Specialists. Chats a Lead opens for a job: a web designer, a researcher, a fixer. Some stay, some live for one task.
- Outside agency (optional). Agents in another tool, such as ChatGPT, for light and creative jobs.
The idea that makes it work: cascade delegation.
- Any agent can open child chats and hand them tasks.
- The Brain opens chats under itself. A Lead opens chats under itself. A specialist can open its own.
- Each child gets a written brief, works alone, and reports back to the chat that opened it.
- Tasks go down. Reports come up, level by level.
- You talk to one chat. The work happens in many.
You
└─ The Brain
├─ Lead: Brand A
│ ├─ Specialist: web designer
│ └─ Task chat: one-off job
├─ Lead: Brand B
└─ Agency (optional, outside Claude)
The files are the memory. Chats come and go, so every rule, decision and note lives in a file, not in a chat.
01 / WORKSPACECreate your workspace and the main rules
Open Claude Code Desktop and start a chat in your empty folder. Paste the prompt. Answer the questions one at a time.
I'm setting up a workspace for a team of AI agents. This folder is the workspace. Help me create it, one step at a time.
About me: I'm a creator, not a developer. Use plain language and tell me what you are about to do before you do it.
Rules:
- Ask ONE question at a time and wait for my answer.
- Don't invent facts about me. If you don't know, ask.
- Don't install, download or delete anything.
- Never ask me for passwords or keys in this chat.
- If something fails, stop, explain it simply and propose a fix. No blind retries.
- Don't say it worked until you have checked the files exist.
Steps:
1. Ask me: my name, my language for the chat, and the 2 to 4 main areas of my work (for example a brand, a course, a client project).
2. Create one subfolder per area, and these folders: `_brain`, `_team`, `_log`, `_archive`.
3. Ask me three things and write the answers in the next file:
- What may agents do without asking me? (for example: edit local files, make drafts, run local tools)
- What must they ask me first? (for example: publish online, message real people, spend money, delete for good)
- Where do things live? (one line per area)
4. Create `CLAUDE.md` in the root with: who I am, the language rule, "do without asking", "ask first", "where things are", and these fixed rules:
- The truth lives in files, not in chats. Decisions, notes and to-dos get written to a file right away.
- Each project folder has its own `CLAUDE.md` with its rules. Read it before working there.
- Nothing is deleted. Old files go to `_archive`.
5. Create a short `CLAUDE.md` inside each area folder: what the area is, and "rules for this area" (empty list for now).
6. Show me the folder tree and the content of the root `CLAUDE.md`. Ask: "What would you change?" and fix it with me.
Check at the end: list every file you created and confirm each one exists.
Check: you have a root CLAUDE.md and one folder per area. Claude Code reads that file at the start of every chat in this folder.
02 / MEMORYGive the team a shared memory
One folder, _brain, with an index that every chat loads. The index is one line per entry. Details stay in separate files and are opened only when needed.
Paste in the same chat, or open a new chat in the workspace.
Create the shared memory of my workspace in the folder `_brain`.
Rules:
- Ask ONE question at a time. Never invent facts about me or my work.
- Never write passwords, keys or private numbers in any file. If a service needs a key, write only the name of the variable and where it is stored.
- Back up any file before changing it.
- Don't say it worked until you have checked the files.
Steps:
1. Interview me, one question at a time, to fill these entries (3 to 8 questions each, stop when I say enough):
- `me/profile.md`: who I am, my skills, how I like to work.
- `areas/<area-name>.md`: one per area: what it is, who it's for, what I offer, my tone of voice.
- `services.md`: the tools and services I use and what each is for. No keys.
- `glossary.md`: names and short forms I use that an outsider wouldn't know.
2. Create `_brain/INDEX.md`: a table with one row per entry: file, what it contains, "open it when...".
3. Add this line to the root `CLAUDE.md`: `@_brain/INDEX.md`. That makes the index load in every chat. The entries open only when a chat needs them.
4. Add a rule to the root `CLAUDE.md`: "If a fact changes, update the entry, not the index."
Check at the end: show me `INDEX.md` and the list of files. Confirm that the line `@_brain/INDEX.md` is in `CLAUDE.md`.
Check: open a new chat in the workspace and ask "What do you know about me and my areas?" The answer should come from the index and the entries.
03 / BRAINCreate the central brain
The Brain is a chat with a card. You'll start it with a fixed first message, so you can restart it at any time.
Create the team folder and the card for my central brain, "The Brain".
Rules:
- Ask ONE question at a time. Never invent facts.
- Don't delete or overwrite existing files. Back up first.
- Don't say it worked until you have checked the files.
Steps:
1. Create `_team/README.md` with:
- A table of team members: name, card file, role, zone (the folders only that member writes in). Add one row for The Brain, with `_team/brain.md` and the zone `_team/`.
- A section "Team rules" (empty for now, Step 6 fills it).
2. Create `_team/brain.md`, the card of The Brain, with these sections:
- **Mission:** I talk to The Brain. It makes the right member work and keeps the team organised.
- **Zone:** `_team/` only.
- **Does alone:** reads the recent chats and tells me what is waiting for me (title, the question in one line, a recommendation). Sends each task to the member who owns that zone, or opens a child chat with a complete brief. Keeps `_team/` up to date.
- **Asks me first:** archiving or stopping chats, publishing, messaging real people, spending money, deleting.
- **Never does:** project work inside another member's zone.
- **Handover notes:** a dated list. Empty for now.
3. Add to the root `CLAUDE.md`: "The team lives in `_team/`. The README lists members and zones."
4. Tell me how to start the brain: "Open a new chat in the workspace and send: `You are The Brain: read _team/brain.md and the handover notes, then introduce yourself in two lines.` Then pin the chat in the sidebar."
Check at the end: list the files and show me `brain.md`.
Then do what the last line says: open a new chat, send the first message, pin it. This is the chat you'll talk to from now on.
04 / LEADSCreate the Leads
One Lead per area. Each owns a zone: folders only that Lead writes in. If someone else needs a change there, they ask the Lead.
Send this to The Brain.
Create one Lead for each area of my workspace.
Rules:
- Ask ONE question at a time. Never invent facts about me.
- Don't touch any file outside `_team/` except the list below. Back up before changing a file.
- Don't say it worked until you have checked the files.
Steps, once per area:
1. Ask me, in one message with 3 short questions: what this Lead should aim for in the next 3 months, which folders are its zone, and what it must ask me before doing.
2. Create `_team/<lead-name>.md` with:
- **Mission:** one sentence, with the goal I gave you.
- **Zone:** the only folders this Lead writes in.
- **Reads:** the `CLAUDE.md` of its area, the matching `_brain/areas/` entry.
- **Does alone:** local and reversible work: drafts, files, local tools, tidying.
- **Asks me first:** publishing, messaging real people, spending, deleting for good, changes of direction.
- **How it works:** for a single task it opens a child chat with a complete brief, checks the result and reports to me. At the end of a task it commits only the files it touched, one by one (see the team rules in `_team/README.md`).
- **Handover notes:** dated list, empty for now.
3. Add one row for it to the table in `_team/README.md`.
4. Add the zone to the `CLAUDE.md` of the area: "Only <lead-name> writes here."
After all Leads:
5. Update `_team/brain.md`: the Brain sends each task to the Lead that owns the zone.
6. Tell me how to start each Lead: open a new chat and send `You are <lead-name>: read _team/<lead-name>.md and the handover notes, then introduce yourself in two lines.` Suggest I group each Lead's chats under its own sidebar section (create a group, move the chat in).
Check at the end: show me `_team/README.md` with the table.
Start each Lead the way the last line says. Pin only The Brain. Leads live in their own sidebar groups.
05 / SPECIALISTSChild chats and specialists
This is the most important step. It turns a list of chats into a team.
A chat opens a child chat. The child:
- appears nested under the chat that opened it;
- receives a written brief and works alone;
- reports back to the parent when it finishes a turn.
Two kinds of children:
- Specialists: stay. Example: a web designer under the Lead of your main brand. They have their own card and zone.
- Task chats: live for one job. Example: "write this guide", "fix this bug". When the job is done, the parent checks the result.
Send this to The Brain. It adds the delegation rules to every card, including its own.
Add delegation rules to my team, so every agent can open child chats and get reports back.
Rules:
- Ask ONE question at a time. Never invent facts.
- Back up each file before changing it. Don't delete anything.
- Don't say it worked until you have re-read every file you changed.
Steps:
1. Create `_team/delegation.md` with these sections:
- **When to open a child chat:** the task is separate, it can run alone, it ends in something of its own (a file, a page, a change). Not for quick things: a question, a read, one edit.
- **The brief (always complete, in your own words):**
- the task and why it exists;
- the files or folders involved, with full paths;
- what "done" looks like;
- limits: what not to touch, what to ask me first;
- where to leave long results (a file), so the report stays short.
- **The report:** the child ends with 3 lines: what it did, where the result is, what is not checked. Short enough to be read at a glance.
- **The parent's job:** read the report, check the result, then tell me. A report is a claim, not proof.
- **Specialists vs task chats:** a specialist gets a card in `_team/` and a zone. A task chat gets only a brief.
- **One writer per set of files:** two children never edit the same files at the same time. If their work may overlap, give each its own copy or run them one after the other.
- **No polling:** a parent doesn't check on children in a loop. The report arrives by itself.
- **When to close:** a task chat is closed when its result is checked. A specialist stays until I say otherwise.
2. In every card in `_team/` (including `brain.md`), add a section "Delegation" with one line: "Follow `_team/delegation.md`."
3. In `_team/README.md`, add: "Tasks go down, reports come up, level by level."
4. Ask me if I want a first specialist now (for example under a Lead). If yes, create its card in `_team/` with mission, zone, what it does alone, what it asks first. Tell me the first message to start it.
Check at the end: show me `_team/delegation.md` and the list of cards that now have the Delegation section.
Try it: ask the Brain: "Open a child chat, brief it to list the files in _team/ and report in 3 lines." The child should appear nested under the Brain and report back on its own.
Notes:
- You can also say it plainly: "Open a child chat for this and give it a brief."
- Claude Code Desktop may ask you to approve the first time a chat starts another one. Approve it.
06 / RULESSet the team rules
Rules that keep many chats from stepping on each other.
With one chat, the rules live in your head. With ten chats working at the same time, they have to be written down. This step puts them in one place, _team/README.md, which every chat reads.
- Each zone has one owner, so two chats never edit the same files.
- Chats pass work to each other with short, quoted messages, so nothing gets lost on the way.
- Every chat saves only the files it touched, so one chat never overwrites the work of another.
- Secrets stay in a
.envfile, never in chats or in the guide files.
The prompt asks you before it changes any rule. Keep the ones you need, rewrite the others.
Write the team rules into `_team/README.md`, in the section "Team rules".
Rules:
- Ask ONE question at a time. Never invent facts.
- Back up the file first. Don't say it worked until you have re-read it.
Write these rules (ask me before changing any of them):
1. **One owner per zone.** Only the owner writes in a zone. Anyone who needs a change there asks the owner.
2. **Quote me.** When a task is passed to another chat, the message includes my own words, quoted.
3. **Short reports.** An answer to another chat is a short report: what was done, where, what is not checked.
4. **Commit only what you touched.** At the end of a task, each chat saves its own files with git, naming them one by one. Never "add everything". Never touch files left by other chats.
5. **Ask before archiving.** Chats are archived only with my OK, one by one.
6. **Write it down now.** To-dos and dates go into files right away, each with an owner: "for me" or "for the agents".
7. **Handover.** Before a long chat ends, its member updates its handover notes. A new chat gets the card and continues.
8. **Secrets.** Passwords, keys and tokens live only in a `.env` file in the workspace, never in a chat or in any other file. `.env` is listed in `.gitignore`. Files mention only the name of the variable.
Then:
- If this workspace is not a git repository yet, ask me if I want to create one and do it with `git init` only if I say yes.
- Create `_log/todo.md` with two sections: "For me" and "For the agents".
- Add to the root `CLAUDE.md`: "Team rules are in `_team/README.md`. To-dos go in `_log/todo.md`."
Check at the end: show me the rules section and `todo.md`.
EXTRA / AGENCYAdd an outside agency (optional)
Skip this if you don't use ChatGPT. The team works without it.
An agency is a group of agents in another tool. Mine are light and creative: copywriters and a graphic designer. Claude handles code, files and publishing.
The rule that makes it work: Claude gives documentation, not briefs.
- You give: facts, sources, your words, what to leave out.
- They choose: format, angle, call to action.
Claude can wake an agency chat from the command line with Codex. It uses your ChatGPT subscription, with no API credits. You need the Codex app and command line signed in.
Add an optional outside agency to my team. The agency lives in ChatGPT/Codex. Claude only prepares documentation and a task queue.
Rules:
- Ask ONE question at a time. Never invent facts.
- Back up any file before changing it. Don't delete anything.
- Never write keys or passwords in files. Codex uses my own login.
- Don't say it worked until a command has actually returned a result.
Steps:
1. Ask me which agency roles I want (for example: one manager, one copywriter per brand, one graphic designer).
2. Create `_team/agency.md`, written as a card (with the sections Mission, Zone "none, outside Claude", Does alone, Asks me first, Delegation: "Follow `_team/delegation.md`" if it exists), and also with:
- the roles and what each one does;
- the rule "we give documentation, not briefs": facts and sources, my words, what to leave out, the text and path if already decided. The agency chooses format, angle and call to action;
- what stays with Claude: code, files, publishing;
- the flow: documentation file, one row in the queue, the agency delivers files, Claude checks facts, generates the page, publishes only with my OK.
3. Create `_team/agency-queue.md`: a table with columns Date, From, Brand, Task, Documentation, Status. Status goes: todo, working, delivered, published.
4. Check that Codex is installed: run `codex --version`. If it is missing, tell me where to get it and stop.
5. Show me the command to wake an agency chat from Claude, adapted to this folder:
`codex exec --skip-git-repo-check -s workspace-write -C <workspace-folder> -o <reply-file> "<prompt>"`
To continue an existing agency chat: `codex exec resume <chat-id> "<prompt>"`.
Ask me before running it for real.
6. Warn me about cost: resuming a long agency chat is expensive. For repeated jobs, start a new short chat that carries only the minimum context.
7. Add the agency to `_team/README.md` as an outside member, and tell the Brain in `_team/brain.md` that light creative tasks go through the queue.
Check at the end: show me `agency.md`, the queue file, and the output of `codex --version`.
07 / CHECKTest the whole setup
Send this to The Brain. It checks the files and runs a small delegation test.
Test my agent team setup end to end. Report only what you actually checked.
Rules:
- Don't change any file except the temporary test file below, and delete that file at the end.
- Don't ask me for passwords or keys.
- Don't say a check passed unless you looked at the real file or result.
Checks:
1. The root `CLAUDE.md` exists and contains the line `@_brain/INDEX.md`.
2. `_brain/INDEX.md` exists and every file it lists exists.
3. `_team/README.md` lists every card in `_team/`, and every card has the sections Mission, Zone, Does alone, Asks me first and Delegation.
4. No file in the workspace contains a password, a key or a token. Search for obvious patterns and tell me what you searched.
5. Delegation test: open ONE child chat. Brief it to create `_team/_test.txt` with the single word "ok" and to report in 3 lines. Check the file, then delete it.
Final report as a list: each check with PASS or FAIL, and for each FAIL the fix you propose. Do not fix anything without asking me.
Done when: every check passes and the child chat shows up under The Brain and reports back by itself.
BONUS / LIVEYour Live page
One local page that shows your chats at a glance:
- which ones are working;
- which ones are waiting for you;
- tokens used today per chat;
- your hours, the agents' hours and the multiplier.
It reads the chat history files that Claude Code keeps on your computer. It only reads. It never sends anything out.
Paste in a new chat in the workspace.
Build a small local "Live" page for my Claude Code chats, in the folder `live/` of my workspace.
Rules:
- Ask me nothing, build it, then show me the result.
- Read-only. Never write to, move or delete any file outside `live/`.
- The server listens ONLY on 127.0.0.1. No outside network calls, no extra packages (Python standard library only).
- Never read or print the file `~/.claude/.credentials.json`, or any key or token. Do not show chat contents, only titles and numbers.
- Don't say it works until you have run it and seen real numbers.
What to build:
1. `live/server.py`: a Python server (`http.server`) on `127.0.0.1:8799`. It serves `live/index.html` and a JSON endpoint `/api/live`.
2. Data source: Claude Code keeps one `.jsonl` file per chat in `~/.claude/projects/<folder>/`. Each line is a JSON object. Use these fields:
- `type` is `user` or `assistant` for messages; skip lines with `isSidechain` = true (sub-agents). A `user` line whose content is only a tool result is NOT a person typing, and neither are lines with `isMeta` or `isCompactSummary`, or text that starts with `<local-command-` or `<command-name>` (commands like /compact and /model);
- `timestamp` (ISO time), `sessionId`, `cwd`;
- on `assistant` lines: `message.model`, `message.stop_reason` (`end_turn` means the agent finished its turn; `tool_use` means it is still working; it can be null on partial lines, so use the last line that has a value), and `message.usage` with `input_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`, `output_tokens`;
- the chat's title: a line with `type` = `custom-title` has `customTitle`; if missing, use `agentName` from a line `type` = `agent-name`, then `aiTitle` from `ai-title`.
3. `/api/live` returns, for every chat file modified in the last 30 minutes:
- title (or the folder name if there is none), folder, model;
- state: `working` if the last meaningful line is an agent line with `stop_reason` = `tool_use`, or the last line is a person's message; `waiting` if the last agent line has `stop_reason` = `end_turn`, even when a command line like /compact came after it;
- context size now = input + cache read + cache creation tokens of the LAST assistant reply;
- tokens processed today = the sum of all four token fields over today's assistant replies of that chat, each reply counted once;
- a warning level: yellow above 150000 context tokens, red above 250000.
4. It also returns today's hours and the multiplier:
- split today's timeline of all chats into short blocks (a gap longer than 20 minutes starts a new block);
- "my hours" = time covered by lines where a person typed, counting 5 minutes of presence around each message, plus 2 minutes of reading after the last reply of a turn;
- "agent hours" = time covered by agent lines between two messages, counted without overlaps between chats at the same time;
- multiplier = agent hours divided by my hours (show "n/a" if my hours are 0). Label these numbers "estimate" on the page.
5. `live/index.html`: one page, dark, simple. Top: today's hours, agent hours, multiplier. Then two lists: "Working" and "Waiting for you", each row with title, folder, model, context bar (green, yellow, red), tokens today. It refreshes itself every 5 seconds with `fetch`. No frameworks.
6. Add `live/START.md` with the command to start it, and add the line "Live page: `py live/server.py`, then open http://127.0.0.1:8799" to the root `CLAUDE.md`.
Check at the end: start the server, call `/api/live`, show me the real numbers (titles and numbers only), then open the page. Tell me what you could not verify.
The usage limits of your subscription are not in this page, on purpose. Claude Code shows them with /usage.
TROUBLESHOOTINGCommon problems
- The Brain does project work itself. Tell it: "Send this to the owner of the zone." Check its card says it never works in another member's zone.
- A child chat doesn't appear. Ask the parent to open it again and approve the permission when Claude Code Desktop asks.
- Two chats edited the same file. Break the job in two, with one writer per set of files, or run the jobs one after the other.
- A new chat forgets the rules. Start it with its first message and card, as in Step 3. Check the root
CLAUDE.mdis in the folder you opened. - A chat got too long. Update its handover notes, open a new chat, send the first message again.
- Codex doesn't run. Check
codex --version, and that you're signed in to ChatGPT in the Codex app.
GOOD TO KNOWGood to know
- This is one way to do it. Rename the roles, merge or split the areas, add rules you need.
- Start small: The Brain and one Lead. Add the next one when you feel the need.
- Agents can be wrong. Read the reports, check the files, and keep the decisions for yourself.
- Everything lives in plain files. You can read, edit and back them up like any other file.
- Never put keys or passwords in chats or in these files. Keep every secret in a
.envfile (rule 8 in Step 6) and name only the variable in your notes. - Quick tip: ask your agent how to store secrets. For example: "Show me how to keep my API keys in a
.envfile and keep that file out of git."
Your action checklist
Don't close this page yet. Do these, in this order, and tick them off.
- Today, 10 minutes: create an empty folder for your workspace and open it in Claude Code Desktop. Paste the Step 1 prompt.
- Today: answer the questions about your name, your areas and what Claude may do without asking. Open
CLAUDE.mdand read it once. - Today: paste the Step 2 prompt, then open a new chat and ask "What do you know about me and my areas?". If the answer is wrong, fix the memory entry, not the chat.
- This week: create the Brain (Step 3) and one Lead for your busiest area (Step 4). Leave the other areas for later.
- This week: do the Step 5 test: ask the Brain to open a child chat that lists the files in
_team/and reports in 3 lines. Confirm the child appears under the Brain. - This week: paste the Step 6 rules and run the Step 7 check. Fix anything that fails before you add more.
- Next week: give your first real job to the Brain, read the report, and write one new rule for whatever went wrong.
- When you're ready: add the Extra (outside agency) or the Bonus (Live page). Neither is needed for the team to work.
- Always: keep passwords and keys in a
.envfile, never in a chat.
Would you like to see my progress while using AI agents? Check out my live dashboard.