Let Claude coordinate ongoing work with Projects

Give Claude a body of related work in one conversation and let it coordinate parallel cloud sessions that share repositories, instructions, and memory.

A project is one ongoing conversation where Claude coordinates a stream of related work for you. You tell it what needs doing and it starts a thread for each task.

Each thread is usually a cloud session: Claude Code running in the cloud rather than on your machine. When a task needs something only your computer has, you can ask Claude to run that thread on your computer instead of in the cloud, through Remote Control. Threads run in parallel, and you can check on them and steer them from your phone. Cloud threads keep going after you close your laptop, while a thread on your computer runs only while that computer is awake.

Without a project, running several sessions means doing the coordinating yourself: you decide what each one works on, repeat the same background at the start of each, and check back to see which finished or needs an answer. With a project, you instead:

• Send work to one place: paste a bug report, a stack trace, or a list of tasks into the conversation whenever one comes up. Claude starts a thread for each piece of work or passes it to the thread already working in that area, and answers quick questions in place.
• Set context once: every new thread starts with the project's instructions, so a rule you state once, such as which branch to target, reaches all of them.
• Walk away and come back to finished work: when you come back an hour later or the next morning, the Overview pane shows which threads finished, which pull requests are ready for review, and which thread is waiting for your answer.

If you already know the work you want a project to run, go straight to Create a project.

When to use a project

A project is worth creating when the work has a goal that outlasts one session and keeps producing tasks. These kinds of work suit a project well:

• One goal across many repositories: "Bring every service up to the new lint config." Claude can run a thread per repository, each with its own pull request, and the Overview pane shows which ones are ready for review.
• An area you keep feeding: the bugs, stack traces, and review requests for one service, pasted into the conversation as they reach you. A pitfall you tell Claude to remember after one fix is in project memory for the next.
• A build or migration bigger than a session: "Build what docs/spec.md describes" or "Move the app off the deprecated ORM." The work splits into threads that each take a part, decisions you ask Claude to remember early on reach the later cloud threads, and the spec changes and bugs you find during the build go into the same conversation.
• Work that isn't code: a folder of contracts or a support-ticket export you keep coming back to with new questions, such as "find the ten most common integration mistakes in these tickets." Upload the documents instead of adding a repository, and threads deliver each write-up as a file on the project's Library tab.

In any of them you can send a batch of tasks, tell Claude to start without asking you to confirm, walk away, and find the threads that need you under Waiting on you when you're back, or ask Claude to put part of the work on a schedule as a routine. If one of these is your situation, create a project.

When something else fits better

A project still fits when only some tasks need your machine. Cloud threads work on GitHub repositories and on the files, folders, and Google Drive folders you upload to the project, and for the occasional task that needs a local database or a tool on your computer, you can ask Claude to run that task's thread on your computer. Something other than a project fits better in these cases:

• One task that fits in a session: "Fix the flaky login test." Start a cloud session yourself.
• Work where every task needs your machine: a local database, a device emulator, or an API behind your VPN. Use a local session, or agent view to run several at once. If the work only needs local files, upload them to the project instead.
• One task that repeats on a schedule with no conversation around it: "Post a dependency report every Monday." Create a routine on its own.
• Several people giving Claude work and steering it together in a Slack channel: see Claude Tag.

A project draws on the same plan limits as your other Claude Code sessions and uses them faster. Usage and cost covers what draws on your plan and how to keep it down.

How a project is organized

A project is one coordinating conversation with Claude plus the threads it starts to do the work. These are its parts:

• The project conversation: one long-running session where Claude acts as coordinator. It takes what you send, decides what becomes a thread, and keeps track of every thread it started. It sees what threads report back, not every step they take.
• Threads: the workers. Each is a separate session with its own context window that does one piece of work and reports back to the conversation when it finishes. A cloud thread works on its own branch and opens a pull request when the work calls for one.
• What every cloud thread starts with:
  • The project's repositories and files, plus its instructions and memory
  • The CLAUDE.md and skills in each of the project's repositories, and in a project with one repository, that repository's permission rules and hooks too
  • The connectors on your claude.ai account
  • A cloud environment that sets its network access, environment variables, API credentials, and installed tools
