Can Codex CLI create a branch automatically?

Codex CLI can run git commands if you ask it to, including creating a branch. However, it is safer to create the branch yourself before starting the session so the scope is clear from the beginning.

Should I run Codex CLI on main or always on a branch?

For any change that modifies files, use a branch. Running on main means any mistake goes directly to your primary history. A branch costs you one git checkout -b command and gives you a clean recovery path.

How do I handle a Codex CLI session that spans multiple branches?

Do not span a single task across branches. Complete the task on one branch, merge it, then start a new branch for the next task. Mixing branches mid-task makes the history hard to follow and conflicts harder to resolve.

What if two tasks depend on each other and I need to work on both at once?

Create a shared base branch for both tasks, then branch off it for each. When the first task is done, merge it to the base branch and rebase the second task's branch onto it. Keep each branch focused on one task.

Codex CLI Branches: Keep Work Scoped

Codex CLI works on whatever git branch is checked out. Using branches to scope each task to its own line of work keeps agent changes isolated, makes review easier, and gives you a clean recovery path if something goes wrong.

September 16, 2026Updated October 21, 20264 min read

Codex CLI operates on whatever branch you have checked out when you start the session. It reads files, creates or modifies them, and runs commands in that working tree. Using a dedicated branch for each task or experiment means the agent's changes stay isolated from other work until you review and merge them.

A branch gives you a recovery path and a clear scope. When the session ends, the branch holds exactly what the agent did. Tools like fenbs track which task belongs to which branch, record the implementation decisions, and carry the remaining work forward so the next session starts in the right place.

How Codex CLI uses the current branch

Codex CLI does not manage branches for you. It acts on whatever state the repository is in when you run it. If you run it on main, changes go directly onto main. If you run it on feature/add-validator, changes go there.

This makes branch discipline your responsibility, not the tool's. The good news is that the decision itself is simple: before starting a Codex CLI session for any task that will change files, create a branch. The branch scope is the task scope.

Keeping work isolated with branches

Before starting a session, check your current branch with git status or git branch. Make sure it is the branch you intend to work on.
Create a branch per task: git checkout -b task/validate-user-input. Use a short name that matches the task so branches are easy to identify later.
Give Codex CLI a clear, bounded instruction for the task. The narrower the task, the cleaner the branch: one branch, one purpose.
Commit at milestones during the session. Each commit is a checkpoint. If the agent takes an unexpected direction after a commit, you can reset to the last good state.
When the task is done, review the branch diff before merging: git diff main. Check that the changes are confined to the task and nothing unexpected was touched.

Checks before a handoff or merge

Before merging a Codex CLI branch or handing it to a reviewer, run the same checks you would for any code change: tests pass, the linter is clean (if you use one), and the diff shows only the expected files.

Also check that the branch is not behind the target. If other work merged to main while your agent was working, rebase or merge main into your branch and resolve any conflicts before the handoff. A reviewer who sees conflicts has to decide between two changes without the context behind either one.

Run tests: npm test, pytest, or whatever your project uses.
Check the diff for unexpected files: git diff main --name-only.
Update from the target branch: git fetch origin && git rebase origin/main.
Write a short summary of what changed and what was verified. This is the handoff note for the reviewer, not just the commit message.

How fenbs helps

Track branch tasks and decisions outside the session

Record each branch's task in fenbs: what it is for, the implementation decisions made, and what remains. The next session — on the same branch or a follow-up one — reads the context and continues from the confirmed state. Connect Codex CLI at /integrations.

Create a free account

Free for one person · No credit card · Works with Claude, ChatGPT, Cursor and more

When a branch experiment does not work out

If a Codex CLI session on a branch produces an approach that is wrong or too complex, the branch contains the evidence. Before discarding it, record why the approach did not work. That record prevents the next attempt from repeating the same path.

Then discard the branch cleanly: git branch -D task/bad-attempt. Do not merge a failed experiment. Start a new branch from main with a clearer instruction and the lesson from the first attempt included in the prompt.

Naming branches and writing useful task descriptions

A good branch name makes it easy to trace back to the original task. Use a consistent format: task/short-description or fix/issue-reference. The description should be specific enough that you know what is on the branch without checking it out first.

Before starting a Codex CLI session, write a clear task description in one or two sentences. Include what the code should do when the task is done, what it should not do, and any files or modules that are off-limits for this branch. A clear boundary prevents the agent from making sensible-looking changes that are outside the task scope.

After the session, add a short summary to the branch's commit message or a note: what was done, what was not done, and what a reviewer should check first. A reviewer who understands the intent of a branch can spot scope creep or an unexpected side effect in the diff that they might otherwise miss. That summary also helps you, two weeks later, understand why the branch exists if it was not merged immediately.

How to do this with fenbs

Create a free account and add a project for the codebase.
Add a task for each piece of work. Name the branch after the task so you can find them together.
Record the implementation decision for each branch in Decisions and rules: what approach was chosen and why alternatives were rejected.
When a Codex CLI session ends, save progress in the task: what the branch contains, what was checked, and the next step.
Connect Codex CLI to fenbs at /integrations. At the start of each session, ask it to read the task context before touching any file.

See codex cli best practices for a broader guide to productive Codex CLI sessions, and codex app vs cli vs ide extension for when to use the CLI versus other Codex interfaces.