gh issue develop: Checkout a GitHub Issue Worktree

To use gh issue develop checkout worktree, you need GitHub CLI 2.99.0 or later, which introduced worktree support for gh issue develop. From your repository, run gh issue develop 123 --checkout --worktree ../repo-issue-123. GitHub CLI creates a branch linked to issue 123 and checks it out in a separate worktree at the path you choose. Give your coding agent that worktree as its working directory so its file changes stay separate from your current checkout.

gh issue develop 123 --checkout --worktree ../repo-issue-123
cd ../repo-issue-123

All issue numbers, branch names, paths, task wording, and PR text below are examples; replace them for your repository. Choose an unused directory and the issue you intend to assign. Git worktrees provide multiple working trees attached to one repository, each with its own checkout and index. For a broader explanation of that arrangement, see Git Worktrees: Why AI Agents Need Them.

Read the issue and check the starting point

Before creating the branch, use gh issue view to read the issue body and comments. The description may contain acceptance criteria, while comments may narrow the task or identify work already in progress. Ask the agent to work from the issue’s current requirements rather than a title alone.

gh issue view 123 --comments
gh issue develop --list 123

The second command lists branches already linked to the issue. If one exists, decide whether the agent should continue there before creating another. Multiple branches can be useful for alternative approaches, but distinct names and worktree paths make it easier to tell their changes apart.

Check that GitHub CLI is using the intended account with gh auth status. In a repository with several remotes or accounts, also confirm which issue and repository you mean. For --checkout, your local Git remotes must include one matching the repository where the branch is created. Verify or configure that remote before a cross-repository checkout: --repo OWNER/REPO selects the issue repository and --branch-repo OWNER/REPO selects the branch destination, but neither configures a local remote. Both gh issue view and gh issue develop accept --repo OWNER/REPO; an issue URL can identify the issue directly.

Create a named branch and separate checkout

For a predictable branch name and starting branch, supply --name and --base:

gh issue develop 123 \
  --name issue-123-fix-cache \
  --base main \
  --checkout \
  --worktree ../repo-issue-123

--name chooses the branch name. --base main starts it from the remote main branch and configures that branch as the base for a later gh pr create. --checkout --worktree places the branch in the named worktree instead of switching your current checkout. If the issue belongs to another repository, add --repo OWNER/REPO; if the development branch belongs in a different repository, --branch-repo OWNER/REPO selects that destination. Confirm the matching local remote first.

Pick a path outside the current checkout, such as a sibling directory. This makes it clear which files belong to the agent’s workspace and avoids mistaking a worktree for an ordinary subdirectory of your project. Use a branch name that includes the issue number when several agents may work on nearby tasks. The number is an organizational convention; gh issue develop creates the GitHub issue link.

Afterward, run git worktree list from either checkout to see the registered paths and their branches. In the new directory, git status --short --branch shows the current branch and working tree changes:

git worktree list
cd ../repo-issue-123
git status --short --branch

Confirm the branch and directory before launching the agent. The worktree separates checked-out files, but it does not decide what the agent is allowed to edit. Set the task boundary in the prompt: identify the issue, name the relevant area of the codebase, ask for appropriate tests, and require a concise account of changed files and remaining uncertainty. If multiple agents are tackling separate issues, assign each a different branch and worktree path.

Give the agent an issue-specific task

An effective handoff can be short and concrete. After opening the agent in ../repo-issue-123, give it a task like this:

Work on GitHub issue #123 in this worktree. Read the issue body and comments
before changing code. Fix only the cache invalidation described there.
Add or update the relevant tests, run the project's documented checks,
and report the changed files, test results, and any unresolved questions.
Do not create or merge a pull request.

The prompt ties the work to the issue while leaving the agent room to inspect the code. Asking for test results means asking it to report what it ran; you still need to review its claims and the resulting diff. Keep project setup, credentials, and test commands in the instructions you normally use for that repository rather than assuming a new worktree contains everything needed to run the project.

If you want two possible fixes for the same issue, create separate linked branches with separate worktree paths and give each agent the same acceptance criteria. Compare the resulting changes before choosing one. For guidance on handling the outputs of parallel branches, see How to Merge Work From Parallel AI Agents.

Continue an existing linked branch

If gh issue develop --list 123 shows the branch you want, create a local worktree for that branch instead of creating another issue branch. First, git fetch origin updates remote-tracking references. If the branch already exists locally and is not checked out in another worktree, add it directly:

git fetch origin
git worktree add ../repo-issue-123 issue-123-fix-cache

If it exists only as origin/issue-123-fix-cache, create a local branch that tracks it:

git fetch origin
git worktree add --track -b issue-123-fix-cache \
  ../repo-issue-123 origin/issue-123-fix-cache

Use the actual remote and branch reported for your repository. -b creates a local branch, so it will fail if that local name already exists. Git also normally refuses to check out a branch that is already checked out in another worktree. Check git worktree list to find that checkout; continue there or choose a genuinely separate branch for a second agent. Avoid forcing the same branch into two worktrees merely to get around the refusal.

Review the change and open a pull request

When the agent finishes, inspect the worktree before creating a PR. git status identifies modified and untracked files; git diff shows unstaged changes, while git diff --cached shows staged changes. Open and inspect each untracked file listed by status, since those diff commands do not show its contents before it is staged. Review the final commit diff as well if the agent committed its work. Confirm that the changed files match the issue, that unrelated edits are removed, and that the tests reported by the agent are appropriate for the change.

cd ../repo-issue-123
git status --short --branch
git diff
git diff --cached

Stage only reviewed files with git add and commit the intended changes before opening the PR:

git add path/to/reviewed-file
git diff --cached
git commit -m "Fix cache invalidation for issue 123"

gh pr create --draft opens a draft pull request; it does not commit working-tree changes. If the branch is not fully pushed, GitHub CLI may prompt you to choose where to push it. Provide a title and body so reviewers see the issue, the change, and the verification performed:

gh pr create --draft \
  --title "Fix cache invalidation for issue 123" \
  --body "Fixes #123

Summary: Update the cache invalidation path.
Tests: Add the commands and results actually obtained."

GitHub can link a PR to an issue and close the issue on merge with Fixes #123, but closing keywords in a PR description are interpreted only when the PR targets the repository’s default branch. If you used --base to target another branch, check the PR’s issue link and closing behavior rather than assuming the keyword will close the issue. Creating an issue-linked branch and closing the issue are separate steps.

Handle creation and cleanup problems

A linked branch requires the right repository access. GitHub’s issue branch feature requires write permission and remains in public preview, so availability and behavior may change. If branch creation fails, confirm the account, issue repository, branch destination, and permission to create branches there. For checkout failures, also confirm that a local remote matches the branch destination repository.

If Git says the branch is already checked out, inspect git worktree list. If the desired path is still registered after a directory was moved or deleted outside Git, use git worktree repair or git worktree prune as appropriate; inspect the worktree list before pruning. Do not delete a directory just to make a worktree error disappear.

After the PR is merged and you no longer need the checkout, return to the original checkout before removing the linked worktree. From there, remove the worktree, then delete its local branch if you no longer need it:

cd ../repo
git worktree remove ../repo-issue-123
git branch -d issue-123-fix-cache

Git normally requires a clean worktree for removal, so inspect and preserve any changes first. git branch -d deletes a fully merged local branch. Removing the worktree and deleting its branch are separate operations. See Clean Up Stale AI Agent Git Worktrees Safely for a fuller cleanup process.

Where Parallel Code fits

Parallel Code is our free, open-source (MIT) desktop app for macOS and Linux. It runs several AI coding agents in parallel, each isolated in its own git worktree, and provides a diff-first review surface. You can bring your own editor and agent when an issue needs a separate workspace or when you want to compare approaches.

Frequently asked questions

Does --checkout alone create a separate worktree?

No. --checkout checks out the created branch, while --worktree PATH specifies where to place the separate checkout. Use both flags together when you want the issue branch in its own worktree.

Can I start from a branch other than the default branch?

Yes. Pass --base BRANCH to gh issue develop to create the issue branch from that remote branch. Check the eventual PR base as well, especially if your team expects the change to merge somewhere other than the repository’s default branch.

What if the issue already has a linked branch?

Run gh issue develop --list ISSUE first. If you intend to continue that branch, fetch it and add a worktree for the existing branch; create a new linked branch only if you need a separate line of work.

Does deleting the worktree close the GitHub issue?

No. Worktree removal cleans up a local checkout. Issue closure depends on the issue or PR workflow, such as merging a PR that targets the default branch and uses a supported closing keyword.