How to Use Claude Code Projects to Run Multiple AI Agents

Managing multiple Claude Code sessions manually creates friction. A developer must decide which agent handles which task, maintain separate branches, repeat context across conversations, monitor progress across browser tabs, review results, and reconcile conflicts. The work gets split, but the coordination stays with you.

Anthropic redesigned Claude Code Projects on September 17, 2026, introducing a new experience where users describe what needs to be done and Claude manages the work by scoping the request, delegating tasks, coordinating parallel threads, reviewing outputs, and assembling results. The coordinator does the orchestration. You define the goal. Threads execute independent work in parallel. 

This guide explains how Claude Code Projects work, how to set one up, how to run multiple AI agents effectively, and how to avoid common pitfalls like merge conflicts and excessive usage consumption.

How Claude Code Projects Run Multiple AI Agents

Claude Code Projects coordinates work across parallel cloud coding sessions under a single conversation. Rather than manually opening and managing separate Claude Code instances, you describe a larger development objective, and Claude’s coordinator distributes independent workstreams across multiple threads while the project conversation provides a central monitoring point.

Each thread is a Claude Code cloud session working on its own branch and copy of the repository, and the coordinator keeps work organized while overlapping code changes are resolved as merge conflicts like any other pull request. 

At a glance:

• Project defines the goal and shared context
• Coordinator plans and delegates tasks
• Threads execute larger independent workstreams in parallel
• Subagents handle focused tasks within threads
• Shared memory carries project decisions forward
• Pull requests provide integration points
• Human review remains a critical step

What Is the Difference Between Projects, Threads, and Subagents?

These four components form a hierarchy. Understanding each one prevents confusion when designing your workflow.

The critical distinction: threads are not simply lightweight connections. Each thread is a full Claude Code cloud session working on its own branch and copy of the repository. A thread has its own working context, can run tests independently, open its own pull requests, and continue work after you close your laptop. This makes threads suitable for larger, longer-running work like “build the API server” or “migrate the database schema.” 

Subagents, by contrast, are specialized workers within a conversation or thread. They handle focused tasks, code review, security audit, documentation, and return a summary. A thread can spawn subagents to parallelize work within its own scope.

How the Claude Code Coordinator Works

The coordinator operates in five steps:

1. Understands the project goal – Reads your description of what needs to be built or changed
2. Determines the work – Identifies all tasks required to reach the goal
3. Identifies independent workstreams – Recognizes which tasks can run in parallel without blocking each other
4. Delegates to threads – Starts new threads for independent work or routes tasks to existing ones
5. Monitors, reviews, and synthesizes – Watches progress, reviews outputs, resolves dependencies, and assembles the result

Example scenario:

Goal: “Retire a deprecated API across our application.”

The coordinator might identify these parallel workstreams:

• Update the API repository to support both versions
• Migrate the web application from v1 to v2
• Migrate the mobile application from v1 to v2
• Update tests to cover the new API version
• Write migration documentation

These tasks can run simultaneously because they don’t depend on each other. Once all are complete, they merge and you review the pull requests.

How to Create a Claude Code Project

Step 1: Access Claude Code Projects

Claude Code Projects are currently available in beta to select Claude Pro and Max subscribers using cloud sessions, with access expanding over the coming week and eventual availability coming to all Claude users and Team and Enterprise plans. If you have Pro or Max and don’t yet have access, you can join a waitlist through your Claude Code interface. 

Step 2: Start a New Project

Open Claude Code and select “New Project.” You’ll define:

• Project goal – A clear description of what you want to accomplish
• Repository or context – The codebase or knowledge base the threads will work with

Step 3: Connect Your Repository

If using a GitHub repository, connect it to the project. This allows threads to:

• Work on isolated branches
• Run tests in CI/CD pipelines
• Open pull requests for review
• Merge approved changes

Step 4: Configure the Project

Set project-level configurations:

• Instructions – Persistent rules for all threads (coding standards, architecture decisions)
• Model – Which Claude model the coordinator uses
• Effort level – How much reasoning effort to apply
• Cloud environment – Resource configuration
• Connectors and plugins – External tools like GitHub, databases
• Coordinator vs. thread models – You can assign different models to the coordinator (higher reasoning) and worker threads (faster execution)

