Support multiple workspace folders in the Codex app

A concrete remote-operations use case that reinforces this request:

I use Codex Desktop on Windows as the primary UI for operating a remote Linux homelab. A single logical Codex project needs to group several related but independently versioned areas, for example:

/srv/homelab/
  services/media/.git
  services/ai/.git
  services/rag/.git
  apps/custom-app/.git
  projects/
  models/
  staging/
  logs/

The project is an operational workspace, not a monorepo. Individual threads specialize in media, AI, backups, networking, migrations, or a specific application, and a single task can legitimately span more than one child repository plus non-Git directories.

Today the Desktop app accepts only one root path. The available choices are both poor:

1. Select each repository as a separate Codex project: Git works correctly, but the app loses the umbrella project organization and cross-domain context.
2. Select the parent directory: organization and context work, but the app repeatedly treats the parent as if it should be a Git repository, probes for <parent>/.git, produces unnecessary prompts/failures, and may spend session time/tokens trying to force Git semantics onto a non-repository workspace.

The CLI already has partial primitives such as --add-dir and writable_roots, but using the CLI defeats the Desktop app's better UI/UX for remote operation.

The ideal Desktop behavior would be:

• one saved project/workspace with multiple attached roots;
• each root independently marked read-only or read-write;
• Git detection and diff/status scoped per attached repository;
• non-Git roots explicitly supported without prompting to initialize Git;
• AGENTS.md discovery per root;
• threads able to choose a default working root while retaining access to the other attached roots;
• support for remote roots, not only local folders.

This is a significant UX blocker for using Codex Desktop as an operational command center rather than only as a one-repository coding client. It also overlaps with #26338, but the need here is broader than multi-repo detection: the workspace must include both Git and non-Git directories without forcing the workspace root itself to become a repository.

A particularly useful Codex Desktop/worktree use case for this request is a primary writable repository with persistent read-only reference repositories.

Example:

Codex project: Backend
- backend/   primary repository, read-write, managed worktrees enabled
- frontend/  attached reference repository, read-only

A backend task could then implement an endpoint based on types and API usage already defined in the frontend, without being allowed to modify the frontend.

The current trade-off is awkward:

• Opening the backend repo directly preserves Codex-managed worktrees, but loses convenient access to sibling repositories.
• Opening the common parent directory exposes both repos, but the parent is not itself a Git repository, so the Codex app does not offer managed worktrees.

Suggested semantics:

• Let a local Codex project attach additional folders or repositories with an explicit access mode, defaulting to read-only.
• Make attached reference roots available to every chat and Codex-managed worktree belonging to that project.
• Restrict edits, patch tools, setup scripts, and Git operations to the primary writable repository.
• Exclude reference repositories from staging, commits, handoff, and worktree lifecycle operations.
• Show each root and its effective access mode clearly in project settings and the task UI.
• Allow sensitive files or patterns such as .env to remain denied even inside an attached reference root.
• Optionally let users choose whether a reference repository follows its current local checkout or is pinned to a branch/commit snapshot when the task starts.

This would preserve worktree isolation for parallel tasks while still giving Codex the cross-repository context needed for frontend/backend contracts, shared libraries, schemas, and related services.

+1

This would be a huge unlock for real multi-repo / multi-folder workflows (e.g. frontend + backend + shared libs in one agent session).

Cursor’s Agents UI/UX is excellent for this: multi-workspace + multi-root workspaces make it natural to keep several project roots in one place, switch context, and let an agent work across folders without splitting everything into separate projects/threads. Something in that spirit for the Codex app would be fantastic.

Post-26.715 feedback from a frontend + backend multi-repository workflow:

The new multi-folder local project support is a strong start, but the current primary-folder semantics still leave an important correctness gap. The release notes say that new chats, Git operations, and automatic discovery of AGENTS.md, skills, and config.toml use the primary folder, while secondary folders are available for search, reading, and editing.

In my setup, one logical product contains two independent repositories:

• frontend/ with its own AGENTS.md, toolchain, Git history, and frontend rules
• backend/ with its own AGENTS.md, toolchain, Git history, database safety rules, and backend rules

A single task frequently changes both repositories. If Codex can edit the secondary backend repository but does not automatically discover and apply its AGENTS.md, it can perform valid filesystem edits while missing the repository-specific development and safety instructions. Requiring the primary AGENTS.md to manually point at every secondary AGENTS.md is fragile and makes project correctness depend on duplicated glue instructions.

I do not think eagerly concatenating every AGENTS.md into one global prompt is the best solution either. Instructions can conflict, and loading unrelated rules increases context usage. A root-aware model would be safer:

1. Keep a primary folder only as the default for new chats, fallback working directory, and default Git target.
2. Discover AGENTS.md, skills, and project config independently for every attached root.
3. Scope each root instruction hierarchy to files and commands operating inside that root.
4. When a turn spans multiple roots, apply the frontend rules to frontend operations and backend rules to backend operations rather than globally merging both rule sets.
5. Provide a project-level/shared instruction layer for rules that intentionally apply across all attached roots.
6. Show which root and instruction sources are active, especially when a task crosses repositories or rules conflict.
7. Let both Files and Review switch repositories and keep the selected repository visible. The Review selector gap is also tracked in #34444.

This would preserve a useful primary default without making secondary repositories second-class development targets. Cursor is a useful UX reference for switching workspace roots, but Codex also needs explicit per-root instruction scoping because AGENTS.md can contain build, test, security, and database requirements.

Is primary-only AGENTS.md discovery an intentional long-term design, or is per-root, path-scoped discovery planned for multi-folder projects?

So. the best solution then to make it all compatible with many usages described here that somehow deviated a little to different directions is to enable 'project' path/origin to be optionally 'project dir' or 'workspace dir'.

'Project dir' aims at current way of work (forced git project), treating it as a git project, while 'workspace dir' does not treat as git project but a group of folders that must work together to achieve an objetive, inside a sandbox.

Both methods should allow default structure configurations and mapping or custom mapping, allowing to load agents, skills, etc - from custom path mapped.

I think this way would work for everyone that proposed a solution on this issue while giving flexibilty for new ways of project configuration that we have not seen yet without adding too much complexyty to the UI/backend.