MemoryLake
Back to all articles
TutorialNovember 13, 2026·12 min read

What Is a Codex Worktree? What a New Worktree Starts With, Why Archiving a Chat Deletes It, and How to Restore the Snapshot Codex Saves (2026)

You start a Codex chat, pick Worktree under the composer instead of Local, and let it run in the background while you keep working in your own checkout. It goes well. A few weeks later you open an older chat and the files it worked on aren't on disk anymore. Codex offers to restore something. What happened?

Two things in OpenAI's documentation explain it. Worktrees are designed to be temporary: "By default, chats use a Codex-managed worktree. These are meant to feel lightweight and disposable." And they're cleaned up on a schedule you may not have noticed: "By default, Codex keeps your most recent 15 Codex-managed worktrees."

The work isn't necessarily gone. "Before deleting a Codex-managed worktree, Codex saves a snapshot of the work on it."

This guide covers what a Codex worktree is, how to start a chat in one, what a new worktree starts with and what it leaves out, how Handoff moves a chat between Local and a worktree, when Codex deletes worktrees, how to restore one, where worktrees live, and what a worktree doesn't hold.

What a Codex worktree is

OpenAI's documentation opens with the purpose: "Worktrees let Codex run multiple independent chats in the same project without interfering with each other."

Under the hood, a Codex worktree is a Git worktree. "Worktrees only work in projects that are part of a Git repository since they use Git worktrees under the hood." The documentation explains what that means: "Each worktree has its own copy of every file in your repo but they all share the same metadata (.git folder) about commits, branches, etc."

The ChatGPT desktop app uses three terms:

  • Local is your own checkout, the repository you created.
  • Worktree is a Git worktree the app created from your local checkout.
  • Handoff is the flow that moves a chat between Local and a worktree.

OpenAI suggests thinking of them as foreground and background: "You can think of Local as the foreground and Worktree as the background."

The repository and the worktree stay on the machine that holds the project. "Worktrees don't run locally on your phone." The ChatGPT mobile app can start, guide, approve, and review worktree chats, but it does that by controlling Codex on your connected computer.

How to start a chat in a worktree

The steps are short:

  1. In the new chat view, select Worktree under the composer. Optionally choose a local environment to run setup scripts.
  2. Below the composer, choose the Git branch to base the worktree on.
  3. Submit your prompt. Codex creates the worktree from that branch.
  4. When you're ready, keep working on the worktree or hand the chat off to Local.

The project has to be in a Git repository.

What a new worktree starts with

A worktree isn't an empty folder. OpenAI's documentation describes exactly what Codex puts in it.

The branch's latest commit. "The starting commit is the HEAD commit of the branch selected when you start your chat."

Your uncommitted changes, if you chose a branch that has them. "If you chose a branch with local changes, Codex applies the uncommitted changes to the worktree as well."

Every tracked file. "Local Codex-managed worktrees start from a Git checkout, so tracked files are already present."

No branch of its own. "The worktree isn't checked out as a branch." It's in a detached HEAD state, and the documentation gives the reason: "This lets Codex create several worktrees without polluting your branches."

Your local instruction override. Codex copies one ignored file automatically. "Codex automatically copies an ignored AGENTS.override.md into local managed worktrees, so you don't need to list it in .worktreeinclude." If you keep personal instructions for Codex in that file, they're present in the worktree too.

Whatever your setup script installs. If you chose a local environment, its setup script runs. OpenAI explains why that matters: "Since worktrees run in different directories than your local chats, your project might not be fully set up and might be missing dependencies or files that aren't checked into your repository." And: "Setup scripts run automatically when Codex creates a new worktree at the start of a new chat."

What a new worktree leaves out

The flip side of starting from a Git checkout is that anything Git ignores stays behind, unless you say otherwise.

Ignored files, by default. OpenAI's examples include .env files and a secrets file. To bring specific ones, add a .worktreeinclude file at the repository root and list the paths or patterns to copy. The documentation is precise about the limits: "Codex only copies ignored files that match .worktreeinclude; it doesn't copy other local files that Git doesn't track."

Tracked files in the include list. "Don't list tracked files." They're already there.

Symlinks and existing files. "Codex skips source symlinks and won't overwrite files that already exist in the new checkout."

Other kinds of worktrees. The include behavior has a scope: "This behavior applies to local ChatGPT desktop app managed worktrees, not remote worktrees or Git worktrees you create yourself from the command line."