Step 5: Define Your Project Goal

Write a goal that establishes scope and helps the coordinator plan effectively.

Strong example:

“Migrate our application from API v1 to v2. Identify all callers across three repositories: the core API, web application, and mobile application. Parallelize independent migrations, run the test suite for each component, open pull requests for completed work, and report dependencies that require a specific merge order.”

Why this works:

• Specifies the objective
• Names the repositories involved
• Indicates what can run in parallel
• Defines testing requirements
• Clarifies deliverables
• Asks for dependency analysis

Weaker example:

“Migrate to API v2.”

This lacks scope, doesn’t clarify which repositories are involved, and gives the coordinator minimal guidance on how to parallelize.

How to Run Multiple AI Agents With Claude Code

1. Start With One Clear Outcome

The coordinator works better when you describe the result rather than prescribe every step. Say “retire this deprecated payment processor” rather than “fix line 42 in service A, then update service B, then run this test.”

2. Break the Work Into Independent Workstreams

Identify work that can run simultaneously without blocking each other.

Example: Build a subscription management system

• Thread 1: Backend subscription API
• Thread 2: Database schema and migrations
• Thread 3: Web UI for subscription management
• Thread 4: Automated test suite
• Thread 5: API documentation

These can work in parallel because the test suite and documentation depend on the API design, which is independent work.

3. Let Independent Threads Run in Parallel

Each thread is a full Claude Code session working on its own branch and copy of the repository, and threads can further split their delegated work into pieces using subagents, loops, and workflows when needed so large assignments finish faster. Don’t artificially serialize work; if two threads don’t depend on each other, let them run together. 

4. Monitor the Main Project Conversation

Check the project chat periodically to:

• See progress summaries
• Understand blockers
• Answer clarifying questions
• Steer direction if needed

5. Inspect Individual Threads When Needed

Dive into a specific thread when:

• A thread is blocked and needs clarification
• Test results are unexpected
• You want to review implementation details
• An architectural decision needs adjustment
• Two threads might have conflicting approaches

6. Review Pull Requests and Test Results

As threads complete work, they open pull requests. The overlap is resolved as a merge conflict just like any other PR. Review each PR, run tests, merge when approved. This is the integration point where human judgment remains essential. 

Read More: Claude Code vs OpenAI Codex: Features, Benchmarks, Pricing & Performance

A Real Claude Code Multi-Agent Workflow Example

Project Goal: Add a two-factor authentication (2FA) system to an existing SaaS application.

Workstreams and thread ownership:

• Thread 1 (Backend): Implements TOTP/SMS verification, stores secrets in the database, and creates API endpoints for registration and verification
• Thread 2 (Database): Adds the user_2fa table, secret encryption, and backup codes
• Thread 3 (Frontend): Builds QR code display, manual entry fallback, and verification UI
• Thread 4 (Tests): Writes unit tests for verification logic, integration tests for the full flow, and security tests
• Thread 5 (Documentation): Documents setup instructions, API changes, and user guides

Dependencies:

• Database schema must be stable before the backend can write to it
• Backend API must be ready before frontend can integrate it
• Tests can run as each component is ready
• Documentation should be drafted alongside implementation

Parallel execution:
Threads 1, 2, and 3 can start immediately. Threads 1 and 3 wait for Thread 2 to stabilize the database. Threads 4 and 5 work as soon as there’s code to test and document.

Result:
The project pulls together: pull requests from each thread, merged in dependency order, reviewed for security (especially Thread 1), tested end-to-end, and documented.

Claude Code Threads vs. Subagents

Understanding when to use threads versus subagents determines whether your project completes efficiently or wastes resources.

Threads are best for:

• Independent feature areas (backend, frontend, database)
• Different repositories in a monorepo
• Large migrations
• Long-running workstreams that take multiple turns
• Tasks requiring their own full Claude Code session

Subagents are better for:

• Focused research (investigating a library, understanding unfamiliar code)
• Code review (checking implementation against standards)
• Security scanning
• Small, specialized investigations
• Tasks that will finish in one or two turns

Hierarchy:
Project → Coordinator → Thread → Subagent

