Grounding a design in your codebase
A design written only from meetings can describe code that is not there. Grounding fixes that: Retain asks Codex, running on your Mac, read-only questions about your checkout, and writes the design against the answers, with the files cited. This page covers what you need, how to connect a folder, what Codex can and cannot do, and what stays on your computer.
What you need
- The Mac app, on a Mac with Apple silicon and macOS 26 or later.
- Codex installed on your Mac and signed in. Retain uses the Codex you already have and its own sign-in. It does not install Codex, sign you in, or change how Codex is billed. Claude Code is not used for this.
- A Git checkout of the project on that Mac.
Connect a codebase
Open a design step (see From a meeting to a design doc) and find the Codebase row.
- Open its menu and choose Choose Folder…, then pick the project's folder. Retain shows the repository, the folder, the branch, and whether you have uncommitted changes, which Codex will read too.
- Select Use This Codebase to allow Codex to read that folder. Nothing runs until you do.
- Pick the same folder again next time from the menu. Don't Use a Codebase or Write Without the Codebase writes the design from your meetings and email only.
If something is in the way, the step says what and offers a fix: Locate Folder… for a folder that moved, Choose Codex… and Check Again when Codex cannot be found or is not signed in.
In Settings > Setup you can see and stop the service that runs Codex, check which Codex Retain found, and stop using or forget a folder. Retain starts the service only when a document uses a codebase. It stops when you quit Retain, sign out, or an update installs. Closing the window does not stop it.
What happens when you write
The step shows where it is: Preparing your codebase, Checking the code, Waiting for your Mac to answer, then Writing the design.
- Retain's writer asks a handful of focused questions, some at the same time. Codex answers each from your checkout.
- Each answer separates what Codex saw in the code from what it inferred and what it proposes, and cites the file, symbol and line.
- Answers are kept short, and a design usually takes a few minutes, up to about ten.
- Keep Retain open and your Mac awake while it runs. Stop ends it and keeps what was written.
If you stop the service mid-run or Codex cannot answer some questions, the design is still written, and it says it is not fully grounded in the code. If the folder changes while Codex is reading, those answers are set aside and you can write again.
What Codex can and cannot do
Codex runs in a read-only mode: it cannot change files. Retain tells it not to install packages, switch branches or run builds, and to read no environment files other than the example one.
Ask about the code later
A document written with a codebase remembers which repository it used. With the document open on the Mac and that folder connected, the document chat can hand a question about the code to Codex and answer from its cited findings. If the folder is not connected, the chat says so and tells you what to do instead of answering from memory.
What stays on your computer
- The folder's location is kept on your Mac and never sent to Retain.
- Your Codex sign-in and billing stay with Codex.
- Under Settings > Activity > Codex you can read the questions Retain asked and Codex's answers. That log is kept on your Mac.
What does leave your Mac is Codex's findings and excerpts, which go to Retain so it can write the design. Retain stores them with the design, including the file paths they cite. See Privacy and security for the rest.
Once the design is written, build packets take it into your coding agent.
Need help?
Can't find what you're looking for? Contact our support team for a quick reply.
Contact Support