Codex App Troubleshooting: Fix Worktrees, Conflicts & Slow Runs

Hey fellow parallel-task runners—if you've been stress-testing Codex app with real multi-agent workflows, you've probably hit the same friction points I did.

I'm Hanks. I've spent three years running automation experiments inside actual workflows, not demos. When OpenAI dropped the Codex app for macOS in February 2026, I immediately threw it into my daily coding grind—multiple agents, overlapping file edits, background automations. Within 48 hours, I'd broken it in four predictable ways.

Here's the core question I kept asking: Can this app survive 10+ parallel worktrees without turning into merge soup?

This isn't a feature tour. It's field notes from fixing the breakage patterns that show up when you actually run Codex hard: worktree bloat, permission fatigue, merge chaos, and sluggish performance.

First-Aid Checklist (Before Deep Debugging)

When Codex starts acting weird, I run this 60-second diagnostic before diving into complex fixes.

Quick reality checks:

1. Check approval queue — Open the app, look for the bell icon. Codex might be waiting for permission you didn't see.
2. Terminal sanity test — Hit Cmd+J, run git status. If the terminal's frozen or showing the wrong branch, you're in the wrong context.
3. Filter confusion — Click the filter icon next to "Threads." I've spent 10 minutes "debugging" missing threads that were just filtered out.
4. Restart the obvious — Close terminal panel (Cmd+J), reopen it. Run pwd to confirm you're where you think you are.

If those don't fix it, keep reading.

Automations Created Too Many Worktrees (Cleanup Strategy)

This was my first real collision. I set up three automations to monitor CI failures, check for outdated dependencies, and flag security issues. After a week, I had 47 worktrees sitting in $CODEX_HOME/worktrees.

The problem: According to OpenAI's troubleshooting docs, frequent automations create worktrees faster than you delete them. Each automation run gets its own isolated workspace—which is great for parallel work, terrible for disk space.

The fix pattern I landed on:

When to Archive vs. Delete Worktrees

I archive when I might reference the diff later (like "how did I solve this before?"). I delete when the thread was exploratory or the fix already merged.

Cleanup workflow:

# List all worktrees
git worktree list
# Remove specific worktree (do this from your main repo)
git worktree remove path/to/worktree
# Prune orphaned worktree references
git worktree prune

In the Codex app: Archive the thread first (right-click → Archive). Then delete the worktree using the terminal or the app's worktree manager. Don't skip the archive step—once you delete the worktree, the diff is gone.

The Codex app features page notes you can promote worktrees to permanent homes using "Add to sidebar," but only do this if you're actively iterating on that branch. Otherwise, you're just hoarding directories.

Merge Conflicts & Overlapping Edits (Prevention + Recovery)

This is where most multi-agent workflows blow up. I ran into it on day two: three agents editing authentication logic simultaneously. Two PRs merged clean, the third showed conflicts in four files.

Root cause: When multiple agents modify the same file without syncing, Git requires manual conflict resolution before merging. Codex doesn't auto-resolve conflicts—you handle them.

Prevention Strategy

What worked for me:

1. Task isolation — Assign agents to different modules/files when possible. One agent handles auth, another handles API routes, another updates docs.
2. Sequential merging — Merge PR #1 before starting PR #2 if they touch overlapping areas. Sounds obvious, but I kept trying to parallelize everything.
3. Worktree-per-feature — Base each worktree on the latest main branch, not on each other.
4. Sync before new threads — Run git pull origin main in your local checkout before starting new worktree threads.

Reality check from OpenAI's community forum: Users running 10+ tasks in parallel report frequent conflicts. The consensus: Codex won't auto-fix merge conflicts for you. You resolve them manually or rerun the task.

Recovery Workflow

When conflicts appear:

1. In GitHub PR: Click "Resolve conflicts" button (top right of PR page).
2. In local editor: Use VS Code or your IDE's merge tool. GitLens extension makes this visual.
3. Manual resolution:

# Check conflict status
git status
# Edit conflicted files (look for <<<<<<< markers)
# Choose which changes to keep
# Mark as resolved
git add <conflicted-file>
# Complete the merge
git commit

Pro tip: If the conflict is messy and you trust one version completely, you can take "ours" or "theirs" entirely:

# Keep your version
git checkout --ours path/to/file
# Or keep their version
git checkout --theirs path/to/file
git add path/to/file

