You ask Codex to keep working on a long-running branch. It starts, then stops with merge conflict in src/api/handler.ts. Or worse: it commits a file that still contains <<<<<<< HEAD markers. Or it picks the wrong side wholesale, throwing away logic that landed on main last week.
Fastest fix: rebase the branch onto the base branch before you launch the Codex task, and put that rebase in your environment’s setup script (which runs with internet) rather than asking the agent to do it (the agent phase has internet Off by default, as of June 2026). Then add an AGENTS.md rule that says “if you hit a conflict, stop and report — never pick a side, never commit markers,” and back it with a pre-commit hook. Codex never sees a conflict, so it can’t guess wrong.
Why this works: Codex is not a merge-conflict expert. The model can read both sides of a conflict, but without the semantic context of why each side exists, it guesses. The reliable strategy is to keep conflicts away from the agent entirely.
One thing to know up front: as of June 2026, Codex Cloud has no built-in “conflict detected” indicator or “fix conflict” button in the PR panel — it is an open feature request (openai/codex#23016, filed May 2026). When a GitHub PR shows This branch has conflicts that must be resolved, you find out by opening the PR on GitHub, not from Codex’s UI. So don’t wait for the agent to flag it — prevent the conflict instead.
Which bucket are you in?
| Symptom | Likely cause | Jump to |
|---|---|---|
Task stops with merge conflict in <file> | Branch is stale; agent ran on an out-of-date tree | Step 1, Step 2 |
PR has literal <<<<<<< / ======= / >>>>>>> lines | Codex committed the markers as plain text | Step 3, Step 4 |
PR silently drops a feature that recently landed on main | Agent took ours/theirs wholesale | Step 3 |
| History is a tangle of merge commits | Agent ran git merge mid-task, repeatedly | Step 6 |
| Same conflict reappears every rebase | No recorded-resolution cache | Step 7 |
Common causes
1. Branch is days behind the base branch, conflicts inevitable
You started a Codex task on a feature/x branch cut last Tuesday. main moved 40 commits since. Anything Codex touches is going to conflict. Codex clones the repo and checks out the branch you selected for the task; it does not automatically rebase that branch onto the base branch first.
How to spot it: git log --oneline origin/main..HEAD shows few commits; git log --oneline HEAD..origin/main shows many. The branch is far behind.
2. The branch was never rebased before the task started
Your setup script does npm install but not git rebase origin/main. So the agent starts work on a stale tree, and conflicts surface only when it tries to apply_patch.
How to spot it: Setup logs do not include any rebase / pull. The first conflict appears at the apply_patch step, not before.
3. Codex committed the conflict markers themselves
The model saw <<<<<<< HEAD ... ======= ... >>>>>>> main, did not recognize them as control markers, and treated them as plain text. The PR now has real <<<<<<< lines.
How to spot it: git diff origin/main..HEAD | grep -E '^\+(<<<<<<<|=======|>>>>>>>)' returns matches. The build will also fail.
4. Agent picked one side wholesale
When asked to resolve, Codex took ours or theirs for every conflict without reading. It picked the side that produced the smaller diff or fewer compile errors, not the correct one.
How to spot it: The PR drops a feature that landed on main recently, or drops the work the branch was supposed to add. Compare with git log.
5. Merge instead of rebase, then conflicting merges of merges
Codex ran git merge origin/main, hit a conflict, fixed it, then later ran git merge origin/main again because of a new commit on main. History becomes a nest of merge commits, each with its own conflicts.
How to spot it: git log --oneline --graph shows many merge commits. History is hard to follow.
Shortest path to fix
Step 1: Rebase before you launch the task
Make it your own habit, or wire it into the environment:
git fetch origin
git rebase origin/main
# if conflicts appear, resolve them in your editor, never inside Codex
git push --force-with-lease
# now launch the Codex taskA clean rebase before the agent runs eliminates the large majority of mid-task conflicts.
Step 2: Rebase in the setup script, not in the agent
Codex Cloud runs two scripts around your task: a setup script that runs once on container creation with internet access, and an optional maintenance script that runs when a cached container is resumed (it exists precisely to bring a stale cached checkout up to date). The two phases run in separate Bash sessions, so environment variables you export in setup do not carry into the agent phase. The agent phase itself has internet Off by default as of June 2026 (the per-environment toggle in the Codex Cloud environment settings is Off / On; even On defaults to a domain allowlist) — so you cannot rely on the agent running git fetch. Put the network-dependent rebase in setup or maintenance.
Cached containers live for up to 12 hours, and the cache auto-invalidates whenever you change the setup script, maintenance script, environment variables, or secrets (or when you click Reset cache on the environment page). That is why the maintenance script matters: a 6-hour-old cached checkout can be several commits behind main.
In your setup script (Environment settings, or .codex/setup.sh for the CLI):
#!/usr/bin/env bash
set -euo pipefail
# Refuse to start if the branch is too far behind the base branch
git fetch origin main --quiet
behind=$(git rev-list --count HEAD..origin/main)
if [ "$behind" -gt 50 ]; then
echo "ERROR: branch is $behind commits behind main. Rebase before launching Codex."
exit 1
fi
# Attempt a clean rebase. If it conflicts, abort and bail.
if ! git rebase origin/main; then
git rebase --abort
echo "ERROR: rebase produced conflicts. Resolve them manually before retrying."
exit 1
fi
npm ciNow the agent only ever runs on a clean tree, and conflicts surface to a human before the agent starts. If you use a cached container, mirror the git fetch + rebase in the maintenance script so resumed runs also pick up new commits on main.
Note: a non-zero
exitfrom the setup script fails the environment build, which is exactly what you want — better a failed setup than a PR full of conflict markers.
Step 3: AGENTS.md “stop on conflict” rule
Put this in your repo-root AGENTS.md. Codex builds an instruction chain in precedence order — global ~/.codex/AGENTS.md, then the git-root AGENTS.md, then any nested directory AGENTS.md, with files closer to the edited file winning — and follows operational rules like this one. (A sibling AGENTS.override.md at the same level takes precedence over the plain AGENTS.md, and the whole chain is capped at 32 KiB by default, so keep this rule near the top.)
## Merge conflict policy
If you encounter merge conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`),
or `git status` shows files in "both modified" state:
1. Stop immediately.
2. Do not edit the file to remove the markers.
3. Do not pick `ours` or `theirs` without explicit human instruction.
4. Run `git rebase --abort` or `git merge --abort` to restore a clean state.
5. Write a note in the PR description listing the conflicting files and
which commits introduced them.
6. Mark the task as blocked.
Never commit a file containing `<<<<<<<`, `=======`, or `>>>>>>>` lines.The agent now has a clear escape hatch instead of guessing.
Step 4: Pre-commit hook that blocks conflict markers
A model can ignore a prose rule; a hook is mechanical. Install it from the setup script so every cached container has it:
mkdir -p .git/hooks
cat > .git/hooks/pre-commit <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
if git diff --cached -U0 | grep -E '^(\+|-)?\s*(<<<<<<<|=======|>>>>>>>)\s' >/dev/null; then
echo "ERROR: commit contains merge conflict markers. Resolve before committing."
exit 1
fi
EOF
chmod +x .git/hooks/pre-commitEven if the agent ignores the AGENTS.md rule, the commit hook stops it. (Note: core.hooksPath overrides .git/hooks — if your repo sets a custom hooks path, write the hook there instead.)
Step 5: Manual rebase the night before a big agent run
For multi-step Codex plans (a sequence of 4–5 PRs), rebase the branch the evening before. Walking into a clean tree saves hours of conflict triage.
# Day before
git fetch origin
git checkout feature/x
git rebase origin/main
git push --force-with-lease
# Verify CI is green on the rebased branch, then queue the Codex run for the morningPair this with branch protection so --force-with-lease is the only force option allowed, and the agent can never blow away a teammate’s push mid-conflict.
Step 6: Prefer rebase over merge
In AGENTS.md:
When integrating with main, always use `git rebase origin/main`, never
`git merge origin/main`. Do not run rebase yourself — it runs in the
setup/maintenance script at task start. If main moves during your task,
do not re-merge; stop and report.Rebase keeps history linear. A merge inside a long task produces conflicts of conflicts.
Step 7: Turn on git rerere for repeat conflicts
If the same conflict keeps reappearing every time you rebase a long-lived branch, enable rerere (reuse recorded resolution). Git records how you resolve a conflict once and replays that resolution automatically the next time the identical conflict shows up:
git config --global rerere.enabled trueThis is for you, resolving conflicts in your own editor — not for the agent. It removes the repetitive toil before you hand the clean branch back to Codex.
How to confirm it’s fixed
Run these on the branch before (and after) the Codex run:
# 1. No conflict markers anywhere in tracked files
git grep -nE '^(<<<<<<<|=======|>>>>>>>)' -- ':!*.md' || echo "clean"
# 2. Branch is not behind the base branch
git rev-list --count HEAD..origin/main # should be 0 after rebase
# 3. No "both modified" files
git diff --name-only --diff-filter=U # should print nothing
# 4. Build/tests pass
npm run build && npm testIf all four pass, the agent walked into a clean tree and the PR is conflict-free.
FAQ
Why won’t Codex just fix the merge conflict when I ask it to?
Two reasons. First, resolving a conflict correctly needs to know why each side exists, which is context the model often lacks — so it guesses, picks a side wholesale, or leaves markers in. Second, in Codex Cloud the agent phase is offline by default (as of June 2026), so an agent that tries to git fetch the latest main to understand the other side simply can’t reach the network. Rebasing in the setup script, where internet is available, sidesteps both problems.
Does Codex have a button to resolve PR conflicts automatically?
Not as of June 2026. Codex Cloud’s PR panel shows no “conflict detected” indicator and no “fix conflict” button — this is tracked as an open enhancement request, openai/codex#23016. You confirm conflicts by opening the PR on GitHub (the This branch has conflicts that must be resolved banner). Prevent conflicts with a pre-launch rebase instead of relying on the agent to detect them.
Where exactly should the rebase live — setup script or maintenance script?
Setup script for a fresh container; maintenance script for a resumed cached container. The maintenance script exists to update a checkout that was cached on an older commit, so mirroring the git fetch + git rebase origin/main there keeps resumed runs current. Both run with internet access, unlike the agent phase.
The agent committed <<<<<<< markers and the build broke. How do I recover?
On the branch, run git rebase --abort or git merge --abort if a rebase/merge is still in progress. If the markers were already committed, find them with git grep -nE '^(<<<<<<<|=======|>>>>>>>)', fix each file by hand, and amend or add a cleanup commit. GitHub’s own Resolve conflicts button on the PR can help for simple cases, but it is greyed out once a conflict is too complex (binary files, or conflicts that touch more than a handful of lines), so the command line is the reliable path. Then install the Step 4 pre-commit hook so it can’t happen again.
Will force-with-lease overwrite a teammate’s work?
No — that’s the point. git push --force-with-lease refuses to push if the remote branch moved since you last fetched, so it won’t clobber a teammate’s commit. Plain git push --force will. Add branch protection so only --force-with-lease is permitted.
Prevention
- Rebase branches before launching Codex; in the setup script, bail if the branch is too far behind the base branch.
- Put the network-dependent rebase in the setup or maintenance script (internet on), never in the agent phase (offline by default).
- AGENTS.md “stop on conflict, never commit markers, never pick sides” rule, scoped at the repo root.
- Pre-commit hook blocks any commit containing
<<<<<<</=======/>>>>>>>. - Prefer rebase over merge; one rebase point at task start, never mid-task.
- Enable
git rerereso you resolve recurring conflicts once. - Branch protection plus
--force-with-leaseso the agent cannot overwrite teammate work.