• The Overview pane: where you see all the threads at once and which of them need you. Its other tabs are Library for the files you added and the files threads produced, Pull requests for the ones threads opened, and Routines for scheduled work in the project.

Cloud threads don't pick up anything from the Claude Code setup on your own machine. Get skills, plugins, connectors, and tools into threads covers how to give them what they'd otherwise be missing.

Here is how those parts connect, from you through the conversation to the threads doing the work, with Overview tracking their state:

Create a project

You create and use projects at claude.ai/code, in the Code tab of the desktop app, or in the Claude mobile app for iOS and Android. In the browser and the desktop app there are two ways to start a project:

• From scratch, when you know the stream of work you want Claude to run: open the New project dialog and name it. Start a new project from scratch walks through the dialog.
• From a cloud session that's already doing the work: choose Continue as a project from that session's menu, and Claude proposes the project's setup from what the session was doing. See Start from an existing cloud session.

Either way, check the prerequisites first.

Check the prerequisites

Before you create a project, check your plan, your GitHub setup, and what the work needs to reach:

• Plan: you're on Pro or Max and Projects shows in your sidebar.
• GitHub, if the project will work on code: your code is on github.com rather than GitHub Enterprise Server, GitLab, or Bitbucket, your connected GitHub account has push access to it, and the Claude GitHub App is installed on it. If you connected GitHub with /web-setup, that token lets your other cloud sessions reach a repository but isn't enough for a project's cloud threads, which need the Claude GitHub App. Set up GitHub access has the steps.
• Network, credentials, and tools: for cloud threads, these come from the project's cloud environment. The default environment already reaches common package registries, so check this only if the work needs other domains, a secret, or a tool that isn't preinstalled. If the work needs an MCP server, check that it shows as connected in your claude.ai connectors.

Start a new project from scratch

Starting a project from scratch means opening the New project dialog, naming the stream of work, and optionally giving it a goal and the repositories and files it works on. Only the name is required, so you can create the project first and fill in the rest as the work takes shape.

The project is now listed under Projects in the sidebar, and its conversation is open. Your first batch covers what to set up before you send it work.

Start from an existing cloud session

If you already have a cloud session doing work that belongs in a project, open the session's menu in the sidebar and choose Continue as a project or Move to project:

• Continue as a project creates a new project named after the session and opens it. Claude reads the session and posts Setup recommendations in the conversation for you to confirm. The original session stays in your session list, and if it was in the middle of a turn it keeps running, so stop it yourself if you don't want both working at once. If you use the Set up project banner that can appear above a cloud session's message box instead, the result is the same, except that the session's running turn stops once the project opens.
• Move to project brings the session's work into an existing project. It posts a message in that project's conversation asking Claude to read the session and pick up where it left off, and new work continues in the project's own threads. The original session stays in your session list, unchanged.

Set up GitHub access

Most GitHub setup happens once, not per project. You connect your GitHub account to Claude once, and the Claude GitHub App is installed once per repository, or once for a whole GitHub organization if you give it all repositories. You come back to these steps when you add a repository the Claude GitHub App doesn't cover yet or one in a GitHub organization that enforces SSO.

When one of these steps is incomplete, the New project dialog and the project page name the missing step and link to where you finish it. Finish the step there, then click Check again if the dialog offers it. If a repository is still missing from the list afterward, open the Claude GitHub App's installation on GitHub, at github.com/settings/installations for a personal account, and confirm the repository is listed under Repository access. For the error messages a thread or the project reports when access is still wrong, see Repository access errors.

Work in a project

Give Claude work through the project conversation: tasks one at a time or several at once, plus updates and loose thoughts as they come up. Claude routes each message, and threads do the work and report back.

