gh pr create --draft From a Git Worktree

To run gh pr create --draft from a git worktree, push the agent’s branch, then create the PR with that branch as --head and the intended destination as --base. You can do both from your usual terminal without switching the branch in your main checkout. GitHub CLI’s --draft, --head, --base, and --repo flags make the PR target explicit.

Before starting, install and authenticate GitHub CLI and make sure you have permission to push to the selected remote. Git authentication for a push does not establish the CLI authentication needed for the PR commands.

These are example names in the commands below: the linked worktree is ../project-agent-auth, its branch is agent/auth-fix, and the GitHub repository is owner/example. Replace them with your worktree path, branch, repository, and actual PR text. The steps below check each value before anything is pushed.

Identify the worktree and branch

A linked worktree has its own working tree and checked-out branch, while remaining attached to the same Git repository. git worktree list shows which branch is checked out at each path. Start there if several agents have produced branches and the directory names no longer make the mapping obvious.

git worktree list
git -C ../project-agent-auth branch --show-current
git -C ../project-agent-auth status --short

Git’s -C option runs a command as though it started in the specified directory. It lets every Git command above target the agent worktree while your terminal stays in the main directory. The PR command later uses --repo and --head for the same reason: the terminal’s current branch should not decide which change gets published.

Before pushing, inspect the remote’s push destination:

git -C ../project-agent-auth remote get-url --push --all origin

git remote get-url --push --all origin lists all push URLs for origin. Check that every destination points to the repository selected by --repo owner/example, or to the intended fork if you will use --head username:branch. If a destination differs, resolve that mismatch before pushing.

Check that git branch --show-current prints the branch you intend to publish. It prints nothing for a detached HEAD. If that happens, create or select a branch in the agent worktree before following the push example; do not assume its directory name is a branch name. Also confirm that the worktree’s branch is different from your base branch.

git status --short reports staged, unstaged, and untracked paths. A clean result is a useful checkpoint before publishing. If it lists files you expect in the PR, review and commit those files in the agent worktree first: pushing a branch publishes its commits, not loose edits in its working directory. If it lists generated files or unrelated changes, decide what to do with them before creating the PR.

For background on why the two checkouts can hold different branches, see how Git worktrees isolate agent work.

Review the change against the intended base

Choose the PR base deliberately. main is only an example; a team may use another integration branch. Fetch before comparing so your local remote-tracking branch reflects the remote’s latest fetched state. git fetch origin updates remote-tracking branches according to the configured fetch rules without checking out a different branch.

git -C ../project-agent-auth fetch origin
git -C ../project-agent-auth diff --stat origin/main...HEAD
git -C ../project-agent-auth diff origin/main...HEAD
git -C ../project-agent-auth diff --check origin/main...HEAD

The three-dot form of git diff compares the head with its common ancestor with the base. --stat gives a compact file summary; the full diff is where you check the agent’s changes. --check reports introduced whitespace errors or conflict markers and exits unsuccessfully when it finds them. Review the scope, tests, and any surprising file edits before sharing the branch; a draft label does not replace that check. The AI-generated code review workflow covers a more detailed review pass.

If origin/main is not the branch you intend to merge into, substitute the actual base in both the comparison and gh pr create --base. A mismatch can make the PR show changes you did not mean to propose. If the comparison is empty, stop and confirm that the agent committed its work on the branch you identified.

Push the branch, then create the draft

Run the push only after the branch name, push destination, and diff agree. git push --set-upstream origin HEAD pushes the current branch and records its upstream; HEAD here belongs to the worktree named by -C, not to your main checkout.

git -C ../project-agent-auth push --set-upstream origin HEAD
gh pr create --repo owner/example --draft --base main --head agent/auth-fix --title "Fix authentication retry" --body "Draft: review agent changes; tests pending."

The explicit --head also prevents gh pr create from offering to push or fork an unpushed current branch. That is useful when the CLI is invoked from the main directory, whose checked-out branch may be unrelated to the agent’s work. --repo selects the GitHub repository rather than relying on repository detection from that directory. The create command prints the new PR’s URL when it succeeds.

Write a title that describes the change and a body that tells reviewers what remains open. For a longer description, gh pr create --body-file <file> reads the body from a file; --fill instead derives title and body from commits. Explicit --title and --body values take precedence over --fill, so use the option that matches how much context the commits actually provide.

A GitHub draft PR cannot be merged, and code owners are not automatically requested to review it. Use the draft state when the branch is worth sharing but still needs validation or edits. It does not hide the branch or the proposed diff from people with access to the repository.

Keep working on the same branch

The worktree remains available after the PR is created. Make further commits there and push that same branch again; new commits on the head branch are added to its pull request. You do not need a second PR for each agent revision.

git -C ../project-agent-auth push
gh pr view agent/auth-fix --repo owner/example --json url,isDraft,baseRefName,headRefName
gh pr checks agent/auth-fix --repo owner/example

Once an upstream is set, the shorter git push uses the branch’s push configuration; keep the remote and branch explicit if your repository has unusual push settings. gh pr view accepts a branch and exposes fields including isDraft, baseRefName, and headRefName. Use those fields to confirm that the PR points where you expected. gh pr checks shows the PR’s check status, if checks are configured for the repository.

When the change is ready to request review, gh pr ready marks a draft PR ready:

gh pr ready agent/auth-fix --repo owner/example

Keep the worktree until you are finished using it. If you later remove it, follow the checks in the worktree cleanup guide so you can account for local edits and the branch first.

When the straightforward command needs adjustment

The agent has uncommitted edits. git status --short identifies them. Review and commit only the intended files in the agent worktree, then compare and push again. Opening a draft before that step would share the branch’s existing commits, not the edits still on disk.

The base branch is wrong. Set --base to the branch that should receive the change and compare against its remote-tracking counterpart. GitHub CLI can otherwise use a configured gh-merge-base value or the repository’s default branch, so spelling out --base avoids ambiguity in this workflow.

The push goes to a fork. Push to the fork remote, then use --repo for the upstream repository and --head username:branch for a user-owned fork. GitHub CLI documents that head syntax and notes that an organization name is not supported in that position. Confirm which remote received the branch before creating the PR.

The CLI offers to push or fork unexpectedly. Confirm the branch was pushed to the intended GitHub repository and that --head matches its remote branch name. An explicit --head skips the create command’s own push and fork prompts; it does not push a missing branch for you.

Where Parallel Code fits

Parallel Code is our free, open-source desktop app for macOS and Linux that runs AI coding agents in parallel, each in its own git worktree. Its diff-first review surface helps you choose a change to publish. You can then use the Git and GitHub CLI steps above for that worktree’s branch.

Frequently asked questions

Do I have to switch my main checkout to the agent branch?

No. Use git -C to inspect and push the agent worktree, then give gh pr create an explicit repository, head branch, and base branch. Your main checkout can stay on its current branch throughout.

Can I create the draft before the agent has committed everything?

Yes, if the branch already contains a useful committed change, but uncommitted edits will not be included in the pushed branch. Check git status --short, and make the PR body clear about what remains unfinished.

Will another push create another PR?

No. Push additional commits to the same head branch to update the existing PR. Use gh pr view agent/auth-fix --repo owner/example to find it again from a terminal outside the worktree.

What if the worktree is on a detached HEAD?

git branch --show-current will print no branch name. Create a branch in that worktree and confirm its name before pushing; the draft PR needs a head branch that GitHub can compare with the base.