A thread can spawn subagents for parallelized focused work. Subagents cannot spawn other subagents. The project conversation spawns threads. This prevents excessive nesting.

How to Use CLAUDE.md With Multi-Agent Projects

CLAUDE.md files provide Claude with persistent instructions that apply to anyone working on the project, including build and test commands, coding standards, architectural decisions, naming conventions, and common workflows. 

In a multi-agent project, CLAUDE.md becomes a shared rulebook. Every thread loads it automatically, ensuring consistency without repeating context.

Example CLAUDE.md for a multi-agent project:

# Project: Authentication System Redesign

## Tech Stack

– Node.js 18+

– TypeScript (strict mode required)

– PostgreSQL with Prisma ORM

– Next.js 14+ for frontend

## Build & Test Commands

– `npm run build` – Compile TypeScript

– `npm test` – Run full test suite

– `npm run test:security` – Run security tests (required before PR)

– `npm run db:migrate` – Apply database migrations

## Coding Standards

– TypeScript strict mode is non-negotiable

– All public functions must have JSDoc comments

– No secrets in code; use environment variables

– All async functions must have proper error handling

## Architecture Rules

– Backend lives in `/api` and does not import from `/web`

– Frontend lives in `/web` and uses API endpoints only

– Database changes require migrations in `/migrations`

– All authentication logic belongs in `/api/auth`

## Security Requirements

– Do not modify authentication behavior without tests

– All security changes require @security-reviewer approval

– No SQL anywhere except Prisma queries

– Environment variables must not be logged

## Database Rules

– No schema changes without migrations

– Never run migrations directly; use the CLI

– Breaking changes must be backwards-compatible for 2 releases

– Add indexes for any new foreign keys

This file prevents duplicate instructions. Threads reference it automatically. New context doesn’t need to re-teach the same standards.

How Shared Memory and the Project Library Help

Two distinct mechanisms preserve continuity across threads:

Shared memory: Every thread adds to and draws from a shared memory, reducing the need for complex prompt engineering. As the project progresses, the coordinator captures important decisions. If a thread discovers that “the release date moved to Friday,” that fact enters shared memory. Future threads and the coordinator reference it automatically. Examples: 

• “Feature X was intentionally removed to reduce scope”
• “A specific vendor API has a 30-second timeout”
• “The billing service is under active refactor; don’t touch it yet”
• “Users with beta flags see the new UI”

Project Library: Projects now include a library that collects files you add and artifacts produced by Claude, making it easier to find relevant materials and for new work to build on past efforts. The library accumulates: 

• Uploaded reference documents
• Generated code artifacts from previous work
• Test utilities created during the project
• API specifications produced by threads
• Configuration files and scripts

Shared memory is ephemeral context that evolves. The Library is persistent assets that threads reference.

How to Prevent Conflicts Between Multiple Claude Code Agents

Parallel work introduces merge conflicts. Prevent them strategically.

Use Clear Ownership

Assign file ownership to threads. Example:

• Thread 1 owns /api → only Thread 1 modifies anything in the API folder
• Thread 2 owns /web → only Thread 2 modifies web code
• Thread 3 owns /tests → only Thread 3 writes test files
• Thread 4 owns /docs → only Thread 4 updates documentation

Ownership prevents accidental overlap. When boundaries are clear, conflicts become predictable and rare.

Establish Strict Dependencies

Some tasks must wait for others. Make this explicit in the project goal:

Database schema → API implementation → Frontend integration → End-to-end tests

Don’t ask the frontend thread to depend on an API contract the backend thread hasn’t finalized. Create a brief specification first, share it in project memory, then let work proceed.

Use Pull Requests as Checkpoints

Each thread opens a PR when work is complete. Code review catches:

• Unintended overlaps
• Architectural misalignment
• Missing tests
• Undocumented decisions

Give Every Agent Clear Acceptance Criteria

Each workstream should define:

• Scope (what files it touches)
• What it should produce (code, tests, documentation)
• Dependencies (what it needs from other threads)
• Non-functional requirements (performance targets, security constraints)

Avoid Unnecessary Overlap

If two threads both modify the same file, merge conflicts are guaranteed. If three threads each add a function to the same utility file, coordinating the merge becomes tedious. Push common work to a single owner thread and have others import it.