Your first batch

Before you send a new project a batch of work, set it up so the first threads come back the way you want:

1. Write project instructions: the brief every thread starts from, such as which branch to target, how a thread checks its work, and what needs your go-ahead.
2. Send one small piece of the real work, or start one of the threads Claude suggested if it offered any, and open the thread when it finishes to see how it reports back and what it did on its branch. If it assumed something wrong or couldn't reach what it needed, Threads guessed or stalled instead of asking covers where to fix that.
3. Check Thread model and Thread effort in Project settings > General. A new project runs every thread on Opus at high effort, which draws on your plan fastest; Choose models and let Claude manage context covers the alternatives.
4. Ask Claude to propose threads before starting them and to run a few at a time, and drop those limits once a few threads come back the way you want.

Send work and read results

Claude decides where each message you send in the conversation goes:

• A quick question usually gets an answer in the conversation.
• New work goes to a new thread or to a thread already working in that area, and Claude tells you which. Each new thread shows up under your message as a card: a box with the thread's title and status, which you click to open the thread.
• Several unrelated tasks in one message become separate threads.

If Claude routes something differently than you wanted, say so. Tune how Claude runs a project lists things you can tell it, such as reusing an existing thread for follow-ups or answering in place instead of starting a thread.

A thread's full results stay in the thread, and you open its card in the conversation to read them. Files a thread produced are also on the Library tab in Overview.

Sometimes Claude proposes threads instead of starting them, in a Suggested threads list. Click the arrow on a suggestion to start that thread. When several are listed, a button under the list starts all of them.

Review a thread's pull request

When a cloud thread changes code, this is what it does unless you tell it otherwise:

• Branch: works on a new branch, started from the repository's default branch.
• Pull request: opens one when you ask, and can open one on its own for a bug fix or another concrete change.
• After it opens: watches the pull request with auto-fix turned on, whether or not auto-fix is on for your other cloud sessions. It pushes fixes when CI fails, addresses review comments, and replies in the thread when checks pass and the pull request is ready for you.

When a thread has pushed a branch or opened a pull request, its card in the conversation can show a button for the next step:

• Resolve conflicts, Fix CI, Address comments, and Merge it send that instruction to the thread as a message from you, so you can prompt the thread yourself instead of waiting for it to react to the pull request.
• Review PR opens the pull request on GitHub.
• Create PR appears when an idle thread has pushed a branch but hasn't opened a pull request. Clicking it creates the pull request from that branch directly rather than sending the thread an instruction to open one.

To change when threads open pull requests, for example only when you ask, or which branch they start from, say so in the task or in project instructions.

See what needs you in Overview

The Overview pane beside the conversation tracks the project's threads. It's already open the first time you open a new project. The Overview button in the project header closes and reopens it, and shows a dot when a thread is waiting on you.

In the desktop app, you also get a desktop notification when Claude posts in the conversation, a thread hits an error, or a thread needs your input, so you don't have to keep the project open to find out. To also get one each time a thread finishes a turn, or to turn them off for a project, choose Notifications in the project's sidebar menu. These notifications are desktop-only: in a browser, check the dot on the Overview button.

The pane's Threads tab groups threads by state:

The pane's other tabs are Library for the files and folders you added and the files threads produced, Pull requests once threads have opened any, and Routines for the routines Claude set up from this project.

Open a thread when you need control

Click a thread's card in the conversation or its row in Overview to open its transcript in the Overview pane. From there you can:

• Read what Claude did, step by step.
• Steer the task by writing in the thread's own message box. A message there goes straight to that thread, while a follow-up in the project conversation reaches it only when Claude matches the follow-up to that thread.
• Answer a permission prompt the thread is waiting on.
• Interrupt the thread with Stop, which replaces the send button while the thread is working, or by pressing Esc.

Choose models and let Claude manage context

Set models and effort in Project settings > General. A new project runs Opus everywhere, with high effort for threads and low effort for the conversation:

