Give Codex a Map of Your Monorepo
Codex needs boundaries, not your entire monorepo
In a monorepo, the hard part is rarely writing the function. It is finding the right package, understanding who imports it, and running the correct checks without rebuilding half the company. Codex can inspect files, search symbols, and execute commands, but that does not mean every workspace automatically becomes useful context. Give it a small, explicit map before asking it to edit.
This walkthrough assumes an existing pnpm workspace with apps/web, apps/api, and packages/contracts. Substitute your actual paths and package scripts. Run everything from the repository root unless a command says otherwise.
1. Inventory workspace boundaries before opening Codex
Start with the same reconnaissance you would do before touching an unfamiliar checkout: — git status --short
git ls-files 'AGENTS.md' '*/AGENTS.md' 'AGENTS.override.md' '*/AGENTS.override.md' — cat pnpm-workspace.yaml
pnpm -r list --depth -1 — rg --files -g package.json -g '!node_modules' -g '!dist'
The package list tells you the workspace names used by pnpm filters. The paths tell you where instructions belong. Check existing instruction files before creating anything: the commands below overwrite their destinations. Also inspect any untracked instruction files reported by git status.
2. Put the repository map in AGENTS.md
Codex discovers instruction files along the directory path to its working directory, starting with broader guidance and adding more specific guidance. AGENTS.override.md takes priority over AGENTS.md within the same directory. Existing user-level instructions can also apply. Do not assume launching at the root automatically loads every nested instruction file.
Create a concise root map if one does not already exist:
printf '%s\n' '# Repository map' '' 'apps/web: browser application.' 'apps/api: HTTP service.' 'packages/contracts: shared request and response types.' '' '# Working rules' '' 'Inspect package.json before choosing validation commands.' 'Before editing a subtree, read its AGENTS.md and any AGENTS.override.md.' 'Change shared contracts before updating their consumers.' 'Do not edit generated files; locate their generator instead.' 'Do not modify unrelated working-tree changes.' 'Report commands run, results, and checks not run.' > AGENTS.md
This is routing information, not a second README. Keep architecture essays elsewhere and name their paths here when they are genuinely useful. Instruction discovery has a size budget, so a short operational map beats a pasted documentation archive.
3. Add API-specific instructions beside the service
Put local constraints close to the code they govern: — mkdir -p apps/api
printf '%s\n' '# API service boundaries' '' 'Read package.json for available scripts.' 'Shared request and response types live in ../../packages/contracts.' 'Preserve existing authentication and error-response conventions.' 'Add or update regression tests for changed behavior.' 'Ask before adding dependencies or changing public response shapes.' > apps/api/AGENTS.md
Launch from that directory when the task is API-local:
cd apps/api && codex
That makes the service instructions part of startup discovery. For a cross-package task launched from the root, explicitly ask Codex to read each affected package's instructions before editing. A nested file is not a magic repository-wide rule.
4. Give Codex a bounded cross-package task
Back at the repository root, start a session: — codex
Use a prompt with scope, sequencing, and a stopping condition:
Read AGENTS.md and the instructions in apps/api and packages/contracts. Find the create-project endpoint and its shared request type. Add optional clientRequestId support using existing naming conventions. First summarize affected files and available validation scripts; do not edit until I approve the plan. Avoid apps/web unless a consumer actually requires changes.
The important bit is not the wording. It is making Codex establish the dependency boundary before modifying code.
5. Verify the affected workspace, then inspect the diff
After approving the plan, have Codex run only scripts that actually exist. If both packages define test and typecheck scripts, these commands target them without guessing package names:
pnpm --filter ./packages/contracts --filter ./apps/api run test
pnpm --filter ./packages/contracts --filter ./apps/api run typecheck
git diff --check — git diff --stat
git diff — Then check downstream consumers when shared contracts changed. Targeted checks shorten feedback; they do not replace required integration tests or CI.
Keep the repository map portable through Fluxo
I keep these instructions in Git rather than in provider-specific prompts. Fluxo works with Codex, Claude Code, Gemini CLI, and any OpenAI SDK, using one key and one base URL, https://api.fluxorelay.com, for Claude, GPT, Gemini, DeepSeek, Kimi, GLM, Qwen, Grok, and more. GPT-6 Astra and Claude Sonnet 5.5 are two concrete model choices; neither replaces repository guidance.
Fluxo bills per real token, including cache reads and writes, with no monthly fee; users also earn a referral share when people they invite pay. If that fits your terminal workflow, create a Fluxo account and try it with one narrowly scoped repository task.