Best Prompt for Claude Code Multi-Agent Projects

Effective project goals share a structure. Here’s a template that works for most multi-agent work:

[Project Name and High-Level Goal]

Migrate our payment processing from Stripe to our in-house system. The work spans three repositories and can be parallelized.

Repositories involved:

• API repository (payments API)
• Web application (checkout flow)
• Mobile application (payment screens)
• Configuration repository (feature flags, secrets)

What needs to happen:

1. Update the payments API to handle both systems in parallel
2. Migrate web checkout to use the new system
3. Migrate mobile payment screens to use the new system
4. Update configuration and feature flags to control the migration
5. Write tests covering the new flow and the old-to-new transition
6. Document the migration for the support team

What can run in parallel:

• API updates and configuration
• Web and mobile migrations (both depend on API)
• Tests (as code is ready)
• Documentation (as work progresses)

What must be sequential:

• API design → implementation → testing → deployment
• Feature flag setup → web migration → mobile migration

Success criteria:

• Zero transaction failures during migration
• All tests pass
• No performance degradation
• Backwards compatibility maintained for one release
• Pull requests open for each component, reviewed before merge

Constraints:

• No direct database access; use the API only
• All changes logged for audit
• Feature flag in place before production deployment
• Team approval required for any payment-related changes

Structure your prompt this way, and the coordinator will understand the full scope, parallelizable work, dependencies, and success metrics.

When Should You Use Claude Code Parallel Agents?

Parallel agents shine in specific situations.

Best for:

• Large migrations across multiple systems
• Projects spanning multiple repositories
• Frontend and backend work that can proceed independently
• Test-heavy development where testing can parallelize with implementation
• Documentation alongside code
• Teams handling related but independent bug fixes simultaneously
• Long-running projects where work arrives in batches

Less suitable for:

• Tiny one-file bug fixes (overhead exceeds benefit)
• Highly sequential tasks where every step depends on the previous one
• Work where all agents must modify the same code
• Projects where task boundaries are unclear
• When you need to minimize usage consumption

Parallel agents work when tasks are genuinely independent, not simply because more agents are available. Parallelism adds overhead: context coordination, branch management, potential merge conflicts. Use it when the benefit justifies that cost.

Common Problems With Multi-Agent Claude Code Workflows

Agents duplicate work

Cause: Task boundaries were unclear.
Fix: Define ownership. “Thread 1 owns the user service, Thread 2 owns the payment service.” Make it explicit.

Agents modify the same files

Cause: Excessive overlap in scope.
Fix: Have one thread own shared files. Others use and extend, not modify.

Merge conflicts spike

Cause: Parallel changes to the same code without clear coordination.
Fix: Establish dependencies. Stabilize the schema before parallel implementations. Use feature branches strictly.

Context becomes inconsistent

Cause: Important project decisions weren’t captured in shared memory.
Fix: Update project memory when decisions change. “Database index strategy changed to support read replicas.” Let future threads reference it.

Usage gets consumed quickly

Cause: Projects can reach usage limits faster because each thread is a full Claude Code session.
Fix: Monitor project usage in the UI. Choose lower effort levels for routine work. Use Pro/Max plans if heavy parallelization is your workflow. 

Agents produce technically correct but incompatible changes

Cause: Missing architectural constraints or API contracts.
Fix: Specify API contracts, data structures, and architectural decisions upfront. Use CLAUDE.md to encode rules all threads follow.

Limitations of Claude Code Projects

Be aware of current constraints:

Availability: Projects are in beta, currently available to select Claude Pro and Max subscribers using cloud sessions, with broader access coming over the following week and eventual availability to Team and Enterprise plans. 

Existing projects: If you have existing projects on the web or desktop, they continue working as before and will be upgraded as the rollout expands.

Cloud-only for now: Threads run in the cloud today; running on your machine alongside your local tools and code and behind your network is coming very soon. Local execution is planned but not yet available. 

Thread limit: The enforced limit is 200 new threads per day across your projects. 

Usage consumption: Each thread is a full session. Because of this, projects can reach usage limits faster. Running 5 parallel threads consumes usage roughly 5x faster than a single thread. 