Installed dependencies. Unless a setup script installs them, a fresh worktree may not have your node_modules or build output. That's what local environment setup scripts are for.

Moving a chat between Local and a worktree

Handoff moves a chat and its code in either direction. OpenAI's documentation says: "Handing off to or from Local moves your chat and code so you can continue in the other checkout."

Two details make Handoff predictable:

  • A chat keeps its worktree. "Each chat keeps the same associated worktree over time. If you hand the chat back to a worktree later, Codex returns it to that same background environment so you can pick up where you left off."
  • Ignored files don't travel. "Since Handoff uses Git operations, any files that are part of your .gitignore file won't move with the chat unless Codex copies them into a local managed worktree with .worktreeinclude."

We covered Handoff in detail, including what moves with a chat between your computer and a remote host, in our guide to what moves with your chat in Codex Handoff.

The branch rule that trips people up

Git has a rule Codex can't work around. The documentation puts it in bold: "Git only allows a branch to be checked out in one place at a time."

That shows up when you turn a worktree into a branch. If you select Create branch here on the worktree and then try to check out that branch in your local checkout, Git refuses with an error that the branch is already used by a worktree.

OpenAI's advice: "If you plan on checking out the branch locally, use Handoff to move the chat into Local instead of trying to keep the same branch checked out in both places at once."

When Codex deletes a worktree

Worktrees take space. "Worktrees can take up a lot of disk space. Each one has its own set of repository files, dependencies, build caches, etc." So the desktop app limits how many it keeps.

The default limit. "By default, Codex keeps your most recent 15 Codex-managed worktrees. You can change this limit or turn off automatic deletion in settings if you prefer to manage disk usage yourself."

When deletion happens. The documentation lists two triggers:

  • You archive the associated chat.
  • Codex needs to delete older worktrees to stay within your configured limit.

The first one is easy to overlook. Archiving a chat sounds like tidying up the sidebar, but for a chat with a Codex-managed worktree, it also deletes the worktree. Archiving in Codex has other effects too, which we covered in our guide to the Codex agent command center and what archive and delete do.

What's protected. Codex-managed worktrees aren't deleted automatically if a pinned chat is tied to them or if the chat is still in progress.

Older permanent worktrees. "Permanent worktrees created in earlier versions remain available and protected from automatic cleanup. You can no longer create permanent worktrees from the project menu."

How to restore a deleted worktree

Deleting a worktree doesn't delete the chat. OpenAI's FAQ says: "Chats can remain in your history even if the underlying worktree directory is deleted."

And the work is saved first: "Before deleting a Codex-managed worktree, Codex saves a snapshot of the work on it. If you open a chat after its worktree was deleted, you'll see the option to restore it."

So the recovery path is simple: open the chat and choose the restore option.

The documentation doesn't say how long snapshots are kept, or whether a snapshot includes ignored files copied through .worktreeinclude. If a worktree held something you can't recreate, such as a local secret or a generated file, keep your own copy rather than relying on the snapshot.

Where worktrees live

"Codex creates worktrees in $CODEX_HOME/worktrees." You can change the location. OpenAI's FAQ says to open Settings, then Worktrees, and change Worktree root.

That's useful if your home drive is small, or if you want worktrees on a faster disk. It's also worth knowing when you clean up disk space by hand. The protections for pinned and in-progress chats, and the snapshot step, are documented for Codex's own cleanup, not for folders you remove yourself.

Worktrees for scheduled tasks

Worktrees aren't only for chats you start yourself. "For Git repositories, scheduled tasks can run on dedicated background worktrees so they don't conflict with your ongoing work."

Projects outside Git work differently: "In non-version-controlled projects, scheduled tasks run directly in the project directory."

What a worktree doesn't hold

A worktree holds files. The chat attached to it holds the conversation. What neither is designed to hold is the reasoning that carries from one chat to the next: why this approach was chosen, which alternatives failed, and what the code is waiting on.

Worktrees are, by design, disposable. When one is deleted, the snapshot keeps the work on it. The decisions made along the way live in that chat's conversation, which is easy to lose track of once there are dozens of chats.

What people try first

Archiving old chats to clean up. For a chat with a Codex-managed worktree, archiving deletes the worktree.

Expecting .env files in a new worktree. Ignored files aren't copied unless they match .worktreeinclude.

Checking out the worktree's branch locally. Git allows a branch in one place at a time. Use Handoff instead.

