Workspace with multiple repositories showing the repository panel with two repos
Workspaces support working across multiple repositories and running multiple Codex threads on the selected registered host.

​
Multi-Repository Support

Add multiple repositories to a single workspace to work on cross-repo tasks.

​
Adding Repositories

Repository selection showing selected repo with branch dropdown and list of available repositories to add
When creating a new workspace, add multiple repositories from the create view:
  1. Click the + button in the workspace sidebar
  2. Select your project from the dropdown
  3. Click repositories from the Add Repositories list to include them
  4. Set the target branch for each selected repository
  5. Each repo maintains independent git state

​
Working Across Repos

With multiple repositories in a workspace:
  • Reference code from one repo while implementing changes in another
  • Implement coordinated changes across multiple codebases
  • Manage git operations independently per repository
  • View changes from all repos in a unified diff view

​
Repository Panel

Each repository in the workspace shows:
InformationDescription
Repository nameWith status indicator
Current branchThe working branch
Target branchBranch to merge into
Changes countUncommitted modifications
Commits ahead/behindRelative to target branch

​
Per-Repository Actions

Access repository-specific actions via the command bar:
  • Copy Repo Path - Copy the repository path
  • Repository Settings - Configure repo options
  • Git Operations - PR, merge, rebase per repo
Use the command bar’s Repo Actions page to quickly switch between repositories when performing git operations.

​
Multiple Threads

Thread dropdown in chat box toolbar showing multiple threads
Create multiple Codex conversation threads within a single workspace.

​
Why Use Multiple Threads?

  • Token limits: Start fresh threads when conversations get long
  • Parallel work: Run different tasks or Codex configurations simultaneously
  • Code review: Start a dedicated review thread
  • Experimentation: Try different approaches in separate threads

​
Creating a New Thread

  1. Click the thread dropdown in the chat box toolbar
  2. Select New Thread from the dropdown
  3. Select the Codex configuration to use for the new thread
  4. Start your conversation

​
Switching Between Threads

The thread dropdown in the chat box toolbar shows all threads:
  • Latest - the most recent thread
  • Older threads show their creation timestamp
  • Click any thread to switch to it
  • Each thread maintains its own conversation history

​
Thread Indicators

IndicatorMeaning
RunningAgent is actively processing
IdleThread waiting for input
ConfigurationShows which Codex configuration is assigned

​
Running Multiple Threads

Different threads can use different Codex configurations:
  1. Create a new thread
  2. Select a different Codex configuration
  3. Both threads can run in parallel
  4. Switch between them to monitor progress
Each thread operates independently. Changes made by one Codex thread are visible to other threads through the shared workspace files.

​
Example: Full-Stack Feature

Here’s a practical workflow for implementing a feature across frontend and backend repositories:
1

Create workspace with both repos

Create a new workspace, select your project, and add both frontend and backend repositories. Set target branches to main for both.
2

Describe the full task

In your initial message, describe the complete feature:
Add a user profile page:
- Backend: Create GET /api/users/:id endpoint returning user data
- Frontend: Add /profile/:id route with a UserProfile component
- The frontend should fetch from the backend endpoint
3

Agent works across repos

Codex reads code from both repositories and makes coordinated changes. It understands the relationship between frontend and backend.
4

Test integration

Start the dev server (if configured for one repo, you may need to start the other manually via terminal). Test that the frontend correctly calls the backend.
5

Create separate PRs

Create a PR for each repository:
  1. Open command bar (Cmd/Ctrl + K)
  2. Go to Repo Actions
  3. Select Create PR for the backend repo
  4. Repeat for the frontend repo
  5. In PR descriptions, reference the related PR
6

Merge in order

Merge backend first (since frontend depends on it), then merge frontend.

​
Best Practices

​
Multi-Repo Workflows

  • Start with a plan: Describe the cross-repo changes needed upfront
  • Coordinate commits: Ensure related changes are committed together
  • Test integration: Use the preview to verify repos work together
  • Create linked PRs: Reference related PRs across repositories (e.g., “Related to frontend#123”)

​
Thread Management

  • One focus per thread: Keep each thread focused on a specific goal
  • Document in notes: Use workspace notes to track which thread does what
  • Limit concurrent threads: Too many active threads can be confusing
  • Review before switching: Check the changes panel when switching threads
When multiple threads modify the same files, the last write wins. Review the Changes panel carefully to ensure nothing was overwritten unexpectedly.