Merge conflicts: Parallel work on the same code creates normal Git conflicts. The coordinator doesn’t prevent them, humans must resolve them during PR review.

Human review required: Pull requests from threads are not automatically merged. Code review remains essential, especially for security-critical changes.

Claude Code Projects vs. Manually Running Multiple Claude Code Sessions

When should you use Projects instead of opening separate sessions manually?

Projects solve the coordination problem. Use them when you have multiple independent workstreams that would otherwise require manual switching and context repetition.

Use manual sessions when your task is small enough to fit in a single session and you don’t benefit from persistence.

Best Practices for Claude Code Multi-Agent Workflows

• Start with a measurable goal. “Retire API v1” is better than “update the system.”
• Separate independent workstreams clearly. If Thread A depends on Thread B, say so.
• Keep dependent work sequential. Don’t ask two threads to build what the third thread depends on.
• Give every workstream clear boundaries. Ownership prevents conflict.
• Use CLAUDE.md for persistent rules. Repeat standards once, not in every thread.
• Monitor shared memory. Update it when decisions change.
• Use the project library. Store reference documents and generated artifacts there.
• Require tests. Each thread should test its own work.
• Review pull requests carefully. Merges are the integration points where quality matters.
• Track usage by project. Set models and effort levels strategically.
• Keep humans responsible for architecture. Agents implement; people decide.

Conclusion

Claude Code Projects transform how you approach multi-faceted development work. Instead of manually dividing tasks across separate sessions, you define the goal and let the coordinator manage the parallelization:

Goal → Coordinator → Parallel Threads → Subagents where needed → Code, tests, and pull requests → Human review → Integration

The feature works best for developers working on larger codebases, teams handling multiple independent workstreams, developers who currently manage several Claude Code sessions manually, and users comfortable reviewing AI-generated code.

Start with one project where the work naturally separates into two or three independent workstreams. A migration, a multi-part feature, or a refactor across repositories are ideal candidates. Run it, measure usage, review the PRs, and compare against your previous single-session workflow. That practical comparison is worth more than any tutorial.

Then expand to larger projects as you understand how to scope work, manage dependencies, and prevent conflicts. Parallel agents are powerful when used strategically, not as a default.

Frequently Asked Questions

What are Claude Code Projects?

Claude Code Projects are a redesigned feature that turns a project into a central conversation where Claude acts as a coordinator, delegating work across multiple parallel cloud coding sessions. Each session is independent, works on its own branch, and reports back to the main project conversation.

Can Claude Code run multiple AI agents at the same time?

Yes. Claude Code Projects have no fixed number of concurrent threads, Claude starts as many as it needs, but the enforced limit is 200 new threads per day across your projects. 

How do Claude Code threads work?

Each thread is a Claude Code cloud session working on its own branch and copy of the repository. Threads run independently, can modify code, run tests, and open pull requests. They share project memory and the project library with other threads. 

What does the Claude Code coordinator do?

The coordinator reads your project goal, determines what work is needed, identifies tasks that can run in parallel, delegates work to new or existing threads, monitors progress, reviews outputs, coordinates dependencies, and assembles the final result.

What is the difference between Claude Code threads and subagents?

Threads are full Claude Code cloud sessions for large, independent workstreams. Subagents are specialized workers within a conversation or thread, best for focused tasks that finish quickly. A thread can spawn subagents; subagents cannot spawn other subagents.

Do Claude Code Projects share memory between agents?

Yes. Every thread adds to and draws from a shared memory, reducing the need for complex prompt engineering. Important project decisions, changes, and learnings persist across threads automatically. 

Can multiple Claude Code agents work on the same repository?

Yes, but each thread works on its own branch and copy of the repository. If any threads work on the same code, the overlap is resolved as a merge conflict just like any other PR. 

Does running multiple Claude Code threads use more tokens?

Yes. Because each thread is a full Claude Code session, projects can reach usage limits faster. You can monitor project-specific usage and adjust models and effort levels to manage consumption. 

Can Claude Code Projects create pull requests?

Yes. Each thread can run tests and open pull requests to your connected repository. The project coordinator monitors these, and you review them before merging.

Can Claude Code Projects run locally?

Not yet. Threads run in the cloud today; running on your machine alongside your local tools and code and behind your network is coming very soon.