Claude Code Projects: coordinator, threads, and beta limitations

Anthropic recently redesigned Projects in Claude Code. It is now a single coordinating conversation that launches parallel cloud sessions—threads—for tasks and receives reports from them. A project is worth creating when your work has a goal that will outlast a single session and generate new tasks—for example, developing a GitHub repository over several weeks. The need for parallel work alone is not enough. If you need to quickly fix one file here and now, an ordinary session is sufficient.

The work is led by a coordinator—a long-lived conversation in which Claude decides what to turn from your message into a task for a thread. The threads write the code: each is a separate cloud Claude Code session on its own repository branch. Several threads can run at once, each with its own context and branch. The coordinator sees what a thread reports on completion, but not every step it takes. It reports completed pull requests (requests to merge changes) to you and, at your command, asks a thread to revise or merge them. Below is an overview based on Anthropic's official documentation: what to configure, how the work is organized, and what limitations the beta has.

The beta is becoming available gradually, starting with Pro and Max accounts that have already used cloud Claude Code sessions and have not created a project in ordinary chat or Cowork. If you cannot see the Projects section yet, you can join the waitlist.

What is Claude Code Projects?#

A project is a single long-lived conversation with a coordinator, with repositories, memory, and instructions attached. You write to the coordinator, and it decides whether to respond immediately or launch a thread. You do not need to manually open a new session for each task.

A thread is a full cloud Claude Code session: it has its own context and repository branch and opens a pull request when needed. The coordinator can keep several threads open at once—for example, one fixes a bug, another writes tests, and a third updates documentation—while answering your questions in the main conversation.

For comparison, imagine several tabs with local Claude Code sessions, each in its own working copy of a repository. Such a copy is called a worktree—a separate folder for one branch, so local sessions do not interfere with each other. You switch between the sessions yourself and decide what to assign to each one. Cloud threads do not need a worktree: each thread clones the repositories into its own isolated cloud environment. Projects takes care of coordination, deciding when to create a new thread and when one is unnecessary.

A project has shared memory and instructions that each new thread receives. The setup section explains what to save in them and how they are passed to threads.

How this differs from an ordinary session and an agent team#

If you already run nested subagents within a single Claude Code session, it is worth distinguishing them from agent teams and project threads. An agent team is another way to delegate work: one session launches teammate sessions for a specific task. You can run it both on your own machine and inside a cloud session.

• Agent team—teammate sessions for one specific task that can be launched locally or in the cloud. These are not separate project threads.
• A project and its threads—the work runs in the cloud. Each thread is a separate session on its own branch and keeps running even after you close your laptop. A local session cannot be part of a project.
• Agent view—a screen for observing several local sessions on your machine. It has no coordinator: you decide what to assign to each one.

Anthropic's official documentation makes a separate point: parallel work alone is not a reason to create a project. In a project, Claude launches sessions and receives their reports itself, and all sessions start with shared repositories, instructions, and memory. The work remains in the cloud throughout the task.

A similar approach—a coordinator distributing tasks among agents—is implemented in another tool, covered in the article about Cursor Projects. The mechanism is different, but the coordinator also decides what to assign to whom.

What to configure before your first project#

Before creating a project, check three things.

1. GitHub account and Claude GitHub App. If you have already connected GitHub through /web-setup, that token gives your ordinary cloud sessions access to the repository. It is not enough for project threads: you need a connected GitHub account with push access to the repository and the Claude GitHub App installed for that repository. Without it, a thread can neither clone the repository nor open a pull request.

2. Project instructions. Project instructions is text of up to 16 000 characters sent to each new thread and to the coordinator itself. Put information here that you would otherwise have to explain again in every session: the repository structure, code conventions, and the checks required before a pull request.

3. Model and effort level. By default, a new project runs each thread on the Opus model with high effort, and the coordinator with low effort. The documentation says this setting “uses up your plan allowance fastest” (translation; original: draws on your plan fastest). If your tasks are straightforward, you can select a less costly model or lower the effort in Project settings > General. Thread and coordinator settings are changed separately; the documentation describes more economical options.

Project memory is stored as ordinary files, with an index file named MEMORY.md. Each new thread reads it at startup and accesses the other files as needed. Findings from one thread saved in memory become available to the next without needing to be retold.

What to do if threads change the same code#

Each thread works on its own branch and opens a pull request itself if the work requires one. But the coordinator does not guarantee that tasks will never overlap: if several threads end up in the same area of code, you can ask the relevant thread to resolve the conflict through the interface. There is a Resolve conflicts button next to its pull request that sends an instruction to the thread as a message from you.

The official documentation suggests specifying preferences for the number of threads in the project instructions: for example, ask the coordinator to launch no more than two threads at once or reuse an existing thread for new tasks in the same area. This is a preference that the coordinator tries to follow, rather than a hard limit. On its own, it does not guarantee that threads will not collide in the same file—an existing conflict must be resolved separately. For related tasks in the same area, you can reuse either an active or an idle thread. If it has been idle for more than an hour, it rereads the entire history when it receives a new message, which affects subscription allowance usage.

The more clearly tasks are separated by files or modules, the easier it is to work in parallel. A separate article covers dividing a large task into independent parts: how to delegate coding to thousands of agents. The scale is different there, but the principle of dividing the work is the same.

While the conversation cache remains active (on Pro and Max plans, within an hour, if your plan limits permit), a thread uses fewer tokens from the subscription allowance to reprocess its history. Once the cache expires, the thread rereads its entire history when it receives a new message before starting work. For a new independent task, it may be more economical to ask the coordinator to create a fresh thread: this can use fewer tokens from the same subscription allowance than continuing an old session with a large history after its cache has expired.

Beta limitations to know about in advance#

Before creating a project for an important task, check the beta's limitations:

• Available only on Pro and Max. Team and Enterprise are not yet supported.
• A limit of 200 new threads per day per account, across all projects combined.
• A project belongs to one user. You cannot give another person shared access to it or to an individual thread, and the beta has no organization settings for teams.
• Access only through claude.ai/code, the desktop app, and the mobile app. Projects does not work in the terminal CLI, through Amazon Bedrock, Google Cloud Agent Platform, or Microsoft Foundry.
• A project cannot see local files and tools. Threads work with GitHub repositories, uploaded files, and Google Drive folders, but not with things that exist only on your machine.

If you need terminal access or access to tools available only on your machine, use a local session or agent view for several such sessions. If several people need to work together in one workspace, Anthropic has a separate product for teams on Team and Enterprise: Claude Tag. It lives in a Slack channel; any member can give Claude a task, and everyone in the channel can see and direct the work. A project works differently: it belongs only to you. If you only need specific local files, you can upload them to the project, and each thread will then have access to them. This does not provide access to local tools.

What next#

Before moving your workflow to Projects, try creating one test project on a noncritical repository: connect the GitHub App, write short instructions, give the coordinator one independent task, and see how it handles it. This first run will show whether you understand the coordinator and thread interface. It does not address parallel work, conflicts, or allowance usage across multiple tasks—those need to be tested separately.