Codex Desktop App: Projects, Worktrees, Threads, and Cleanup
If Codex desktop app terminology feels fuzzy, this mental model is the one that stays consistent:
- A project is an entry in your sidebar tied to a local folder/workspace.
- A thread is a conversation inside that project.
- A Codex-managed worktree is a separate checkout Codex can use for thread work.
- A permanent worktree is a long-lived separate checkout that appears as its own project and is not auto-deleted.
What Worktree Mode Means in the App
In Codex app terms, Worktree mode means your thread runs in a different checkout than your main Local checkout for that repo.
That separation prevents common collisions:
- New files generated in one checkout do not appear in the other by accident.
- Dependency installs and build artifacts stay scoped to the checkout you are using.
- Branch and working-copy state in one checkout does not disrupt your active Local checkout.
This is why permanent worktrees are useful for longer efforts: they give you a stable, separate workspace without constant context switching.
When to Create a New Project vs Reuse One
Use this rule of thumb:
- Create a new project when you are switching to a different folder/repository, or when you want a separate long-lived permanent worktree from the same repo.
- Reuse an existing project when you are still in the same folder and just starting another task; create a new thread instead.
If your work will continue over many sessions in the same repo and you want hard isolation, create a permanent worktree project.
How to Create a Permanent Worktree Project
In the sidebar:
- Find the project.
- Open the three-dot (
...) menu. - Choose the permanent worktree option.
Codex creates a new project backed by a permanent worktree. You can run multiple threads from that project, and Codex does not auto-delete it.
Auto-Cleanup: When It Happens
Codex cleanup is lifecycle-based, not a fixed nightly schedule.
By default, Codex keeps your most recent 15 Codex-managed worktrees and can remove older ones to stay under that limit.
Codex-managed worktrees are eligible for automatic deletion when:
- The associated thread is archived, or
- Codex needs to evict older worktrees to respect the retention limit.
Codex tries to preserve important worktrees and avoids auto-deleting a managed worktree if:
- The conversation is pinned,
- The thread is still in progress, or
- The worktree is permanent.
Before a managed worktree is deleted, Codex stores a snapshot so restore is possible when reopening.
How to Configure Cleanup
In Codex desktop app:
- Open Settings (
Cmd+,). - Find worktree cleanup/retention controls.
- Change the managed-worktree retention limit, or disable automatic deletion if you prefer manual cleanup.
If you never want a checkout auto-deleted, use a permanent worktree.
Practical Cleanup Workflow
For old items:
- Archive stale threads.
- Remove no-longer-needed projects from the sidebar.
- Keep only active long-running efforts as permanent worktrees.
This keeps the sidebar and disk usage under control without losing active context.
Sources
This article is open source. Found an error? Have a different perspective? Open an issue or submit a PR — we welcome contributions from the community.