Codex / Workspace setup
Create a Codex Workspace from a Project Folder
Every Codex workspace is tied to one folder on your computer. Name the folders whatever fits your project, attach the right one in Codex, and start a chat from that project row.
Codex open2 minutesBeginner
Attach the project folder you want Codex to treat as home
Use any folder names you want. In this example, `My Agent Projects` is just the parent folder that keeps things organized, and `This Project` is the one you'll attach in Codex. Choose `Use an existing folder`, select `This Project`, then start a new chat from that project row. The final check: the new thread should show `This Project` with `Local` selected.
Attach the local folder and start the first workspace chat
- 1
The folder boundary decides what Codex can see
- Why
- Codex treats one folder as its entire working area for a project. You can use a parent folder to organize multiple projects, and then point Codex at the specific project folder inside it.
- Action
- Name the folders whatever fits your work. This example uses `My Agent Projects` as the parent folder and `This Project` as the project folder inside it.
- Result
- You have a project folder ready to attach in Codex.
- Tip
- The parent folder is for organization. The project subfolder is the one you will select in Codex.
- 2
Existing folders keep your local structure intact
- Why
- Since you already have a folder on your computer, you'll tell Codex to use that one instead of creating something new.
- Action
- In Codex, open `Projects`, click the add-folder control, and choose `Use an existing folder`.
- Result
- macOS opens the folder picker on your computer.
- Tip
- `Start from scratch` creates a new empty project. `Use an existing folder` is what you pick when you already have a folder set up.
- 3
The project folder becomes the workspace name
- Why
- Whatever folder you select here becomes the project name in Codex, so pick the specific project folder you want Codex to work inside.
- Action
- In the folder picker, open your parent folder if you made one, select `This Project`, and click `Open`.
- Result
- Codex adds `This Project` under `Projects`.
- Tip
- `This Project` is only the example name. If your folder is called `2nd-brain`, `personal-os`, or anything else, select that folder instead.
- 4
No chats means the project is attached but unused
- Why
- When you see the project row, Codex has the folder. 'No chats' underneath just means you haven't started a conversation there yet.
- Action
- Check the `Projects` list for `This Project`. It should appear with `No chats` under it.
- Result
- The folder is attached as a Codex project and ready for its first thread.
- 5
Start the chat from the project row
- Why
- Starting the chat from the project row connects it to that folder automatically. This is how Codex knows which files to work with.
- Action
- Hover `This Project` and click the new-chat control. The tooltip uses your folder name, such as `Start new chat in This Project`.
- Result
- A new composer opens for that project.
- Tip
- If you start a generic chat from outside the project, Codex won't have access to the folder you set up.
- 6
The active workspace should match the folder before you ask
- Why
- Quick sanity check before you type anything: make sure Codex is pointed at the right folder. A wrong selection here means Codex works in the wrong place.
- Action
- Before sending your first prompt, check that the top of the chat shows `This Project` and that `Local` is selected.
- Result
- Codex is ready to work in the attached local folder.
- Tip
- Select `Local` when you want Codex to read and write files directly in your folder. Worktrees are a separate feature for running multiple Git branches at once.
