Direct answer
The phrase add a project Codex refers to giving Codex a defined place to work and the context for that work. In the ChatGPT desktop app, a local project can connect to folders on your computer. This guide helps you choose the right project type, set its primary folder, and verify access before asking for changes.
Summary: add a project Codex can use
Create a local project when Codex needs direct access to a codebase or files on your computer. Attach the required folders, make the main repository primary, then start one focused chat for each outcome. A ChatGPT project is different because it carries uploaded files, instructions, and connected sources instead of direct folder access.
For the CLI, the directory where you start Codex becomes the project for that chat. The IDE extension uses the open folder or workspace as its local project. Match the surface to where the work and source files live.
Use a six-stage setup loop. Define the goal, create the project, attach folders, choose the primary folder, start a focused chat, and verify the workspace.
Choose the correct project type first
Project can describe several related setups. They share organization, but they do not provide the same context or file access.
- ChatGPT project
- keeps related chats, uploaded files, instructions, and connected sources together. It does not directly expose a local computer folder.
- Local project in the desktop app
- connects chats to one or more folders on your computer. Use it for a codebase or local file collection.
- Codex CLI project
- uses the directory where you start `codex`, or the directory supplied with `--cd` or `-C`.
- IDE workspace
- uses the folder or workspace open in the editor. Select the intended root when the editor has several workspace roots.
- Chat without a project
- fits a self-contained question that does not need shared files, instructions, sources, or folder access.
Add a local project in the desktop app
Use a local project when Codex must read or change files on your computer. Start from the desktop Projects view and keep the first setup narrow.
- Open the ChatGPT desktop app and sign in with the account that should own the work.
- From the Projects view, create a local project or open the folder that should become the project context.
- Open the project menu and select Edit project when you need to add or change folder access.
- Select Add folder, then attach only the repositories or file collections required for the related work.
- Point to the main repository and select Make primary. New chats will start from this folder.
- Start a new chat inside the project, choose Codex, and describe one concrete outcome with its acceptance criteria.
- Ask Codex to identify the working directory and relevant project rules before it edits files. Compare the answer with your setup.
Make the main repository the primary folder
The primary folder is more than a visual preference. Each new chat begins there, and Codex uses it as the default for Git operations. It is also the starting point for automatic discovery of `AGENTS.md`, skills, and `config.toml`.
- Select the repository that owns the task, branch, tests, and delivery workflow.
- Keep documentation or a related service as a secondary folder when the task needs both.
- Switch the primary folder when a different repository becomes the true owner of the work.
- Split work into separate projects when folders are unrelated or should not share chat access.
- Check the primary repository before using pull request or worktree actions. Those actions target that repository.
Use multiple folders only for one connected outcome
Related folders can share a project. Examples include an application with its documentation or a website with its backend. Secondary folders remain available for search, reading, and editing. Their own project files are not discovered automatically in the same way as primary-folder files.
Use one practical test: would the same reviewer expect these folders in one change or delivery? If not, separate projects usually produce clearer permissions, prompts, diffs, and ownership.
Set the project in Codex CLI or the IDE
The CLI and IDE do not expose the desktop ChatGPT Projects view. They derive project context from the active directory or workspace instead.
- CLI
- change into the intended repository, then run `codex`.
- CLI
- run `codex --cd <directory>` or `codex -C <directory>` when the shell is elsewhere.
- CLI
- use `/new` for a distinct outcome and `/resume` or `codex resume` to continue a saved chat.
- IDE
- open the intended folder or workspace before starting a Codex chat.
- IDE
- select the correct root in a multi-root workspace, then confirm which files are in the current turn's context.
Put durable rules in project files
A chat transcript stores the conversation, but repository guidance should live with the project. Use `AGENTS.md` or checked-in documentation for commands, conventions, boundaries, and review requirements that future chats must find.
- Name the approved package manager and the commands for tests, linting, type checks, and builds.
- State which directories a task may change and which generated or vendor files it should leave alone.
- Explain branch, ticket, commit, review, and deployment requirements in direct language.
- Record product rules, security boundaries, content standards, and source-of-truth locations.
- Keep task-specific acceptance criteria in the chat so durable guidance stays reusable.
Folder access and sandbox permissions are separate
Folder access and command permission are different. Attaching a folder makes it available to the project. The sandbox still controls what local commands can read, change, or reach over the network. Treat project structure and runtime permission as two separate checks.
- Confirm that the intended folder appears in the project before asking Codex to inspect it.
- Check the active sandbox and approval policy before commands need broader file or network access.
- Do not attach sensitive or unrelated folders merely to avoid a later permission request.
- Ask for a read-only orientation first when the repository or task boundary is unfamiliar.
- Review proposed commands and exact targets before approving material external or destructive actions.
Use focused chats and worktrees for parallel changes
A project groups related work, while each chat should own one distinct outcome. When two code changes must proceed in parallel, separate worktrees can isolate branches and files without creating unrelated projects.
- Use another chat for a separate feature, investigation, review, or release task.
- Use a worktree when parallel chats would otherwise edit the same working tree on different branches.
- Keep the project attached to the supporting folders that both worktrees still need.
- Before a worktree action, confirm the primary repository for branch and pull request targeting.
- Archive finished chats and rename active chats by outcome so project history stays searchable.
Verify the project before requesting changes
A short orientation prompt catches most setup mistakes before they become edits in the wrong repository. Ask Codex to report evidence instead of assuming the project is configured correctly.
- State the current working directory and identify the primary repository.
- List the attached folders that are relevant to the requested outcome.
- Find the applicable `AGENTS.md` files and summarize the instructions that control the task.
- Identify the package manager, project structure, test commands, and current Git branch from repository evidence.
- Explain which files are likely to change and which files remain outside the task scope.
- Report any missing access, conflicting guidance, dirty changes, or unclear ownership before editing.
- Wait for confirmation when the evidence points to the wrong project, branch, or folder boundary.
Troubleshoot common project setup problems
- Codex cannot see files
- edit the local project and attach the missing folder, then check sandbox access.
- Git commands target the wrong repository
- make the intended repository primary before starting the next chat.
- Project rules seem missing
- place `AGENTS.md` under the primary project path and ask Codex to report its discovery chain.
- A secondary repository has its own rules
- open it as primary or state the rules explicitly for the bounded task.
- Chats feel confused
- split outcomes into separate chats and move unrelated repositories into separate projects.
- CLI starts in the wrong location
- launch it from the repository or pass the directory with `--cd` or `-C`.
Frequently asked questions
In the ChatGPT desktop app, create a local project, open Edit project, select Add folder, and attach the repository. Make that repository primary, then start a Codex chat inside the project.
No. A ChatGPT project shares uploaded files, instructions, and connected sources across chats. A local project connects to folders on your computer for direct file work.
Yes. Attach multiple related folders in Edit project, then choose one primary folder. Use separate projects when the folders are unrelated or need different access boundaries.
A new chat starts there. Codex also uses it for default Git operations and automatic discovery of `AGENTS.md`, skills, and `config.toml`.
The directory where you start `codex` becomes the project for that chat. Use `--cd <directory>` or `-C <directory>` to choose another directory explicitly.
No. The project defines available context, while the sandbox and approval policy still govern file, command, and network access. Check both before work begins.