I learned this the hard way: don't try to fix conflicts by asking Codex to "resolve this for me." It'll generate code that might compile but won't understand the business logic you're protecting.

Permissions/Sandbox Gotchas (What to Allow, What to Refuse)

The permission system drove me nuts on day one. I'd paste an error log, Codex would ask, "What do you want to do with this?" Then constant approval prompts for pnpm install, file writes, directory reads.

The pattern: macOS requires explicit approval for sensitive directories (Desktop, Downloads, Music, home directory). Codex's troubleshooting guide confirms this is system-level, not a bug.

What to Allow

Always approve:

• Project directory access — Obviously, or Codex can't read your code.
• Git operations — Commit, push, branch creation. These are core workflow.
• Package manager commands — npm install, pnpm install, yarn add. You need dependencies.
• Build/test commands — npm run build, pytest, cargo test. Can't verify fixes without running them.

Conditionally approve:

• Home directory reads — Only if your config files live there (.bashrc, .zshrc, .gitconfig).
• Downloads/Desktop access — Rarely needed. Only approve if you're explicitly working with files there.

Refuse:

• Unrelated directory scans — If Codex asks to read /Applications or system folders, something's wrong with your task scope.
• File deletions outside project — Major red flag.

Permission Fatigue Fixes

Set up local environments: Create a .codex/local-env.yaml file in your project root. This tells worktrees to run setup scripts automatically:

# .codex/local-env.yaml
name: "My Project Setup"
setup:
  - npm install
  - cp .env.example .env

Now worktrees inherit your environment without re-prompting for npm install every time.

Use "Always allow this session": When approving commands, check "Always allow" if it's something you'll run repeatedly. But only for trusted operations in your project directory.

GitHub Issue #10464 reports confusion about permission changes between versions. Bottom line: full access mode still requires approval for destructive ops (file deletion, system commands). That's a feature, not a bug.

Performance Triage: Why Runs Feel Slow

After a week, I noticed some threads taking 3x longer than expected. Not timeouts—just sluggish execution. Here's what I found:

Common Slowness Causes

Actual Speedup Tactics

1. Scope reduction: Instead of "refactor the entire auth system," try "extract login logic into separate function." Smaller tasks = faster execution.

2. Pre-compute heavy operations: Run npm install or bundle install in your local checkout before creating worktrees. Worktrees will inherit lockfiles but won't re-download everything if dependencies are cached.

3. Use local environment scripts: According to the worktrees documentation, setup scripts run once per worktree creation. If your script is slow (Docker builds, large downloads), optimize it or move it outside Codex's scope.

4. Close unused threads: The app manages resources across active threads. I saw a noticeable speedup when I archived old threads instead of leaving 20+ open.

5. Restart the app: If multiple threads are stuck, wait until active work completes, then restart. The January 2026 changelog includes multiple UX fixes for sluggish terminals and stuck approval flows.

Real talk: Sometimes Codex is slow because the task is genuinely complex. I've found that tasks involving cross-file refactoring or dependency graph analysis take longer than simple CRUD generation. That's model reasoning time, not a performance bug.

When Codex Is Actually Broken

Signs you're hitting real bugs:

• Terminal commands return nothing (not errors, just silence)
• Diff pane shows blank screen on valid changes
• Worktree creation fails with cryptic Git errors
• App freezes during thread creation

First response: Check the Codex changelog for recent bug fixes. If you're not on the latest version, update. The January 16, 2026 release fixed terminal paste handling, git apply path parsing, and approval flow glitches.

If that doesn't help: File a GitHub issue at openai/codex with your version number, platform, and repro steps.

The Pattern I Settled On

After two weeks of breaking and fixing Codex workflows, here's the stable structure:

• One agent per worktree, one worktree per feature
• Merge in sequence, not parallel (unless features are completely isolated)
• Archive aggressively (weekly cleanup of old automation runs)
• Approve setup once (local env config), then trust the pattern
• Simplify prompts when stuck (Codex gets lost in vague tasks)

The tool works when you treat it like a distributed dev team: clear assignments, isolated workspaces, deliberate merging, regular cleanup.

At Macaron, we built our workflow system to handle exactly this friction—moving from conversation to structured execution without the worktree management overhead or constant approval prompts. If you're spending more time managing Git isolation than validating results, test it with your real tasks (free tier available) and judge whether it fits your flow.