Codex CLI added experimental worktree support in version 0.154.0 (September 9, 2026): start a session with --worktree or run /worktree mid-session, and the agent gets its own isolated git checkout. For anyone running several client codebases, this stops one AI session from colliding with your main working directory — but cleanup is manual, and OpenAI still calls it experimental.
You're mid-feature on Client A's branch when Client B's Slack message lands: production is down, fix it now. You stash your changes, switch branches, and hope you remember where you left off.
OpenAI shipped a feature this month built for exactly this problem. It's called worktree support. Most people write about it like a general git trick. There's a second use for it that almost nobody mentions, and it's the one that matters if you juggle five client repos.
What Codex CLI worktrees actually are
Git worktrees aren't new. The underlying git command lets you check out more than one branch from the same repository at the same time, each in its own folder, without cloning the repo again or stashing anything (git-scm.com). Most developers have heard of it. Fewer use it, because typing git worktree add ../client-b-hotfix client-b/main every time is one more thing to remember mid-crisis.
Codex CLI, OpenAI's coding agent, folded that command into itself. As of version 0.154.0, shipped September 9, 2026, you can start a session with --worktree or drop /worktree into an active session, and Codex creates an isolated checkout for that session on its own (OpenAI Codex changelog). No manual folder juggling. The agent works in its own sandboxed copy of the repo while your main working directory sits untouched.
That release note is one line. What it changes for a freelancer running four client codebases at once is bigger than one line.
How to actually use it
The workflow is short enough to write down once and forget:
- Start (or fork) a Codex session with the flag:
codex --worktree - Or, inside a running session, type
/worktreeto spin one up mid-conversation - Codex checks out a fresh working tree, tied to the branch you tell it, in its own directory
- Your agent works there. Your terminal, your editor, your uncommitted changes on the main checkout stay exactly where you left them
- When the task is done, merge the worktree's branch like any other, then remove the worktree
Here's the part that matters more than the syntax: step 5 is manual. Codex creates the worktree. It does not clean it up.
Is Codex CLI worktree support ready for client work?
OpenAI's own changelog calls this "experimental." That's their word, not a hedge added here. It means the flag, its defaults, even the command name could change with no warning. Two more features shipped in the very next version, 0.155.0, eight days later: voice conversations and Touch ID checks for MCP requests. Both are also marked experimental (OpenAI Codex changelog). This team is still reshaping the CLI week to week. It is not a finished tool yet.
That's not a reason to skip it. It's a reason to use it the way you'd use any new tool on billable work: on your own low-stakes tasks first, not on the client deliverable due Friday.
Here's the second use nobody mentions in the release notes. Start ten sessions across a busy week and forget to clean up six. Now you have six stale checkouts of client repos sitting on disk. Each one is a full working copy. Each one is something you'd have to explain if a client ever asked what's on your machine.
A short table beats a paragraph here:
| Situation | What happens without cleanup |
|---|---|
| One client, one worktree | Barely noticeable |
| Five clients, worktree per hotfix | Disk fills slowly, unnoticed |
| Worktree left mid-task, laptop reimaged | Orphaned branch, no local trace |
Old worktree still holds client credentials in .env |
Sits on disk indefinitely |
git worktree list shows you every worktree attached to a repo. git worktree remove <path> clears one. Neither is Codex-specific — they're just git, and they're the two commands worth memorizing before you start using /worktree on real work.
DevAegis ships your code encrypted so it only runs while the invoice is current. See how it works
Codex worktrees vs. Cursor Projects: different fix, different problem
If you've read about Cursor's Projects feature on this blog, the comparison is worth making explicit, because the two look similar from a distance and solve different problems up close.
Cursor Projects hands a big task — a framework migration, a large refactor — to a coordinator agent that splits it across parallel subagents, all still working in one shared checkout. The problem it solves is task decomposition: one big job, broken into pieces an agent can chew through concurrently.
Codex worktrees solve isolation, not decomposition. You're not asking one task to split itself up. You're keeping two or more entirely separate tasks — often for two entirely separate clients — from touching the same files at the same time. If your problem is "this one migration is too big for one agent pass," look at Cursor's approach. If your problem is "I have three clients and one laptop," worktrees are the more direct fix.
What this means once the work ships
None of this changes what happens after you hand the build over. Parallel worktrees make it faster to get five client projects across the finish line in a week that used to take two. They do nothing about what happens if one of those five clients stops paying on delivery day — the isolation is on your machine, not in the contract.
That's a separate problem with a separate fix: code delivered to a client should stay conditional on payment until the invoice actually clears, the same way a SaaS subscription cuts off access the day a card fails. DevAegis encrypts the build you hand over and holds the key until payment is confirmed — a five-minute step after codex --worktree has already done its job, not a replacement for it. The full walkthrough is in how to protect your code as a freelancer or agency. If a client goes quiet after delivery instead, here's what you can still do.
Frequently asked questions
What is a Codex CLI worktree?
It's an isolated git checkout that OpenAI's Codex CLI creates automatically for a session, using --worktree at launch or /worktree inside a running session, so an AI agent can work on one branch while your main working directory stays on another.
Is Codex CLI worktree support stable enough for client deliverables? OpenAI labels it experimental as of version 0.154.0 (September 2026), meaning the command and its defaults can change without a deprecation window. Treat it as a habit to build on internal or low-stakes tasks first, not as a stable process to hand a client-facing deadline to right away.
Does Codex clean up worktrees automatically?
No. Codex creates the worktree; removing it is a manual step with standard git commands (git worktree list, git worktree remove). Left unmanaged across several clients, abandoned worktrees quietly consume disk space and can leave stale copies of client code and credentials sitting around.
How is this different from Cursor's Projects feature? Cursor Projects splits one large task across parallel subagents inside a shared checkout — it solves task decomposition. Codex worktrees isolate separate tasks into separate checkouts — it solves keeping unrelated work, often for different clients, from colliding on the same machine.
Do I need to already know git worktrees to use this?
No, but it helps to know the two commands that manage them (git worktree list and git worktree remove), since Codex handles creation but not cleanup.
One thing to do this week: if you're running more than one client codebase right now, run git worktree list in each and check what's still sitting there from an old session — before you add Codex's /worktree into the mix and make more of them.
Set up protection before the next handover
Faster delivery is only good news if it actually gets paid for. DevAegis encrypts the build before it leaves your machine and holds the decryption key until the invoice clears — check devaegis.com/pricing for plans, no card required to look.
Key takeaways
- Codex CLI's worktree support shipped September 9, 2026 in version 0.154.0 — start a session with --worktree, or type /worktree mid-session, to get an isolated git checkout for that task.
- It solves isolation, not decomposition: it keeps separate tasks, often for separate clients, from colliding on one machine, rather than splitting one big task into parallel pieces the way Cursor Projects does.
- OpenAI labels the feature experimental as of versions 0.154.0 and 0.155.0 (September 2026), so its flags and defaults can change without a deprecation notice.
- Codex creates worktrees but doesn't clean them up — abandoned worktrees from old sessions quietly consume disk space and can leave stale copies of client code sitting around.
- git worktree list and git worktree remove are the two standard git commands worth knowing before using /worktree on real client work.
- ChatGPT & Codex changelog — OpenAI
- git-worktree Documentation — Git
Frequently asked questions
Straight answers to what people ask about codex cli worktrees.
Stop handing over the leverage
Your code ships encrypted and runs only while you allow it. One toggle and their site shows a payment screen.
Protect Your Code
