@bassam.cz
Free guide · BRAIN

One brain for Claude Code and Codex

Set it up in 15 minutes.

i use claude code and codex side by side. before this, every new chat started with me explaining my apps again, and neither agent knew what the other one did.

now they share one folder of notes on my laptop. each agent reads it before it starts and writes down what it did when it's done. so my claude code knows what my codex did today.

no app to install, no account, nothing leaves your laptop. it's markdown files and two rules.

what you need

what you're building

one folder called Brain. inside it, one short card per project. both agents read the card before they start and update it when they finish.

01make the folder1 minute

Copy this
mkdir -p ~/Brain/cards
cd ~/Brain && git init

git is optional. it gives you a history of every change an agent made, so a bad edit is one command to undo.

02write one card per project5 minutes

a card is the current truth about one project. not a diary, not chat logs. keep it under a page.

make ~/Brain/cards/your-project.md:

Copy this
# your project

## current state
what works today, in two or three lines.

## key decisions
- the decision, and why, with the date

## where things are
- code: ~/projects/your-project
- live: the url, if there is one

## open items
- the next thing to do

## unverified
- anything an agent claimed but nobody checked

## change log
- 2026-11-11 claude code: what changed, and how it was checked

start with the project you touch most. add the others as you work on them.

03give both agents the same rule3 minutes

put the same block in the global instructions of both tools, so it applies in every project:

Copy this
## brain (shared memory for every agent)
my notes live in ~/Brain/cards, one card per project.
1. start of task: read the card for this project before doing anything.
2. treat the card as dated notes, not proof. if the code says otherwise, the code wins, and say so.
3. end of task that changed something: update the card. current state, key decisions, open items, and one line in the change log with the date, your name (claude code or codex) and how you checked it.
4. never write guesses into a card. if you didn't check it, put it under unverified.
5. if there's no card for this project yet, create one from the template in another card.

rule 4 is the important one. without it, one agent's wrong guess becomes the other agent's fact.

04let them reach the folder2 minutes

both tools keep agents inside the project you opened. ~/Brain is outside it, so allow it once.

claude code, in ~/.claude/settings.json:

Copy this
{
  "permissions": {
    "additionalDirectories": ["/Users/you/Brain"]
  }
}

codex, in ~/.codex/config.toml:

Copy this
[sandbox_workspace_write]
writable_roots = ["/Users/you/Brain"]

swap /Users/you for your home folder (run echo $HOME).

05test the handoff3 minutes

  1. in claude code, do something small on the project. at the end, check the card got a new change log line.
  2. open codex in the same project and ask: "what did claude code do on this project today?"

if codex answers from the card, it's working. if it says it doesn't know, the rule isn't in ~/.codex/AGENTS.md or it can't reach the folder.

06read it yourself1 minute, optional

open ~/Brain as a vault in obsidian. it's the same files the agents read, so when a card is wrong you fix it there and both agents see the fix next chat.

three ways this breaks

when it grows

plain files work for a handful of projects. mine has over 30 project cards, chat history and old notes, so i added a small local search on top: a python script with sqlite full text search, plugged into both agents as an mcp server. agents call ask at the start instead of opening files. you don't need that to start. the folder and the two rules do most of the work.

built this way

this brain sits behind everything i build with claude code and codex: s8vr, cassette, watchtower, and the editor i cut my reels with.