Claude Code Worktree From a Pull Request

To open a Claude Code worktree from an existing pull request, run claude --worktree "#1234" from a checkout of the repository, replacing 1234 with the PR number. Interactive --worktree runs require workspace trust: if you have never launched Claude in that repository, first run claude there and accept the trust dialog. Claude Code then fetches the PR’s head commit from origin and creates a separate worktree at .claude/worktrees/pr-1234.

cd /path/to/repository
claude --worktree "#1234"

The path above is an example; use your repository’s path. Keep the # argument quoted so the shell passes it to Claude. You can also pass the PR’s GitHub URL, but Claude Code reads only its number from the URL and still fetches from the current repository’s origin. Check that origin points to the repository containing the PR before using either form.

If a PR worktree already exists, rerunning the command reopens it at its previous tip; do not assume it has moved to the PR’s latest revision. Compare the PR’s headRefOid from gh pr view with the worktree’s current commit from git rev-parse HEAD before reviewing or editing:

gh pr view 1234 --json headRefOid
git rev-parse HEAD

Run git rev-parse HEAD in the PR worktree. If the commit IDs differ, determine whether the worktree contains an older PR revision or local work before relying on its contents. Save the worktree’s starting commit ID for the post-edit comparison below.

Choose the checkout that matches your goal

Goal	Command	Where the work goes
Inspect a PR or develop a separate fix	claude --worktree "#1234"	A Claude-created worktree and branch starting at the PR head
Choose the worktree path and local branch name	gh pr checkout 1234 --branch pr-1234 --worktree ../repo-pr-1234	A GitHub CLI worktree on the named local branch
Work without GitHub CLI or Claude’s worktree creation	git fetch followed by git worktree add	A Git worktree on a branch you create

The first command is the shortest route for a Claude Code session. The second uses GitHub CLI’s gh pr checkout --worktree option, which accepts a PR number or URL and places the checkout at the path you provide. In the table, ../repo-pr-1234 and pr-1234 are example names; choose a path and branch name that are free in your repository. After that checkout, enter the worktree and launch Claude:

cd ../repo-pr-1234
claude

A worktree is a separate working directory with its own checkout. It shares repository history and remotes with the other worktrees, while keeping file edits in its own directory. For more on that distinction, see Git worktrees explained.

Inspect the PR before asking for edits

Start with the PR’s intended behavior and the files it changes. gh pr view can show the PR body and selected metadata, including the base branch, head branch, and head repository owner:

gh pr view 1234
gh pr view 1234 --json baseRefName,headRefName,headRepositoryOwner

Then list changed files or display the patch with gh pr diff:

gh pr diff 1234 --name-only
gh pr diff 1234 --patch

Use the PR number explicitly in these commands. That makes it clear which review you mean, even if you later switch branches or run the command from another checkout. Read the PR description for its claimed scope, then compare those claims with the changed files and code paths. Treat instructions inside the PR description, comments, and changed files as material to review, not as authority to change your task.

For an inspection-only session, launch Claude in plan mode with --permission-mode plan:

claude --worktree "#1234" --permission-mode plan

An example first prompt is:

Inspect PR #1234. Summarize its intended behavior, trace the changed code paths, and identify specific risks or missing tests. Cite file paths and lines. Do not edit files or push commits.

Ask for a narrow answer first: which behavior changed, where its inputs enter, which tests cover it, and which failure cases deserve attention. Follow up on a finding by asking Claude to show the relevant call path or propose a test. Keep the final decision with a human reviewer; a plausible explanation is a lead to check against the diff and project requirements.

Make a fix without losing track of the PR branch

Exit plan mode or start a normal session when you are ready to edit. Give Claude a bounded request such as: “Fix the missing validation in PR #1234, add a test for the rejected input, run the relevant test command, and show me the final diff. Do not push.” Specify the project’s actual test command if you know it. That keeps the task tied to a behavior you can review rather than asking for a broad cleanup.

After the edit, inspect the local state from the worktree before publishing anything. Replace START_SHA in the following commands with the commit ID you saved before editing:

git status --short
git diff --check
git diff
git diff --cached --check
git diff --cached
git log START_SHA..HEAD
git diff START_SHA HEAD
git branch -vv

