Running parallel coding agents with Cursor 3 and Claude

Managing multiple coding tasks in sequence is slow. Cursor 3 solves this with its Agents Window — a dedicated interface for spinning up parallel Claude agents that each work on isolated Git worktrees simultaneously. One agent refactors your API layer while another rewrites the test suite. Neither knows the other exists, and you don’t get merge conflicts.

This post walks through setting up that workflow from scratch: configuring Background Agents, triggering Cloud Agents from external tools like Slack and GitHub, and keeping everything visible in a single monitoring panel.

What Cursor 3’s Agents Window actually gives you

The Agents Window (available in Cursor 3.x, released early 2026) is a first-class UI panel — not just a chat tab — specifically built for managing multiple agent sessions. Each session gets its own:

• Git worktree — a separate checkout of your repo at a specific branch, so file writes from two agents never overlap
• Environment context — local machine, SSH remote, or a cloud sandbox (Cursor Cloud Agents)
• Tool access — terminal, file editor, browser preview, MCP servers

You can have several agents running concurrently. The panel shows each agent’s current task, last action, and status (running / waiting / complete). There’s no need to tab between chat windows or manually track what’s happening.

If you’ve already worked through how to set up Cursor Rules for consistent AI-assisted coding, those rules apply per-agent automatically — each worktree inherits your .cursorrules file from the repo root.

Setting up isolated Git worktrees for parallel agents

Before you launch any agents, structure your repo so each one works in isolation. Git worktrees let you check out multiple branches from the same repo into separate directories without cloning again.

# From your repo root
git worktree add ../project-api-refactor feature/api-refactor
git worktree add ../project-test-update feature/test-update

Now you have:

/project/               ← main branch, your editor root
/project-api-refactor/  ← Agent 1 works here
/project-test-update/   ← Agent 2 works here

In Cursor 3, open the Agents Window (Cmd+Shift+A on macOS or via the left sidebar agent icon). Click New Agent, then set the working directory to /project-api-refactor and assign it a task. Repeat for the second agent pointing at /project-test-update.

Each agent operates with full read/write access only within its worktree directory. There’s no shared mutable state between agents unless you explicitly configure a shared read-only context file.

Configuring Background Agents and Cloud Agents

Background Agents run locally on your machine. They use your local Claude API key (configured in Cursor settings under AI > API Keys) and have full access to your filesystem, terminal, and any MCP servers you’ve set up for local development.

A typical agent prompt for the API refactor task looks like this in the Agents Window task field:

Refactor all route handlers in /src/routes/api/ to use the new
ResponseBuilder class located in /src/utils/ResponseBuilder.ts.
Maintain existing HTTP status codes. Do not modify test files.
Commit changes to feature/api-refactor when done.

Cloud Agents run in Cursor’s managed cloud environment. They’re useful when you want to offload compute, run agents against a staging environment, or trigger tasks from outside your editor entirely.

To configure a Cloud Agent trigger from GitHub Actions:

name: Trigger Cursor Cloud Agent on PR

on:
  pull_request:
    types: [labeled]

jobs:
  trigger-agent:
    if: contains(github.event.label.name, 'agent-refactor')
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Cursor Cloud Agent
        run: |
          curl -X POST https://api.cursor.com/v1/agents \
            -H "Authorization: Bearer ${{ secrets.CURSOR_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "task": "Review PR diff and update integration tests in /tests/integration/",
              "branch": "feature/test-update",
              "repo": "your-org/your-repo",
              "environment": "cloud"
            }'

You can also do this from a Slack slash command by routing through a small webhook handler — similar to the pattern covered in watching a directory and notifying Slack.

Running the parallel workflow: API refactor + test update

Here’s a concrete example. You have a Laravel API where you’re migrating from plain array responses to a structured ApiResource format. Two agents handle this in parallel:

Agent 1 — API Refactor (Background Agent, worktree: feature/api-refactor):

Task: Convert all controllers in app/Http/Controllers/Api/ to use
Laravel ApiResource classes. Create resource files in
app/Http/Resources/ following existing naming conventions.
Do not touch test files. Run `php artisan test --filter=Unit`
after changes and fix any failures before committing.

Agent 2 — Test Update (Background Agent, worktree: feature/test-update):

Task: Update all tests in tests/Feature/Api/ to assert against
the new ApiResource response structure (data wrapper, pagination
meta). Reference the ApiResource files in app/Http/Resources/
from the main branch. Commit when all tests pass.

Agent 2 reads resource definitions from main (read-only reference) while writing only to its own worktree. No collision. Both agents run php artisan test independently in their own environments.

If you want to see how this kind of structured API thinking translates to building the API itself first, building a RESTful API with PHP and Laravel is a solid starting point before layering in agents.

Monitoring progress and merging without bottlenecks

The Agents Window shows a live feed for each agent: current file being edited, last terminal command run, token usage, and task status. You don’t need to babysit it.

When both agents complete, you merge sequentially — not simultaneously — to avoid conflicts:

# Merge API refactor first (no test changes, clean merge)
git checkout main
git merge feature/api-refactor

# Now merge test updates (tests reference resources that now exist in main)
git merge feature/test-update

Because the worktrees were scoped correctly upfront, this merge is almost always clean. The agents were forbidden from touching each other’s file domains by instruction, not just by convention.

For teams, you can enforce this with Cursor Rules scoped per directory — each agent’s .cursorrules specifies exactly which paths it owns.

If you’re building more complex agent pipelines that go beyond editor tooling, building your first AI agent with Python and Claude shows the underlying mechanics of how Claude agents reason about tasks and tools.

Key takeaways

• Git worktrees are non-negotiable for parallel agents — without isolated directories, concurrent file writes will corrupt each other’s work
• Scope agent tasks by file domain, not by feature — “own these directories, don’t touch those” is more reliable than abstract task descriptions
• Cloud Agents + GitHub webhooks let you trigger parallel work from PR events, removing the editor as a bottleneck entirely
• The Agents Window gives you a single pane of glass across all running sessions — use the status feed to catch stuck agents early rather than waiting for a commit that never comes