Claude Code Projects: how the feature works and when to use it

Claude Code Projects is a public beta, on Pro and Max plans only, in which one ongoing conversation at claude.ai/code, the desktop app or the Claude mobile app hands each task to a separate session called a thread. Threads usually run in the cloud on their own branch, start from shared project instructions and memory, and report back to the conversation. Cloud threads keep going after you close your laptop. It does not run in the terminal CLI or IDE extensions, uses your plan limits faster than a single session, and suits a stream of related tasks over days rather than one job.

Which "projects" this is

Three different things in Anthropic's products are called projects, and search results mix them up:

• Claude Code Projects, covered here: a coordinating conversation that starts and tracks cloud sessions for you. Anthropic announced it on September 17, 2026, and the documentation still describes it as a public beta that is rolling out gradually.
• Projects in claude.ai chat and Cowork: the older feature that groups conversations and reference files, with no threads or coordinator. According to the docs, those keep working as they do today until the redesigned experience reaches them.
• ~/.claude/projects/: the folder where the Claude Code CLI keeps local session transcripts, one subfolder per working directory. It has nothing to do with the feature.

Who can use it today

Projects are offered on Pro and Max, not on Team or Enterprise yet, and the rollout started with accounts that had used cloud sessions and had no existing projects in claude.ai chat or Cowork. If Projects is not in the sidebar at claude.ai/code or in the desktop app's Code tab, look under More; if it is missing there too, the rollout has not reached your account and Anthropic offers a waitlist. If the Projects page shows Get started instead of New project, you first upgrade or archive the existing claude.ai projects it lists.

For a project that works on code, three things have to be in place before threads can clone anything:

1. The code is on github.com. GitHub Enterprise Server, GitLab and Bitbucket are not supported for projects.
2. Your connected GitHub account has push access to each repository.
3. The Claude GitHub App is installed on each repository. A token set up with /web-setup lets your other cloud sessions reach a repository, but project threads need the app.

Projects are not available in the terminal CLI, the VS Code extension or the JetBrains plugin, or through Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry.

A project is a coordinator plus threads

You talk to one long-running conversation. When you paste a bug report or a list of tasks, Claude decides what happens to each piece: a quick question gets an answer in place, new work becomes a new thread or goes to a thread already working in that area, and several unrelated tasks in one message become separate threads. The coordinator sees what threads report back, not every step they take.

Each thread is a full session with its own context window. When a cloud thread changes code, by default it works on a new branch from the repository's default branch, opens a pull request when you ask (or on its own for a concrete fix), and then watches that pull request with auto-fix on, pushing fixes when CI fails and answering review comments.

The Overview pane beside the conversation is where you see the state of everything:

The desktop app also sends a notification when a thread errors or needs your input. In a browser you only get a dot on the Overview button. A permission prompt lives inside its thread: telling the coordinator to go ahead does not answer it, so open the thread and approve there.

Several repositories: add the core ones, let threads pull the rest

Multi-repository work is one of the cases the docs recommend a project for, such as bringing every service up to a new lint config with one thread and one pull request per repository. Repositories you add to the project are cloned by every cloud thread, whether or not the task touches them. A thread whose task needs another repository can add it to itself partway through, which means that repository's CLAUDE.md was not loaded at the start.

The docs' advice is to add the one or two repositories nearly every task touches and name the others in project instructions, so threads start small. Claude can only add repositories from a GitHub owner the project already uses. To bring in a repository from a different user or organization, add it yourself in Project settings > Environment.

Your local Claude Code setup does not come with you

A cloud thread starts with the project's repositories and uploaded files, its instructions and memory, the connectors on your claude.ai account and the project's cloud environment. From each repository it reads only part of what a local session would:

Standing context is set in two places. Project instructions (up to 16,000 characters, under Project settings > Memory) are sent to every new thread: which branch to start from, how a thread checks its work, what needs your go-ahead. Project memory is a set of files with a MEMORY.md index that Claude writes as it works and when you ask it to remember a decision or a pitfall, and every cloud thread reads that index when it starts. Rules about one repository still belong in that repository's CLAUDE.md. Changes to instructions, repositories and environment reach new threads, not running ones.