• Thread model and Thread effort apply to threads. To use a different model for one task, ask for it in the task; for a thread already running, use that thread's model picker.
• Coordinator model and Coordinator effort apply to Claude in the project conversation.

You don't manage context windows in a project. Threads compact automatically, and the conversation works from recent messages, recent threads, and project memory rather than its full history, so it keeps going for as long as the project runs. Put anything that must never be dropped in project memory. If one thread outgrows its context, it shows Claude ran out of context on this turn.

Tune how Claude runs a project

Tell Claude in the conversation how many threads to run at once, when to post updates, and when to open pull requests. If Claude is coordinating in a way you don't want, say so. For example, you can say:

• "Propose threads and wait for my go-ahead before starting them" or "Start these now without asking me to confirm"
• "Run at most two threads at a time" or "Reuse an existing thread for follow-ups in the same area"
• "Post shorter updates" or "Only post when something finishes or is blocked"
• "Give me a status update on every thread"
• "Do this task with a smaller model"
• "Don't open a pull request until I've seen the plan"
• "Tell me what's wrong in these repositories and don't fix anything yet", when you want to go through the findings before any of them becomes a thread
• "Answer that here instead of starting a thread", when Claude starts a thread for something you meant as a quick question

Claude saves preferences like these to project memory on its own and follows them in later cloud threads. They're instructions Claude keeps to, not enforced settings, so a thread limit you give this way isn't a hard cap. Add one to project instructions when you want it worded exactly and applied to every thread from the start.

Unblock a thread waiting on approval

Threads run in auto mode when the thread's model supports it, so most tool calls run without asking you. When a thread needs your approval, the prompt is inside that thread and the thread waits until you answer it there. Telling Claude in the project conversation to go ahead doesn't reach it.

Each approval covers that prompt, or the rest of that thread if you choose the broader option. To let every thread run certain commands without asking, or to block some, add permission rules to the repository's .claude/settings.json. Cloud threads apply them only in a project with one repository; see What threads pick up from your repositories.

Run a thread on your own computer

When a task needs something only your computer has, such as a local database, a device emulator, or an API behind your VPN, ask Claude to run the thread for that task on your computer instead of in the cloud. When you ask in the project conversation, the thread is a Claude Code session in a folder on your machine, connected through Remote Control. The project's other threads keep running in the cloud. Compared with a cloud thread, a thread on your computer:

• Works with the files, tools, MCP servers, and Claude Code settings on that machine instead of the project's cloud environment
• Starts with the project's instructions, but not with its memory files loaded
• Runs only while that computer is awake with Remote Control turned on

The thread runs in auto mode, so Claude runs commands and edits files in that folder without asking you each time. If auto mode is unavailable or turned off in that computer's Claude Code, the thread runs without it, and any permission prompt it raises waits for your answer in the thread, as Unblock a thread waiting on approval describes.

While the thread runs, a laptop icon in its header shows whether your computer is connected. Click it to see which folder the thread is using or to turn the connection off. The thread pauses while that computer is asleep, and stops if the desktop app or claude remote-control quits. Lost contact with your folder covers getting it going again. In the desktop app, turn on Keep this computer awake for Remote Control under Settings > Claude Code to stop the computer from sleeping on its own.

A project can't run a thread on your computer while Require trusted devices is on for your account.

Give a project standing context

Project memory, project instructions, and the project's repositories, files, and environment carry context across threads. You set each one once.

Project settings > Memory lists these files under Auto memory, because Claude writes them itself as it works in the project. They're separate from the auto memory Claude Code keeps on your machine, even though both use a MEMORY.md index. Project memory is also separate from the CLAUDE.md files in the project's repositories. Each cloud thread still reads those CLAUDE.md files from its clone when it starts, so put instructions about a repository in its CLAUDE.md and notes about the project in project memory.

Write project instructions

Project instructions are the brief every new thread starts from. Click the gear icon in the project header to open Project settings, then go to Memory > Project instructions. A useful brief covers:

• What the project is for
• Where the work happens: which repositories, which branch to start from, how to name pull requests
• How a thread checks its own work before calling it done
• What to do when something it needs is missing
• What needs your go-ahead first

For example:

This project holds p95 latency for the payments API under 200 ms: profiling, query and caching fixes, and the dependency upgrades that come with them, in the payments-api repository.

- Branch from main and open one draft pull request per thread.
- Before you call work done, run `make test` and `make lint` and paste the summary lines in your final message.
- If you can't reach something you need, such as a repository, a secret, an API, or a connector, say exactly what's missing in your first message and stop. Don't substitute, mock, or guess.
- Don't merge, force-push, or change CI configuration without asking me in the thread.

Rules about one repository, such as its build commands, belong in that repository's CLAUDE.md, which every cloud thread reads when the repository is part of the project. Once work is underway, when you correct a thread, also tell Claude to remember the correction: it goes into project memory and later cloud threads start with it.

Decide which repositories to add

The repositories you add to a project come with everything in them, their code, CLAUDE.md, and skills, in every cloud thread. Repositories you don't add are still within reach: a cloud thread can add one to itself when its task needs it. Most projects use both:

• Add it to the project, in the New project dialog, in Project settings > Environment, or by asking Claude in the conversation to add it to the project. Every cloud thread from then on clones it and starts with its CLAUDE.md and skills loaded, whether or not the task touches it. Going from one repository to several also changes what threads take from each repository's .claude/settings.json; see What threads pick up from your repositories.
• Leave it off and let threads add it when needed. A cloud thread whose task needs a repository the project doesn't have can add it to itself, and a note in the thread says it was added to this thread only. The clone happens partway through the task, so that repository's CLAUDE.md and skills weren't there when the thread started. The next thread starts without it. A repository added this way needs the same prerequisites as a project repository: the Claude GitHub App installed on it and push access from your GitHub account.

A project doesn't need a repository at all. Its cloud threads can still research, write documents, and write and run code in their own sandbox, and they deliver files to the Library tab. Any of its cloud threads can still add a repository to itself when a task calls for one.

Once the project has repositories, Claude can only add repositories from a GitHub owner the project already uses, whether it adds one to the project or a thread adds one to itself. To bring in a repository from a different owner, add it to the project yourself in Project settings > Environment.

For a project that spans many repositories, such as one feature with server, web, mobile, and desktop code, add the one or two repositories nearly every task touches and name the others in project instructions so Claude knows where the rest of the code lives. Cloud threads then start small and pull in the other repositories only for the tasks that need them.

What threads pick up from your repositories

Each cloud thread clones every repository in the project and loads CLAUDE.md and skills from all of them. Permission rules, hooks, and env come only from the .claude/settings.json in the directory the thread starts in: inside the repository when the project has one, and above the clones when it has several, where no repository's file is read for them.

In a project with several repositories, each clone is attached to the thread as an additional directory with CLAUDE.md loading turned on, which is why every repository's CLAUDE.md and skills load at start even though the thread starts above them. In such a project, put standing rules in project instructions and give threads environment variables through the cloud environment.

Choose an environment for threads

Every new cloud thread starts in the project's cloud environment. The environment sets which domains threads can reach, which environment variables they have, which API credentials are added to their requests, and what the setup script installs before Claude starts. Cloud threads use a default Anthropic-hosted environment until you pick one in Project settings > Environment.

If cloud threads need to reach an internal API or a private package registry, or need a token your machine normally holds, change the environment rather than the project: see Network access, Add API credentials, and Setup scripts.

Get skills, plugins, connectors, and tools into threads

Cloud threads don't have the skills, MCP servers, plugins, and tools installed only on your machine. A thread that Claude runs on your machine through Remote Control uses what's installed there. To make each of these available to cloud threads:

• Skills, subagents, and commands: commit them to a repository you added to the project, for example a skill at .claude/skills/<skill-name>/SKILL.md. Each cloud thread clones every repository in the project and loads .claude/skills/, .claude/agents/, and .claude/commands/ from each of them, so a skill committed to one repository is available in every cloud thread. Cloud threads also load the skills you enable for your claude.ai account.
• Plugins: add them in Project settings > Plugins; they load into each new cloud thread. Plugins that a repository declares in its .claude/settings.json don't load in cloud threads.
• MCP servers: cloud threads get their MCP tools from the connectors on your claude.ai account, which are MCP servers you connect once at claude.ai/customize/connectors or through the Manage connectors link in Project settings > Environment. Every cloud thread can use all of them with no per-project setup. The project conversation itself has no connectors, so send work that needs one as a task for a cloud thread. In a project with one repository, cloud threads also load MCP servers from that repository's .mcp.json. How connectors reach Claude Code lists the rules for cloud sessions and the settings that turn connectors off.
• Command-line tools and packages: install them in the environment's setup script.

To see which connectors a running cloud thread has at claude.ai/code, open the thread and select Connectors from the + menu beside its message box. Turning a connector off there removes it from that thread and saves that as your account default, so new threads and claude.ai chats start without it until you turn it back on. A cloud thread picks up a connector you add or reconnect after the next message you send it.

Project settings reference

You change project settings at claude.ai/code or in the desktop app, not in settings.json. Open Project settings from Settings in the project's sidebar menu or from the gear icon in the project header.

Settings save as you change them; a text field you're editing, such as the goal or instructions, shows Save changes and Discard until you leave it. Changes to instructions, repositories, plugins, and environment in Project settings reach new threads, not threads already running.

Pause, archive, or delete a project

All three controls are at the bottom of Project settings > General:

• Pause: stops everything at once. Every running thread and the conversation are interrupted, no new threads start, routines don't run, and the project doesn't accept messages until you resume it. Click Resume in the same place or on the banner above the project's message box; a paused thread continues when you send it a message after that.
• Archive: hides the project from the sidebar and archives its threads, which stops any thread that was running or watching a pull request. Routines in the project don't run while it's archived. To bring the project back, open it from the Projects page and click Unarchive. Its threads stay archived until you unarchive them individually from the session list.
• Delete: permanently removes the project along with its threads, its memory, and its files, and turns off the project's routines. This can't be undone. Branches and pull requests the threads pushed to GitHub aren't affected.

Usage and cost

Project usage counts against the same plan limits as your other Claude Code sessions, and a project can't spend past those limits on its own.

A thread that reaches your plan's limit waits and continues on its own when the limit resets, so work you left running starts using your next usage window without a message from you. A thread hit the usage limit covers what you see, how to stop it, and the one case that doesn't wait.

Work goes past your plan's limits only if you have turned on usage credits for your account. A thread can't turn them on for you.

What draws on your plan

A project uses your limits faster than a single session does, and on a Pro plan in particular you should expect to reach your limit sooner on days you run one. These are the parts of a project that use your plan:

• Running threads: each is a full session, and several can run at once. There's no fixed number; Claude starts as many as the work calls for, and a limit you ask for is a preference rather than a cap. The enforced limit is 200 new threads per day across your projects.
• The conversation: Claude uses tokens of its own reading what threads report and deciding what to do next.
• Threads watching a pull request: an idle thread wakes up and uses your plan again when CI fails or a review comment arrives on its pull request. To stop that, ask in the thread for it to stop watching the pull request.

A project with no running threads, no watched pull requests, and no new messages doesn't use your plan while it sits idle, and neither does an archived project.

See and reduce a project's usage

Open Usage in Project settings to see token use by thread and by model, and how much went to the project conversation. To bring it down:

• A follow-up routed to a thread that has been idle longer than the cache lifetime, an hour on Pro and Max within your plan's limits, re-reads that thread's whole conversation before doing anything. For new work, asking Claude to start a fresh thread can use less than reviving a large old one.
• For work that doesn't need the largest model, choose a smaller model or a lower effort level for threads, the conversation, or both.
• Ask Claude in the project conversation to run fewer threads at a time, or to answer small questions itself instead of starting a thread.