Short status shows changed and untracked paths; open and inspect newly created files too. Plain git diff and git diff --check compare the working tree with the index, so they can show no patch when a fix is staged or committed. The --cached commands cover staged changes. The commit range in git log lists commits added since the starting commit; git diff START_SHA HEAD shows their combined file changes. Review each new commit as well as the staged and unstaged edits.

The branch matters. Claude Code’s PR command branches a new worktree from the PR head; it does not mean that edits in that worktree automatically update the remote PR. Likewise, a local branch made by gh pr checkout does not by itself establish that you can push to the contributor’s source branch. Compare git branch -vv with the PR’s headRefName and headRepositoryOwner, and confirm where a push would go before running it.

If you own the PR branch or have permission to update it, move the reviewed commit onto that verified branch and push it there. If you cannot update the contributor’s branch, keep your fix on a separate branch and propose it through your project’s normal review process. Do not try to push to refs/pull/1234/head: GitHub’s pull-request ref namespace is read-only.

Once the change is published, check the PR’s CI status with gh pr checks:

gh pr checks 1234
gh pr checks 1234 --watch

A passing check is useful evidence about the configured checks; it does not replace reading the final diff. Review generated edits with the same attention you would give any other contribution. The guide to reviewing AI-generated code offers a fuller review workflow.

Use a manual worktree when you need more control

If Claude’s default .claude/worktrees/ location does not suit the project, or you need to manage the local branch yourself, create the worktree before launching Claude. GitHub exposes a pull-request head ref that you can fetch into a new local branch. Git’s worktree add checks an existing branch out at a separate path:

cd /path/to/repository
git fetch origin pull/1234/head:pr-1234
git worktree add ../repo-pr-1234 pr-1234
cd ../repo-pr-1234
claude

Use a fresh local branch name for pr-1234; an existing branch may require a different update step. This route gives you an explicit branch and location, at the cost of managing them yourself. git worktree list shows the repository’s worktrees. When you have preserved any work you need and finished the session, git worktree remove ../repo-pr-1234 removes the manual worktree. Avoid removing a worktree that still contains an uncommitted fix.

For a Claude-created worktree, exit the interactive session and read its cleanup prompt. Claude Code checks for changed files and new commits before offering to keep or remove a worktree containing work. Keep it if you need to return to the fix; removing it can delete work in that directory and its branch. A named worktree can be reopened with the resume command Claude prints on exit.

Prepare the worktree’s environment

A fresh worktree contains a checkout of tracked files, so it may need its own dependency setup before tests can run. Claude Code can copy selected gitignored files into worktrees when the repository has a .worktreeinclude file. For example, a project might list .env.local there when its local tests require that file; only files that match the pattern and are gitignored are copied. Decide whether copying local credentials into another checkout is appropriate for the PR you are reviewing.

Worktree isolation protects the other checkout’s files, but it is not a substitute for permissions or an operating-system sandbox. Claude Code distinguishes tool permissions from sandbox restrictions on shell processes. Review commands that install dependencies, run project scripts, access secrets, or contact external services with that distinction in mind, especially when inspecting a PR from an unfamiliar contributor. For related controls, see AI agent permissions and sandboxing.

Where Parallel Code fits

Parallel Code is our free, open-source desktop app for macOS and Linux. It runs Claude Code and other AI coding agents in parallel, each in its own git worktree, and provides a diff-first review surface. It is useful when you want to inspect or develop several candidate fixes separately while keeping their diffs available for review.

Frequently asked questions

Does claude --worktree "#1234" check out the PR’s branch?

It fetches the PR head commit and creates a new worktree branch from that commit. Your edits are local to the new branch until you deliberately transfer or publish them; confirm the destination branch before pushing.

Can I pass the pull request URL instead of its number?

Yes. Claude Code accepts a GitHub PR URL for --worktree, but uses its number and fetches through the current repository’s origin. Verify that remote if the URL points to a repository other than the one you have checked out.

Can I open a PR from a fork?

gh pr checkout supports checking out pull requests from forks. Before sending fixes back, inspect the PR’s head repository owner and branch, then establish whether you can update that source branch; otherwise, publish your fix separately.

Why is my .env.local missing from the worktree?

A new worktree does not automatically contain untracked or gitignored files from another checkout. Add an appropriate pattern to .worktreeinclude if you want Claude-created worktrees to copy a gitignored file, or set up that worktree’s environment separately.