Suppose an API change adds a request identifier to each response. The implementation belongs in an application repository; the response example belongs in a documentation repository. For this task, I'd make the application the primary folder in Codex and attach the documentation folder. That choice gives the implementation work the appropriate starting directory and Git defaults. The documentation still needs its own instructions, checks and review target.
This guide concerns local projects used with Codex in the desktop app. The product behavior below comes from OpenAI's documentation checked on September 28, 2026. The two-repository task is illustrative. The accompanying Python exercise inspects synthetic files; it does not test native Codex behavior.
What the primary folder controls
A local project can contain multiple attached folders. In Edit project, use Add folder to attach another folder and Make primary to select the primary one. New chats start in that folder. Codex uses it for Git defaults and automatic discovery of project instructions, skills and configuration. Secondary folders remain available for reading, searching and editing, but Codex does not automatically discover their project guidance. OpenAI's projects guide documents these distinctions.
The same guide says the review pane can cover changes across attached repositories, while pull-request and worktree actions target the primary repository. Other attached folders remain attached when working in a worktree. Those rules make the primary choice a decision about the work you intend to carry through review.
For the response change, the application is the natural primary: its implementation and tests determine whether the new field exists. If the task were only to correct wording in the API documentation, with application code available as reference, I'd choose the documentation repository instead.
Map each repository to its part of the change
Use exact checkout paths, especially when several branches or worktrees are present. A repository name such as “application” doesn't tell a command where to run.
In this illustrative task, /work/application and /work/documentation are the two checkouts. The field to add is request_id. I would give Codex this map with the request:
| Task detail | Application | Documentation |
|---|---|---|
| Intended change | Return request_id and test its presence and meaning | Show the field in the response example and explain it |
| Exact checkout | /work/application | /work/documentation |
| Guidance to read | Application instructions and response contract | Documentation instructions and example/style rules |
| Required check | Response-contract tests, run from the application checkout | Example consistency and link checks, run from the documentation checkout |
| Review destination | Application diff and pull request | Documentation diff and its own repository review |
The check names describe what this fictional change requires. For a real task, replace them with the exact commands declared by each repository, including the directory in which each command runs. If a repository has no check for the new response field, specify the assertion to add: the application returns it, and the documentation example agrees with the tested response. Don't substitute a plausible command for one you have read in that project.
The secondary guidance needs an explicit instruction. For example:
Read the documentation repository's instructions and example rules before changing its response example. Show the instructions that affect this edit. If they conflict with the application contract, identify the conflict before choosing a representation.
Reading a file alone doesn't prove that the agent has followed it. The final review should compare both changes with the requirements: the application's tested field name, the documented field name and the field's explanation must agree.
Keep Git actions tied to the same map. A review pane containing both diffs doesn't make the documentation repository the target of the primary repository's pull-request action. State the repository for each branch, commit and review operation, and inspect its diff before proceeding.
Instructions, skills and configuration need different checks
AGENTS.md contains instructions for the agent. OpenAI describes a global instruction layer and a project chain from the project root toward the current working directory. Each directory contributes according to documented filename precedence, including AGENTS.override.md; size limits also apply. A primary folder therefore doesn't account for every instruction the agent might receive. Instruction discovery rules explain the chain.
A skill packages reusable instructions and optional resources. Current repository discovery uses .agents/skills directories along the path from the working directory up to the Git root, with separate user, administrator and bundled sources. A skill file found in an attached secondary folder is a candidate you can inspect; its presence doesn't establish selection for this task. OpenAI's skills guide documents discovery and invocation separately.
Configuration has another consequence. A secondary folder may contain .codex/config.toml, but asking an agent to read that file doesn't apply its settings to the running session. Project configuration has trust and precedence rules. If the task depends on a particular setting, check the effective configuration through the supported product controls. OpenAI's configuration guide describes those rules.
These distinctions change the instructions I would give for the documentation edit. “Read its contribution rules” is appropriate. “Its configuration must already be active because the folder is attached” is an unsupported assumption.
Run a bounded file inventory
The folder-map exercise contains a Python program and two synthetic folders. Each folder has an example instruction file. The documentation folder also has a comment-only configuration file. There is no Git repository or Codex project inside the exercise.
Extract the archive, open its codex-folder-map-example directory and run these commands with Python 3.10 or later:
python3 -B inspect_folders.py --demo
python3 -B inspect_folders.py --demo --primary documentation
The first run labels the application as primary; the second labels the documentation as primary. Both inspect the same files. The --primary argument is a label supplied to this program. It neither reads nor changes the desktop app's primary-folder setting.
For each supplied root, the program reads candidate instruction and configuration files and records their sizes and SHA-256 hashes. It also inventories skill files in immediate local skill directories when present. You can use those paths to decide which files need a closer read.
The program deliberately leaves these results unmeasured:
primary_setting_in_desktop_app: NOT_OBSERVED
native_loaded_instructions: NOT_OBSERVED
native_skill_selection: NOT_OBSERVED
execution_permissions: NOT_OBSERVED
git_repository_or_worktree_status: NOT_CHECKED
Its search is bounded to the supplied roots. It doesn't reproduce ancestor, global, plugin or custom-filename discovery, and it won't read a symlink target outside the inspected root. “Not present at this path” says nothing about guidance elsewhere.
To inspect your own folders, supply their actual paths as described in the archive's README. The program performs filesystem reads only. Its result is useful for assembling the task map; application state still needs inspection in the application.
Recheck the map when using a worktree
A Git worktree is another working directory for a repository. In the desktop workflow, the documented worktree action targets the primary repository. The statement that secondary folders remain attached does not establish that each received a new worktree. Projects and worktrees should be read with that distinction intact.
Suppose you inspect a worktree task and establish this layout:
| Repository | Checkout before the task | Confirmed checkout in the worktree task |
|---|---|---|
| Application, primary | /work/application | /worktrees/application-request-id |
| Documentation, secondary | /work/documentation | /work/documentation |
Those paths are an illustrative result, not a claim about where Codex creates worktrees. In this layout, a documentation edit would change the existing documentation checkout. If the task requires isolated documentation changes too, prepare and verify a separate documentation checkout through the supported workflow, then update the map to its actual path.
The response-contract tests must run in /worktrees/application-request-id. Running them in /work/application would test a different checkout. The documentation checks must run wherever the task's documentation edit actually resides.
Check access separately
A sandbox constrains what commands can access or change; approval rules determine when a request for broader access needs review. Choosing a primary folder doesn't replace either mechanism. OpenAI describes the separation in its sandbox guide.
Before executing the mapped checks, inspect the task's actual folder attachments, working directory and permission settings. If an operation is blocked, retain the exact error and resolve the access needed for that operation through the supported controls. Don't infer write permission from a successful file read or expand access merely to make the setup look uniform.
For the application-and-documentation task, the completed preparation is specific: application primary, actual checkout paths recorded, secondary guidance read, validation commands obtained from each repository, and two identified review destinations. After a worktree change, update the application path and inspect the documentation path again. Each command and diff should point to the checkout recorded in that map.