Codex and Monorepos: Scoping the Workspace

A monorepo's defining feature — everything in one place, one git history, one set of dependencies shared across many projects — is exactly what makes scoping a Codex session inside one deliberately harder than scoping one in a single-purpose repository. Without deliberate boundaries, a session working "in the repository" can mean anything from one small package to the entire organization's codebase.

Why the default sandbox boundary isn't automatically the right scope

Codex's workspace boundary under workspace-write is the directory the session was started in — which, for a monorepo, might be the repository root, giving a session technical access to every project inside it even when your actual task only concerns one. Technical access and intended scope aren't the same thing, and relying purely on the sandbox boundary to keep a session focused on the right subset of a large monorepo is asking a safety mechanism to do a task-scoping job it wasn't built for.

Starting sessions rooted in the actual subproject

The more reliable fix is starting a session's working directory inside the specific subproject the task actually concerns, rather than at the monorepo root — which narrows the sandbox boundary itself to match your intended scope, rather than relying on instructions alone to keep a broadly-scoped session from wandering. For a task genuinely confined to one package, this is both simpler to reason about and structurally safer than a root-scoped session you're trusting to stay focused.

When a task genuinely spans multiple packages

Some real changes do need to touch several packages at once — a shared interface change that ripples through every consumer, a dependency bump that needs coordinated updates. For these, root-scoped access is genuinely necessary, and the discipline shifts from narrowing the sandbox to being explicit about exactly which packages are actually in scope for this specific task, stated directly rather than left for the session to infer from the size of the repository it finds itself in.

AGENTS.md at the monorepo root versus per-package

A single root-level AGENTS.md trying to describe conventions for every package in a large monorepo tends toward genericity that isn't specific enough to be useful for any one package. Whether your setup supports nested AGENTS.md files per subdirectory is worth checking against the current config reference — if it does, package-specific files describing that package's own conventions, alongside a root file covering only genuinely repo-wide conventions, produces more useful, targeted context than one file trying to cover everything.

Dependency graphs and unintended blast radius

A monorepo's shared dependency graph means a change that looks contained to one package can have downstream effects on other packages that depend on it, in ways that aren't obvious from looking at the changed package alone. Running whatever your monorepo's tooling provides for detecting affected downstream packages — most mature monorepo setups have something — after a Codex session makes a change is worth doing as a standing habit, not just for changes that look obviously shared.

Performance considerations specific to large monorepos

A very large monorepo can mean a large amount of file content available for Codex to read into context if a task's scope isn't narrowed, which interacts directly with both session cost and the long-context repricing threshold on models that publish one. Narrowing working-directory scope isn't just a safety and correctness practice in a monorepo context — it's also a direct, practical lever on how much a session accumulates in context before it even gets to the actual task.

A reasonable default policy for monorepo work

Scope every session to the smallest subproject that plausibly contains the task, state explicitly when a task requires broader, multi-package access rather than defaulting to root-scoped sessions out of convenience, and maintain package-level AGENTS.md context where your tooling supports it. None of this is exotic — it's the same "narrowest sufficient scope" discipline this site recommends for sandbox mode generally, applied specifically to the added complexity a monorepo's shared structure introduces.

Shared tooling and configuration files as their own scope question

A monorepo often has genuinely shared configuration — a root-level lockfile, shared build tooling, a shared CI configuration — that sits outside any individual package but affects all of them. A session scoped to one package generally shouldn't need to touch these, and a session that does propose changing shared root-level configuration as part of a package-specific task is worth treating as a signal to stop and check why, since that's exactly the kind of unplanned scope expansion worth catching in review rather than approving because the rest of the diff looked reasonable.

Coordinating parallel sessions across different packages

A monorepo's structure makes it a natural fit for the kind of parallel, worktree-based sessions this site covers separately — different tasks in different packages, run as genuinely independent sessions rather than one broadly-scoped session trying to juggle several packages' concerns at once. The same coordination concerns apply here as with worktrees generally: parallel sessions in a shared-history monorepo will eventually need their changes reconciled, and treating them as parallel branches of work rather than a way to avoid ever thinking about how the pieces fit together is the right mental model.

Onboarding a monorepo to agentic work incrementally

If a large, established monorepo hasn't used agentic coding tools before, it's worth introducing scoped sessions to one package at a time rather than immediately running broadly-scoped sessions across the whole repository — building confidence in how a narrowly-scoped session actually behaves on one contained piece of the codebase before trusting a wider scope with less oversight. This mirrors the general advice elsewhere on this site about starting conservative and loosening deliberately, applied at the scale of an entire codebase's rollout rather than a single session's sandbox settings.