Running a thread on your own computer

When a task needs a local database, a device emulator or an API behind your VPN, you can ask the project to run that one thread on your computer through Remote Control. Make the folder available first, with Claude Code v2.1.280 or later on that machine, in one of two ways:

• In the desktop app, turn on Use this computer from your phone and claude.ai under Settings > Claude Code and add the folder.
• In a terminal, run Remote Control in the folder and leave it running. In a git repository, add --spawn worktree to give each thread its own git worktree instead of the folder itself:

cd ~/code/payments-api
claude remote-control --spawn worktree

Then choose Work locally from the + menu in the project conversation and allow the folder on the card Claude shows. A local thread uses that machine's files, tools, MCP servers, hooks and permission rules. It starts with the project's instructions but not its memory files, pauses while the computer sleeps, and stops if the desktop app or claude remote-control quits. A project cannot run a thread on your computer while Require trusted devices is on for your account.

It uses your plan faster than one session

Projects count against the same plan limits as the rest of Claude Code and cannot go past them unless you have turned on usage credits. Three things use your plan faster:

• A new project runs threads on Opus at high effort, and the coordinator on Opus at low effort. Change both under Project settings > General if the work does not need them.
• Claude starts as many threads as the work calls for. Saying "run at most two threads at a time" is saved as a preference, not enforced as a cap. The enforced limit is 200 new threads per day across your projects.
• An idle thread watching a pull request wakes up and uses your plan whenever CI fails or a review comment arrives.

A thread that hits your five-hour or weekly limit retries and continues when the limit resets, so work you left running will start using your next window. The exception is a thread started by a scheduled task, which stops with a limit error. Project settings > Usage breaks down token use by thread and model. A project with nothing running, nothing watched and no new messages uses nothing.

When something else fits better

A project is the wrong tool in these cases:

• One task that fits in a session. Start a single cloud session.
• Every task needs your machine. Use local sessions, or agent view (claude agents, a research preview) to dispatch and watch several background sessions at once.
• Your code is on GitHub Enterprise Server, GitLab or Bitbucket. Project threads cannot clone it, though a project can still work on files you upload.
• You are on a Team or Enterprise plan. Projects are not offered there yet.
• One task repeats on a schedule with no conversation around it. Create a cloud scheduled task on its own.
• You need to share the work. A project belongs to one user and cannot be shared.

Two more limitations matter for planning. A session you started yourself on your machine cannot be added to a project; to continue its work there, push its branch, add the repository to the project and name the branch in the task. And a cloud sandbox that cannot be resumed continues from a fresh clone, so ask long-running threads to commit and push work in progress. For running local sessions side by side in different repositories, the guide to Claude Code across multiple projects covers terminal tabs, tmux, agent view and the desktop app, and running several Claude Code agents at once covers worktrees and review load.

For local work across several projects: Armadai

If your work is the opposite of what Projects is built for (several separate project folders on your Mac, each needing its local dev server or other local tools, and you want to see all of them at once), that is the case Armadai addresses. Armadai is a native macOS app that turns each project folder into a workspace on one infinite canvas, with its own agents, terminals, code, browser, notes and tasks, and it runs Claude Code, Codex, Grok and Cursor with your own accounts. A master agent can open workspaces, launch and message agents and read their replies, and the sidebar shows which agent is working, idle or waiting across projects so you can approve many requests from the sidebar without leaving the workspace you are in. Its task hand-off gives each run its own Git worktree and brings successful work back as a draft pull request for review.

Armadai's agents run on your Mac, so unlike cloud threads they stop when you shut down or log out, and when you quit the app unless its background session helper is on. Armadai needs macOS 14 or later on Apple Silicon and Intel Macs. It costs $20 a month or $120 a year after a 7-day free trial that needs no card. Armadai has no free plan; pricing has the details. Your Claude plan limits apply to the agents inside it as they do anywhere else.