Working on multi-repo projects

Lesson updated November 3, 2026 based on the Codex Cloud documentation: multiple repositories now live together in a Codex Cloud environment (the old codex.openai.com address is no longer the entry point). Source: Codex Cloud.

Managing the complexity of distributed architectures

Modern projects often span multiple repositories: a frontend, a backend, a shared library, a payment service. Each has its own lifecycle, CI pipeline, and maintainers. This setup works perfectly—until a change crosses repository boundaries. That’s where Codex changes the game: it can work across multiple repos simultaneously.

The real cost of a cross-cutting change

Consider a routine task: you add a field to an API response in the backend repository. You then need to update the API client in the frontend repository, the shared types in the common repository, the documentation in the docs repository, and the integration tests in the e2e repository. None of these four tasks is difficult in isolation. Together, they mean four context switches, four branches, four pull requests, and four chances to forget one. In practice, the documentation or the e2e tests get skipped, and the problem resurfaces three weeks later as a bug that no one traces back to that original commit.

Coordinating multiple repositories

In Codex Cloud, an environment can bring together multiple GitHub repositories: you select them when creating the environment, Codex sets up their dependencies and tooling, and every task launched in that environment works across the entire set. Your prompt then describes the change as a whole instead of isolating fragments:

"In the backend repo (api-service):
- Add a GET /api/v2/products endpoint with pagination

In the frontend repo (web-app):
- Update the API client to use the new endpoint
- Add pagination to the ProductList component"

Codex applies the changes in each repo and opens coordinated pull requests. Propagating a shared type follows the same logic, with one additional requirement you should state explicitly: verify that compilation succeeds in every affected repo. Without that instruction, you’ll discover the type error in the mobile repo’s CI two hours after merging everything else.

"The Product type in shared-types/src/product.ts has been 
modified (added tags: string[] field). 
Update all usages in:
- api-service: routes and services that use Product
- web-app: components that display a Product
- mobile-app: screens that display a Product
Ensure each repo compiles without errors."

Configuring AGENTS.md in a monorepo

If your project is a monorepo (Turborepo, Nx, Lerna), the logic flips: packages share a single file tree, and the hierarchy of AGENTS.md files carries the distinctions between them. The root file describes the overall structure and rules that apply everywhere:

# AGENTS.md (monorepo root)

## Structure
Turborepo monorepo with the following packages:
- packages/api — Fastify backend
- packages/web — Next.js frontend
- packages/shared — Shared types and utilities
- packages/e2e — Playwright end-to-end tests

## Rules
- Changes to packages/shared MUST be followed by a build 
  of all dependent packages
- Global build command: `turbo run build`
- Global test command: `turbo run test`

Each sub-package then builds on this foundation with its own conventions, without ever repeating what’s already in the root file:

# packages/api/AGENTS.md

## Backend API
- Framework: Fastify
- Validation: Zod (schemas in src/schemas/)
- Types from packages/shared are imported via @myorg/shared
- Every new route requires a test in __tests__/

Two reference cross-cutting workflows

The first covers a feature that spans the entire chain. Pay attention to the fourth instruction: the cross-link between pull requests might seem optional, but it’s what lets the frontend repo reviewer understand why this button exists without hunting down the corresponding backend PR.

"New feature: favorites system.
1. shared-types: Add the Favorite type
2. api-service: CRUD /api/favorites with auth
3. web-app: Heart button on product cards
4. Create a PR in each repo with links 
   to the other repos' PRs in the description"

The second covers migrating a versioned API. Here, the order of steps isn’t cosmetic: it guarantees that no client gets stranded mid-migration, with v2 in place and v1 still alive throughout the consumer migration window.

"API v1 /users is deprecated. Create v2:
1. api-service: Add v2 routes with the new format
2. api-service: Mark v1 routes as deprecated (header)
3. web-app: Migrate all calls from v1 to v2
4. mobile-app: Migrate all calls from v1 to v2
5. docs: Update the API documentation"

What Codex can’t do for you

Codex works repo by repo, in separate sandboxes. It can’t run two repos together: for example, you can’t launch the backend and frontend simultaneously for a real integration test. For cross-repo tests, the sequence remains manual:

1. Merge the individual PRs
2. Run integration tests from your CI/CD pipeline
3. Use Codex to fix any issues detected

In other words, Codex guarantees consistency of the written code, never consistency of the running system. Your CI/CD remains the final arbiter, and caution dictates that you shouldn’t deploy a series of coordinated PRs until it has rendered its verdict.

Key takeaways

• Codex can create coordinated PRs across multiple repositories
• Shared types are an ideal use case for multi-repo workflows
• Configure AGENTS.md in each package of a monorepo
• Cross-repo integration tests must still be verified in CI/CD
• Document inter-repo dependencies in AGENTS.md