Kick Off a Task, Walk Away, Find a PR: Claude Code's Auto-PR Background Agents

Chris Harper

3 min read

Jul 2, 2026 · 04:06 UTC

Workflow

Claude Code

Agents

TL;DR: Spawn a background agent in a worktree, walk away — v2.1.198 will commit, push, and open a draft PR when the work is done. Add a Notification hook to get pinged without polling.

Background agents in Claude Code have always been useful for parallel work. The new auto-PR step closes the loop: when a background agent completes code work in a git worktree, it automatically commits all changes, pushes to origin, and opens a draft pull request — no manual git push && gh pr create step needed.

Here's the full workflow.

Step 1: Spawn the background agent

# From the shell
claude agents spawn "Refactor the UserService class to use constructor injection and add unit tests"

Or from inside an interactive Claude Code session:

/agents
> New background agent: Fix all TypeScript errors in src/auth/ — don't change the public API

Claude automatically creates an isolated git worktree for the agent's work.

Step 2: Wire a Notification hook (optional but recommended)

Add to .claude/settings.json:

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "notify-send \"Claude: $CLAUDE_NOTIFICATION_MESSAGE\""
      }]
    }]
  }
}

Two events now fire through this hook:

agent_needs_input — the agent is blocked and needs you to intervene (it won't silently fail)
agent_completed — the agent finished; look for the PR

On macOS, swap notify-send for osascript -e 'display notification "..." with title "Claude Code"'. On a server or in CI, post to a webhook instead.

Step 3: Review the PR

When the agent finishes, it commits, pushes to origin, and opens a draft PR with the task description as the title. No extra step on your end. Open GitHub, review the diff, and merge when ready.

When this works well

Refactors with a well-bounded scope ("convert all fetch calls in this module to use our API client")
Adding tests to existing, well-typed code with clear specs
Bug fixes with a concrete reproduction step in the task description

When to skip it

Tasks that require architectural decisions mid-way — the agent will surface those via agent_needs_input rather than making the call itself
Work where you want to review intermediate states before the agent commits direction
Anything touching infra or deployment — let humans push those buttons

The pattern pairs naturally with the 1M-token context window: a background agent can accumulate a full trace of reads, edits, and tool calls across a large codebase without hitting a context wall, then close with a reviewable PR.