AI Guides › Step-by-step guides
By Nigel Guy · 8 min read
The usual mistake is treating your notes app as the brain and each AI agent as a visitor who gets briefed from scratch in chat. With one agent that feels fine: you paste the context, it does the job, the knowledge lives in your head and your notes. Add a second agent and it falls apart, because neither agent can see what the other did, and you become the copy-and-paste layer between them.
The rule: give every agent the same written place to read rules from and write progress to, and make the agents use it before they use the chat.
This guide builds that place, which we'll call the Shared Desk: a Notion page tree that Claude Code and OpenAI's Codex CLI both reach through Notion's official MCP server, plus one instructions file that tells both agents to check it first.
| You need | Notes | Cost at time of writing |
|---|---|---|
| Claude Code | Included with paid Claude plans (Pro, Max, Team, Enterprise), not Free. Check the current £ price on Anthropic's pricing page. | Paid plan required |
| Codex CLI | OpenAI's help centre lists Codex on ChatGPT plans including Free, with usage limits that vary by plan. | £0 to start |
| A Notion workspace | The Free plan is enough to begin. Some Notion MCP features (filtering search by editor, meeting-notes queries) need Business or above. | £0 on Free |
| A project folder | Any folder you open both agents in. | £0 |
| Option | How agents reach it | Good for | Catch |
|---|---|---|---|
| Notion (this guide) | Notion's hosted MCP server, signed in with OAuth | Working across machines; people who already live in Notion | Cloud service; agents act with your Notion permissions |
| An Obsidian vault | It is a folder of Markdown files, so agents read and edit it directly if you open them inside it | Local-first, private work | Only shared across machines if you sync it (Obsidian Sync is paid) |
| A Git repository | Plain files, committed and pushed | Teams already using Git | Needs Git habits from everyone, human and agent |
Obsidian itself is free for personal and work use. Nothing here asks you to abandon it; the point is that a notes app on its own is not a shared workspace for agents.
In a terminal, inside your project folder, run:
claude mcp add --transport http notion https://mcp.notion.com/mcp
That adds the server at the default local scope (this project, just you). Add --scope user to make it available in every project, or --scope project to write it to a .mcp.json file you can share through version control.
Then start Claude Code, type /mcp, choose notion and complete the sign-in in your browser. You can also run claude mcp login notion from the command line. Notion's MCP uses OAuth only; there is no token to paste.
Run:
codex mcp add notion --url https://mcp.notion.com/mcp
codex mcp login notion
The first line writes a [mcp_servers.notion] entry to ~/.codex/config.toml; the second opens the OAuth sign-in. If you prefer editing the file, Notion's own docs give this block:
[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"
Confirm with codex mcp list, or type /mcp inside the Codex interface. Sign in with the same Notion account in both tools, or make sure both accounts can see the same pages.
Open either agent and paste the prompt below. It plans first, asks before it builds, and interviews you so the two most important pages are not invented.
Fill in: [WORKSPACE_OR_PARENT_PAGE] (where the desk should go) and [WHAT_YOU_DO] (one or two lines about your work).
Role: you are setting up an operations workspace in Notion that several AI agents
will share. You have Notion tools available through MCP.
Context: I work on [WHAT_YOU_DO]. Create everything under [WORKSPACE_OR_PARENT_PAGE].
Goal: one top-level page named "Shared Desk" containing exactly five children:
1. Ground Rules - my writing style, actions an agent may take alone, actions that
need my approval first, and who to escalate to when unsure.
2. Playbooks - one child page per recurring job, each written as numbered steps a
newcomer could follow with no other context.
3. Reference - facts agents need: what I sell, current prices, audience, brand
notes, key links.
4. Task Board - a database with properties: Title (title), Status (select: Backlog,
Working, Awaiting review, Closed), Assignee (select: one option per agent name),
Log (text).
5. Review Tray - a page where finished outputs are linked for me to check.
Steps, in order:
a) Show me the page tree and database schema as a list. Create nothing yet.
b) Wait for me to approve or edit the plan.
c) Ask me up to ten questions, one per message, to fill Ground Rules and Reference.
d) Build the pages, then draft Ground Rules and Reference from my answers.
Constraints: do not touch existing pages outside the parent I named. If an input
above is missing or still in square brackets, ask for it rather than guessing.
Tag every sentence you inferred rather than heard from me with [CHECK].
Before replying each time, check: have I created anything I wasn't approved to
create, and is every guess tagged?
If Status or Assignee come out as plain text, ask the agent to switch them to select properties.
Agents only check the desk if their standing instructions say so. Codex reads AGENTS.md files (global at ~/.codex/AGENTS.md, plus project-level ones from the repo root down). Claude Code reads CLAUDE.md; recent versions also read AGENTS.md when no CLAUDE.md exists, and you can always import it by putting the line @AGENTS.md at the top of a CLAUDE.md.
So write the rules once, in AGENTS.md at your project root:
# Working agreement for all agents
## On starting any task
- Open "Ground Rules" under "Shared Desk" in Notion and follow it.
- Look in "Task Board" for rows where Assignee is you.
- If a page in "Playbooks" covers the task, follow its steps in order.
## During the task
- Record progress in the row's Log property, not only in this conversation.
- Take facts from "Reference". If a fact is missing, ask me [YOUR_NAME], then add
the answer to Reference with today's date.
## On finishing
- Set Status to "Awaiting review" and link the output in "Review Tray".
- Never set Status to "Closed". Only a human closes tasks.
Fill in [YOUR_NAME]. If the project also has a CLAUDE.md, add @AGENTS.md as its first line so Claude Code loads the same rules. Run /context in Claude Code to confirm the file appears under memory files.
Create a Task Board row assigned to the first agent, let it finish, then give the second agent this prompt.
Fill in: [TASK_TITLE] and [AGENT_NAME].
You are picking up work another agent started. Read "Ground Rules" in the Shared
Desk first. Then open the Task Board row titled "[TASK_TITLE]" and read its Log and
the linked output in Review Tray.
Your job: review that output against the matching Playbook, fix what falls short,
and append a dated entry to the Log saying what you changed and why. Reassign the
row to [AGENT_NAME] only if the Playbook says a further step belongs to them.
Output: a three-line summary in chat (what you found, what you changed, what still
needs a human). If the row or Playbook is missing, stop and tell me instead of
improvising. Before finishing, confirm Status is "Awaiting review", not "Closed".
claude mcp list and codex mcp list both show notion.AGENTS.md, imported where needed, stops the two from drifting apart.