How projects relate to other Claude Code features

Several Claude Code features let more than one session work at the same time, so running work in parallel is not by itself what a project is for. In a project, Claude starts and tracks the sessions instead of you, and each one starts from the same instructions. This is how each neighboring feature connects to a project:

• Claude Tag: Claude Tag is Claude in your team's Slack channels, on Team and Enterprise plans. Anyone in a channel can give it work, everyone in the channel sees and steers it, and it uses connections an admin set up for that channel. A project is yours alone: you're the only one who sends it work or sees its threads, it uses your own GitHub access and connectors, and it's on Pro and Max. How Claude Tag differs from Cowork and Claude Code has the side-by-side.
• Cloud sessions: every thread is a cloud session unless you ask Claude to run it on your machine. Either way, Claude starts and tracks it instead of you. A cloud session you started yourself can become a project or feed one through Continue as a project or Move to project.
• Routines: when you ask for scheduled work in a project, Claude creates a routine that runs as threads in that project and appears on its Routines tab. Routines you create outside a project keep working on their own.
• Remote Control: Remote Control connects claude.ai to a Claude Code session running on your machine. When you ask Claude in a project to run a thread on your computer, the project uses Remote Control to do it.
• Local sessions and agent view: a session you start yourself in your terminal, IDE, or the desktop app's local environment can't be added to a project. Agent view is a screen for tracking several local sessions side by side, and you still start each one and give it its task yourself.
• Worktrees: a worktree gives each local session its own working copy of a repository so parallel sessions on your machine don't overwrite each other. Cloud threads don't need them: each clones its repositories into its own cloud sandbox and works on its own branch.
• Agent teams: an agent team is one session that starts teammate sessions for a single task, on your machine or inside a cloud session, and ends with that task.
• Projects in claude.ai chat and Cowork: the earlier Projects experience, which groups conversations and reference files without threads or a coordinator. Those projects keep working as they do today until the redesigned experience reaches them.

Run agents in parallel compares these options side by side.

Limitations

• Projects are available at claude.ai/code, in the desktop app, and in the Claude mobile app, not in the terminal CLI or through Amazon Bedrock, Google Cloud's Agent Platform, or Microsoft Foundry. The CLI's claude project command, which manages local Claude Code state for a directory, is unrelated.
• Project threads are cloud sessions, or sessions on your own machine through Remote Control, with Anthropic as the model provider in both cases. Security and Data usage cover how cloud sessions are isolated and what's retained, and Connection and security covers how a thread on your machine connects and what's stored.
• You can't add a session you started yourself on your machine to a project. A project reaches your machine only by running a thread there through Remote Control, and that section lists what it needs.
• A cloud thread's sandbox pauses between turns and resumes when the thread continues. If the sandbox can't be resumed, the thread continues from a fresh clone, so uncommitted changes can be lost. On long tasks, ask Claude to commit and push work in progress.
• A project belongs to one user. You can't share a project or its threads with another user, and thread transcripts don't have the share option other cloud sessions have. There are no organization-level controls for projects during the beta.
• A thread belongs to the one project that started it. You can't move or copy a thread to another project, or move it out to stand alone. Move to project goes the other way only: it brings a cloud session's work into a project.

Troubleshooting

For the GitHub setup prompts in the New project dialog, see Set up GitHub access.

A thread looks stuck

Claude doesn't post each step a thread takes, so a thread that shows as running with no new messages in the project conversation is usually still working. A new cloud thread also provisions its cloud environment before Claude begins, so its first update takes a moment. Open the thread to read its transcript. If the thread is waiting on a permission prompt, answer it there.

Threads guessed or stalled instead of asking

When several threads come back having assumed something wrong, worked around missing access, or stopped with "blocked", the cause is usually the same gap in the project's setup rather than a problem with each task. Sort out which threads are sound before you fix anything:

