Choose code and context

Choose a workspace’s code and conversation independently. For example, use clean code from main while keeping the findings from an investigation.

Run coco create <name> -i to choose these settings in a walkthrough. The examples below show the equivalent direct flags.

Choose the code

coco create fix/login --base main

--base accepts a Git revision and defaults to your current HEAD. To start from another workspace’s committed code:

coco create review/login --base-workspace fix/login

Local changes stay in the source checkout unless you explicitly carry them. CoCo warns when tracked or ordinary untracked changes were left behind.

Reuse a conversation

New workspaces start with a fresh conversation by default. Use --context (-c) to copy the history of an existing workspace:

coco create review/login --base main --context investigate/login

When you are already inside a CoCo workspace, . selects that workspace’s conversation:

coco create review/login -c .

This still starts the code from your current HEAD; only the conversation is copied. The walkthrough offers the current workspace by name when it can be used as a context source.

You can supply an existing Codex thread ID instead:

coco create review/login --base main --context <codex-thread-id>

CoCo copies the conversation during creation, through its latest finished turn. The source can keep working: its running turn and any later work stay out of the copy. You can open or send to the new workspace independently.

The source needs at least one finished turn. If it has just started, let its first turn finish before copying it.

To reuse both the committed code and conversation of a workspace:

coco create review/login --base-workspace fix/login --context fix/login

Shorten copied context

Add --compact-context (-C) to have Codex shorten the copied conversation before accepting your first message:

coco create review/login -Cc investigate/login

The source conversation stays unchanged.

Choose a branch

The default branch is coco/<workspace-name>. Choose a different new branch, an existing branch, or a detached checkout:

coco create fix/login --branch feature/login
coco create review/login --checkout existing-login-branch
coco create investigate/login --detached

An existing branch must be available locally and not checked out elsewhere. --checkout selects the branch’s code directly, so it cannot be combined with a base option.

Detached work has no branch name. Before closing it, retain any new commits on a Git branch or tag so you can reopen them.

Bring local changes

Use --dirty (-d) to copy staged edits, unstaged edits, and ordinary untracked files from your checkout:

coco create fix/login -d

The source remains unchanged. Carrying changes requires the selected base to match the source checkout’s current commit.

-D means detached and can be combined with -d:

coco create investigate/login -dD

For tracked changes only, use --carry-changes. Ordinary untracked files then block the copy; add --carry-untracked to include them.

Include ignored setup files

Use a .worktreeinclude file at the repository root for ignored files you need in new checkouts. It accepts Git ignore-style patterns and selects only files Git already ignores. For example:

.worktreeinclude

.env.local

Review the selection carefully: these files are copied into new workspaces and may contain credentials. An ignored root AGENTS.override.md is included automatically. Symlinks are skipped and existing destination files are preserved.

See the create reference for name rules and context disambiguation, or choose a model and profile.