Deleting the worktrees folder by hand. The snapshot step is documented for Codex's own cleanup, not for folders you remove yourself.

Assuming the chat is gone with the worktree. Chats can stay in your history, and you can restore the worktree from the chat.

The Fix: Use worktrees without losing work

Step 1: Set up what a new worktree needs

Add a local environment setup script for dependencies, and a .worktreeinclude file for the ignored files a worktree needs.

Step 2: Protect the chats you'll come back to

Pin chats whose worktrees you want to keep, or raise the limit in settings.

Step 3: Restore instead of redoing

If a worktree was deleted, open the chat and use the restore option before starting over.

Step 4: Write down the reasoning

Keep the decisions behind a worktree's changes, such as the approach and what you ruled out, outside the chat.

Setting this up in MemoryLake

A worktree is a good place for parallel work, and Codex is careful about saving it before cleanup. The decisions behind that work are what the next chat, in a new worktree or in Local, needs to pick up without re-asking.

MemoryLake is a memory layer for that kind of project context, such as decisions, constraints, and conventions, kept in one place you maintain and available to the assistants you connect, such as ChatGPT, Claude Code, and Codex.

You write the entries yourself, in your own words. Nothing is read out of, written to, or deleted from your worktrees, their snapshots, your Codex chats, your .worktreeinclude or AGENTS.override.md files, your Codex memories, or any vendor's store. Worktrees, Handoff, and cleanup work the way OpenAI describes them.

Step 1: Create an API key

Sign in and generate a key from the dashboard. Store it outside your repositories, like any other credential, and don't add it to .worktreeinclude.

The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent
The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent

Step 2: Upload your first memories

Start with what you wrote in Step 4 of the fix: the approach for each piece of work, the alternatives you tried, and the constraints that shaped it. One decision per entry.

The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory
The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory

Step 3: Connect your AI & agents

Connect Codex and any other assistants you use. A new chat in a fresh worktree, or a chat handed off to Local, can draw on the same decisions.

The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer
The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer

What this changes in practice

The first difference is that cleanup stops being a risk to your reasoning. A worktree can be archived and deleted, and the decisions behind it are still written down.

The second is faster starts for parallel chats. Each new worktree chat can draw on the project's settled decisions instead of rediscovering them.

The third is continuity across tools. Claude Code or another assistant working on the same repository can use the same entries.

Best practices for Codex worktrees

Use worktrees for background work. Keep Local for what you're actively testing.

Add a setup script. New worktrees may not have dependencies unless something installs them.

List ignored files in .worktreeinclude. Only matching ignored files are copied.

Pin what you'll revisit. Pinned chats keep their worktrees.

Archive deliberately. Archiving deletes a chat's Codex-managed worktree.

Restore before redoing. Codex saves a snapshot before it deletes a managed worktree.

Keep the why elsewhere. A worktree holds files, not reasons.

Conclusion

A Codex worktree is a Git worktree the ChatGPT desktop app creates so a chat can work in the background without touching your local checkout. It starts from the HEAD commit of the branch you chose, includes your uncommitted changes if that branch had them, has every tracked file, and copies only the ignored files you list in .worktreeinclude, plus AGENTS.override.md.

Codex keeps your most recent 15 managed worktrees by default and deletes a chat's worktree when you archive the chat. Pinned and in-progress chats are protected, and before deleting a managed worktree, Codex saves a snapshot you can restore from the chat. Keep the reasoning behind the work somewhere the next chat can read.

Frequently asked questions

What is a worktree in Codex?

A Git worktree that the ChatGPT desktop app creates from your local checkout so a Codex chat can work in parallel without interfering with your other chats.

Why did my Codex worktree disappear?

Codex deletes a managed worktree when you archive its chat or when it needs to stay within your limit, which is 15 by default.

Can I restore a deleted Codex worktree?

Yes. Codex saves a snapshot before deleting a managed worktree, and when you open the chat, you'll see the option to restore it.

Why aren't my .env files in the worktree?

Ignored files aren't copied unless they match a pattern in .worktreeinclude at the repository root.

Where does Codex store worktrees?

In $CODEX_HOME/worktrees by default. You can change the location under Settings, then Worktrees, then Worktree root.

Why can't I check out the worktree's branch locally?

Git allows a branch to be checked out in only one place at a time. Use Handoff to move the chat into Local instead.

Does archiving a Codex chat delete its worktree?

Yes. Archiving the associated chat is one of the triggers for deleting a Codex-managed worktree.