1. Ask Claude in the conversation: "For every open thread, list what you asked it to do, what it assumed or couldn't reach, and what it's waiting on." Claude reads each thread and answers in the conversation.
2. For threads that started from a wrong assumption, open the thread from Overview and mark it resolved from its menu, or tell it what to do instead in its message box. Its branch and any pull request stay on GitHub until you delete them.
3. Fix the gap once, in project instructions or the environment, then send one thread before sending the rest of the work again as new threads.

Claude hasn't responded

The project conversation shows a "Claude hasn't responded" banner when Claude is running but its replies aren't reaching the project. Click Restart Claude on the banner, or go to Project settings > General and click Restart in the Restart Claude row. Claude reconnects to the conversation; any reply it was in the middle of writing is lost, and threads aren't affected.

Repository access errors

Three messages mean a thread or the project can't reach one of its repositories. A project's cloud threads need the GitHub prerequisites even when your other cloud sessions clone the same repository without trouble.

• "Couldn't start the session — Claude doesn't have GitHub access to this project's repository", reported before the thread starts, when the Claude GitHub App isn't installed on that repository, is suspended, or isn't linked to the GitHub account you connected.
• "Unable to access your repository", reported by a thread when its clone fails: GitHub rejected the clone, the repository wasn't found under the name the project has, or the branch the thread was asked to start from doesn't exist.
• "Claude can't access" a repository, shown when you save repositories in the New project dialog or Project settings. The message continues with an install link and a reconnect link. Use the install link if the Claude GitHub App isn't on that repository, and the reconnect link if it is, since the GitHub App can be installed on GitHub without being linked to the account you connected to Claude. If the message says the GitHub App is suspended or doesn't include this repository, follow its link to GitHub to fix that.

To fix any of them, click the button the message offers, such as Install GitHub App or Select repositories on GitHub, then Check again. When the block is on the GitHub organization's side, such as an owner who hasn't approved the app or an IP allow list that excludes Claude, the message shows a See how to fix link instead. If there's no button, follow Set up GitHub access, then send another message to retry.

A thread hit the usage limit

When a thread or the project conversation reaches your plan's five-hour or weekly limit, it keeps retrying on its own and continues when the limit resets. While it waits, the thread shows Service is busy with "Claude is still retrying and will continue automatically." You don't need to do anything for the work to continue. If you'd rather it not use your next usage window, click Stop in the thread, or pause the project to hold every thread. A thread that a routine started doesn't wait: its turn stops with a limit error, and you send it a message after the limit resets.

Usage limit errors explain the limits and when they reset.

Additional usage credits are required

A thread or the project conversation made a request your plan covers only with usage credits, such as one to a model or context size your plan doesn't include, and usage credits aren't turned on for your account. Add usage credits to your subscription covers who can turn them on or buy them on each plan. Once credits are available, send another message to retry.

Lost contact with your folder

A thread running on your computer shows this when the Claude Code session there stopped responding, usually because the computer went to sleep or the desktop app or claude remote-control quit. Wake the computer, and if the desktop app or claude remote-control is no longer running there, start it again: reopen the app and confirm Use this computer from your phone and claude.ai is still on under Settings > Claude Code, or run claude remote-control again in the same folder.

Other messages

These messages name their own cause. The table gives the next step for each.

Related resources

• Use Claude Code in the cloud: how the cloud sessions behind each cloud thread work, including GitHub access options and auto-fix on pull requests
• Configure cloud environments: change what cloud threads can reach on the network, give them environment variables and API credentials, and install tools with a setup script
• Automate work with routines: schedules, triggers, and management for routines, including the ones Claude creates from a project
• Manage multiple agents with agent view: run and track several sessions on your own machine when the work needs tools or services only your machine can reach
• Projects redesigned: from folder to conversation: the launch announcement, with the thinking behind making a project a conversation with Claude