Projects

A project is one long-running conversation in which Claude acts as a coordinator. You drop work into it as it turns up (a bug report, a stack trace, a list of chores) and Claude starts a thread for each piece. Threads run in parallel, usually as cloud sessions, and report back to the conversation when they are done.

Note: Projects are in public beta on Pro and Max and rolling out gradually, first to accounts that have used cloud sessions and have no existing projects in claude.ai chat or Cowork. They are not yet available on Team or Enterprise. If Projects is missing from the sidebar at claude.ai/code or the desktop app's Code tab, the rollout has not reached you; you can join the waitlist. Meanwhile, agents lists alternatives.

Without a project, running several sessions means coordinating them yourself: deciding who does what, pasting the same background into each one, and checking which ones are finished or stuck. With a project you:

• Send everything to one place. Claude decides whether a message is a quick question to answer in place, new work for a new thread, or a follow-up for a thread already working in that area.
• State context once. Every new thread starts with the project's instructions, so "branch from develop" reaches all of them.
• Come back to results. The Overview pane shows what finished, which pull requests are ready, and which thread is waiting on you.

Cloud threads keep running after you close your laptop. When a task needs something only your computer has, you can ask for that one thread to run on your machine through Remote Control. You can check on and steer everything from your phone.

When a project makes sense

Create a project when the work has a goal that outlives a single session and keeps generating tasks:

• One goal across many repositories. "Move every service to the new logging library." One thread per repo, one pull request each, all visible in Overview.
• An area you keep feeding. Bugs and review requests for one service, pasted as they arrive. A pitfall you ask Claude to remember after one fix is waiting in project memory for the next.
• A build or migration bigger than a session. "Build what docs/spec.md describes." The work splits into threads, early decisions carry forward, and spec changes land in the same conversation.
• Non-code work. A folder of contracts or an export of support tickets you keep asking new questions of. Upload the files instead of adding a repo, and threads deliver write-ups as files on the Library tab.

You can send a batch, tell Claude to start without confirming, walk away, and later look under Waiting on you. You can also ask Claude to put part of the work on a schedule as a routine.

When something else fits better

Projects draw on the same plan limits as everything else and use them faster; see usage and cost.

How a project is put together

• The project conversation. Claude as coordinator: it receives your messages, decides what becomes a thread and tracks every thread. It sees what threads report, not every step they take.
• Threads. The workers. Each is a separate session with its own context window. A cloud thread works on its own branch and opens a pull request when appropriate.
• What every cloud thread starts with: the project's repositories and files, its instructions and memory, the CLAUDE.md and skills from each project repository (and, in a one-repo project, that repo's permission rules and hooks), the connectors on your claude.ai account, and a cloud environment that defines network access, environment variables, network secrets and installed tools.
• Overview. The Threads tab shows every thread by state; Library holds files you added and files threads produced; Pull requests lists those threads opened; Routines shows scheduled work.

Cloud threads do not inherit anything from the Claude Code setup on your own machine. Getting your tools into threads explains how to fill the gaps.

Creating a project

Projects live at claude.ai/code, in the desktop app's Code tab, and in the Claude mobile app. In the browser and desktop app you can start one from scratch or from an existing cloud session.

Prerequisites

• Plan: Pro or Max, with Projects in your sidebar.
• GitHub (for code work): the code must be on github.com (not GitHub Enterprise Server, GitLab or Bitbucket), your connected GitHub account needs push access, and the Claude GitHub App must be installed on the repository. A token from /web-setup is enough for other cloud sessions but not for project threads, which need the GitHub App.
• Network, secrets and tools: these come from the cloud environment. The default already reaches common package registries; check this only if you need other domains, a secret or a tool that is not preinstalled. If you need an MCP server, make sure it shows as connected in your claude.ai connectors.

From scratch

1. Select Projects in the sidebar, then New project (or go to claude.ai/code/projects/browse).
2. Fill in the dialog. Scope it to one stream of work, such as "everything to keep the search API under its latency budget".
   • Name (required): how it appears in the list.
   • Goal (optional): one line, like "Keep p95 search latency under 300 ms". Claude works towards it. You can add or change it later in Project settings > General.
   • Context (optional): GitHub repositories, plus files, folders or Google Drive folders threads should read. Add the repos most tasks need, not every one that might come up. More can be added later in Project settings > Environment.
3. Click Create project. The conversation opens.

Standing rules for threads go into project instructions after the project exists.

On your very first project, Claude takes a turn of its own straight away (using your plan) unless you message first. It may start one read-only thread that explores a repository and suggests next steps, or post Setup recommendations based on your recent cloud sessions: repositories to add, routines to create and threads to start. Recommended items start switched on; switch off what you do not want and click Update setup, or ignore them.

From an existing cloud session

Open the session's menu in the sidebar:

• Continue as project creates a new project named after the session. Claude reads the session and posts setup recommendations. The original session stays in your list and, if mid-turn, keeps running, so stop it if you do not want both working. The Set up project banner that can appear above a cloud session's message box does the same but stops the session's running turn once the project opens.
• Move to project sends the work into an existing project by posting a message asking Claude to read the session and carry on. The original stays unchanged.

Local sessions have neither option. Describe the work in the project conversation instead, or push the branch, add the repo and name the branch in your task.

GitHub access

This is mostly a one-off setup:

1. Connect GitHub to Claude (your first visit to claude.ai/code walks you through it; see web quickstart).
2. Install the Claude GitHub App on the repos the project needs. For an organisation-owned repo, only an organisation owner can complete the install; otherwise GitHub sends the owner a request and the project waits for approval.
3. Authorise SSO if the organisation enforces SAML: reconnect GitHub and authorise the Claude app for that organisation, or its private repos will not appear in the dialogs.

If something is missing, the dialog names the step and links to it; finish it and click Check again. If a repo is still absent, check Repository access on the app's installation page on GitHub (github.com/settings/installations for a personal account).

Working in a project

Your first batch

1. Write project instructions.
2. Send one small, real task (or start one of Claude's suggested threads), then open the finished thread to see how it reported and what it did on its branch.
3. Check Thread model and Thread effort in Project settings > General. New projects run every thread on Opus at high effort, which uses your plan fastest.
4. Ask Claude to propose threads before starting them and to run only a few at a time. Relax that once threads come back as you want.

Sending work and reading results

• A quick question is usually answered in the conversation.
• New work goes to a new thread or an existing one in the same area, and Claude tells you which. New threads appear under your message as cards showing title and status; click one to open it.
• Several unrelated tasks in one message become separate threads.

Full results stay inside each thread; files are also on the Library tab. Sometimes Claude offers a Suggested threads list instead of starting them: click the arrow on one to start it, or the button underneath to start them all.

Pull requests from threads

By default a cloud thread that changes code:

• Works on a new branch from the repository's default branch.
• Opens a pull request when you ask, and may open one itself for a concrete fix.
• Then watches it with auto-fix on (regardless of your other sessions' setting): it pushes fixes when CI fails, responds to review comments, and tells you when checks pass and it is ready.

Thread cards may show buttons for the next step: Resolve conflicts, Fix CI, Address comments and Merge it send that instruction to the thread as if you typed it; Review PR opens GitHub; Create PR appears when an idle thread pushed a branch without opening a PR and creates the PR directly.

Change any of this (only open PRs when asked, branch from somewhere else) in the task or in project instructions.

Overview

The Overview pane is open the first time you visit a project. The Overview button in the header toggles it and shows a dot when something is waiting on you.

In the desktop app you also get notifications when Claude posts, a thread errors or needs input. To be notified every time a thread finishes a turn, or to silence a project, use Notifications in the project's sidebar menu. Browsers rely on the dot.

Taking control of a thread

Click a thread's card or Overview row to open its transcript. You can read each step, type in the thread's own message box (which goes straight to it, whereas a follow-up in the project conversation only reaches it if Claude routes it there), answer a permission prompt, or interrupt with Stop or Esc.

Models, effort and context

In Project settings > General:

• Thread model and Thread effort for threads. For a one-off, ask for a different model in the task or use a running thread's model picker.
• Coordinator model and Coordinator effort for the conversation.

New projects use Opus everywhere, with high effort for threads and low for the coordinator. You never manage context windows: threads compact automatically and the conversation works from recent messages, recent threads and project memory rather than its full history. Put anything that must never be lost in project memory.

Telling Claude how to run things

Just say it in the conversation:

• "Propose threads and wait for my go-ahead" or "start these without asking"
• "No more than two threads at once" or "reuse the existing thread for follow-ups in that area"
• "Only post when something finishes or gets blocked"
• "Give me a status update on every thread"
• "Use a smaller model for this one"
• "Don't open a PR until I've seen the plan"
• "Tell me what's wrong across these repos but don't fix anything yet"
• "Answer that here rather than starting a thread"

Claude saves preferences like these to project memory and applies them to later cloud threads. They are followed, not enforced, so a thread limit stated this way is not a hard cap. Put it in project instructions if you want exact wording applied from the start.

Approvals

Threads run in auto mode where the model supports it, so most tool calls go ahead without asking. When a thread does need approval, the prompt is inside that thread and it waits there; saying "go ahead" in the project conversation does not reach it. Each approval covers that prompt, or the rest of the thread if you pick the broader option.

To pre-approve or block commands for every thread, add permission rules to the repo's .claude/settings.json. That only applies in a one-repo project; with several repos, no repo's rules reach cloud threads, and you rely on auto mode and in-thread approvals.

Running a thread on your own computer

For a task that needs a local database, a device emulator or an API behind your VPN, ask for its thread to run locally. It becomes a Claude Code session in a folder on your machine, connected through Remote Control, while other threads stay in the cloud. Compared with a cloud thread it uses your machine's files, tools, MCP servers and Claude Code settings (including hooks and permission rules) instead of the cloud environment; starts with project instructions but without memory files loaded; and only runs while the computer is awake with Remote Control on.

1. Connect a folder (needs Claude Code v2.1.280 or later on that computer):
   • Desktop app: Settings > Claude Code, turn on Use this computer from your phone and claude.ai, and add the folder underneath. Works while the app is open.
   • Terminal: run claude remote-control in the folder and leave it running. In a git repo, add --spawn worktree so each thread gets its own worktree.
2. Ask for the task locally. Choose Work locally from the + menu beside the message box (your message is tagged Local), or just say it should run on your computer.
3. Allow it. Claude replies with an Allow Claude to work in a folder on your device card. Choose the folder; for a git repo, consider turning on Worktree so two threads cannot overwrite each other. Click Allow once.

The thread runs in auto mode; if auto mode is unavailable or off on that machine, its permission prompts wait in the thread. A laptop icon in the thread header shows whether your computer is connected and lets you see the folder or disconnect. The thread pauses while the computer sleeps and stops if the app or claude remote-control quits. The desktop app's Keep this computer awake for Remote Control setting prevents sleep. Local threads are unavailable while Require trusted devices is on for your account.

Standing context

Project memory appears in settings as Auto memory because Claude writes it. It is separate from the auto memory on your own machine and from the CLAUDE.md files in your repositories. Cloud threads still read each repo's CLAUDE.md from their clone, so put repo-specific rules there and project-wide notes in project memory.

Project instructions

Open Project settings from the gear icon and go to Memory > Project instructions. A good brief covers what the project is for, where the work happens (repos, base branch, PR naming), how a thread checks its own work, what to do when something is missing, and what needs your approval. For example:

This project migrates the customer portal from Create React App to Vite, in the portal-web repository.

- Branch from develop. One draft pull request per thread, titled "vite: <area>".
- Before calling anything done, run `pnpm build` and `pnpm test --run` and paste the final summary lines.
- If a dependency, secret or service you need is unavailable, say exactly what is missing in your first message and stop. Do not stub or guess.
- Ask in the thread before changing CI config, upgrading React itself, or merging anything.

When you correct a thread, also ask Claude to remember the correction so later threads start with it.

Choosing repositories

Repos you add to the project are cloned into every cloud thread with their CLAUDE.md and skills loaded, whether or not a task touches them. Repos you leave off are still reachable: a thread can add one to itself mid-task (with a note saying so), though its CLAUDE.md and skills were not present at start and the next thread will not have it. Either way, the repo needs the GitHub App and push access.

Claude can only add repos from GitHub owners the project already uses; add one from a new owner yourself in settings.

For a feature spanning many repos (server, web, mobile, desktop), add the one or two almost every task touches and name the others in project instructions. A project can also have no repos at all: threads can research, write documents and run code in their sandbox, delivering files to the Library.

Files and folders

Uploads are copies. After editing a file locally, upload it again and choose Replace.

What threads take from repositories

Every repo is cloned and its CLAUDE.md and skills loaded. Permission rules, hooks and env come only from the .claude/settings.json in the thread's starting folder: inside the repo for a one-repo project, and above the clones (where no repo's file is read) for a multi-repo project.

In multi-repo projects each clone is attached as an additional directory with instruction-file loading on, which is why every CLAUDE.md loads. Put standing rules in project instructions and environment variables in the cloud environment.

The cloud environment

New cloud threads use the project's cloud environment, which controls reachable domains, environment variables, network secrets and the setup script. Until you choose one in Project settings > Environment, a default Anthropic-hosted environment is used. For internal APIs, private registries or tokens, change the environment.

Getting your tools into threads

Cloud threads lack anything installed only on your machine:

• Skills, subagents, commands: commit them to a project repo (for example .claude/skills/<name>/SKILL.md). Every cloud thread loads them from every repo. Skills enabled on your claude.ai account load too.
• Plugins: add them under Project settings > Plugins. Plugins declared in a repo's settings do not load in cloud threads.
• MCP servers: cloud threads use the connectors on your claude.ai account (managed at claude.ai/customize/connectors or via Manage connectors in settings), with no per-project setup. In a one-repo project, servers from that repo's .mcp.json load too. The project conversation itself has no connectors, so send connector work as a task. See MCP.
• CLI tools and packages: install them in the environment's setup script.

To see a running thread's connectors, open it and choose Connectors from the + menu. Turning one off there removes it from that thread and becomes your account default for new threads and chats. Connectors added or reconnected take effect after your next message to the thread.

Settings reference

Project settings live in the web and desktop apps, not in settings.json. Open them from the gear icon or Settings in the project's sidebar menu. Changes save as you go (text fields show Save changes and Discard until you leave them) and affect new threads, not running ones.

• Pause interrupts every thread and the conversation, stops new threads and routines, and rejects messages until you click Resume (here or on the banner). Paused threads continue when you next message them.
• Archive hides the project and archives its threads, stopping any that were running or watching a PR. Routines do not run. Unarchive from the Projects page; threads must be unarchived individually.
• Delete permanently removes the project, its threads, memory and files, and turns off its routines. Branches and PRs on GitHub are untouched.

Usage and cost

Projects count against the same plan limits as your other sessions and cannot exceed them on their own. A thread that hits the limit waits and resumes when it resets, which means unattended work will start consuming your next window. Usage beyond the plan happens only if you have turned on usage credits; threads cannot turn them on.

What draws on your plan:

• Running threads. Each is a full session, several may run at once, and the only enforced cap is 200 new threads per day across your projects.
• The coordinator, reading reports and deciding what to do.
• Threads watching PRs, which wake on CI failures and review comments. Ask a thread to stop watching if you want it quiet.

An idle or archived project uses nothing. Project settings > Usage shows tokens by thread and model and how much went to the conversation. To reduce use:

• A follow-up to a thread idle longer than the cache lifetime (an hour on Pro and Max within plan limits) re-reads its whole history first, so a fresh thread can be cheaper for new work.
• Use a smaller model or lower effort for threads, the coordinator or both.
• Ask for fewer concurrent threads, or for small questions to be answered in place.

On Pro especially, expect to hit limits sooner on days you run a project.

How projects relate to other features

• Claude Tag is Claude in your team's Slack on Team and Enterprise, shared and steered by the channel, using admin-configured connections. A project belongs to you alone, uses your own GitHub access and connectors, and is on Pro and Max.
• Cloud sessions are what most threads are; Claude starts and tracks them for you.
• Routines created from a project run as threads in it and show on its Routines tab. Others are unaffected.
• Remote Control is how a thread runs on your computer.
• Local sessions and agent view cannot be added to a project; agent view tracks local sessions you start yourself.
• Worktrees isolate local parallel sessions; cloud threads do not need them because each clones into its own sandbox on its own branch.
• Agent teams are one session spawning teammates for one task, ending with it.
• Subagents run inside a single session; threads are whole sessions, and can use subagents themselves.
• Projects in claude.ai chat and Cowork are the older experience (grouped conversations and files, no threads or coordinator) and keep working until the redesign reaches them.

Agents compares these side by side.

Limitations

• Available on the web, desktop and mobile only: not in the terminal CLI, VS Code or JetBrains, and not via Bedrock, Google Cloud or Foundry.
• Threads are cloud sessions or Remote Control sessions on your machine, with Anthropic as model provider. See security and data usage.
• Sessions you started yourself on your machine cannot be added.
• A cloud thread's sandbox pauses between turns. If it cannot be resumed, the thread restarts from a fresh clone and uncommitted changes may be lost, so ask long-running threads to commit and push as they go.
• Projects belong to one user and cannot be shared; thread transcripts have no share option; there are no organisation controls during the beta.
• Threads cannot move between projects or out of one, and projects cannot be merged. Move to project only works inward.

Troubleshooting

A thread looks stuck. Claude does not narrate every step, so silence usually means work. New cloud threads also provision their environment first. Open the thread to check, and answer any permission prompt there.

Threads guessed or stalled. When several come back with wrong assumptions, workarounds or "blocked", the cause is usually one setup gap. Ask Claude: "For each open thread, tell me what you asked it to do, what it assumed or could not reach, and what it is waiting on." Resolve or redirect the bad threads (their branches and PRs stay on GitHub), fix the gap once in instructions or the environment, test with one thread, then resend the rest.

"Claude hasn't responded". The coordinator is running but replies are not arriving. Click Restart Claude on the banner or in Project settings > General. Any half-written reply is lost; threads are unaffected.

Repository access errors. Project threads need the GitHub prerequisites even if other cloud sessions clone the repo fine.

Click the offered button (Install GitHub App, Select repositories on GitHub) then Check again. Organisation-side blocks (an unapproved app, an IP allow list) show See how to fix instead.

Usage limit reached. The thread shows Service is busy and "Claude is still retrying and will continue automatically", resuming when your five-hour or weekly limit resets. Click Stop or pause the project if you would rather it did not. Threads started by a routine do not wait; they stop with a limit error and need a message after the reset.

Additional usage credits are required. A request needs credits your account does not have enabled (for example a model or context size outside your plan). See costs, then message again.

Lost contact with your folder. The local session stopped responding, usually because the machine slept or the app or claude remote-control quit. Wake it, and restart the app (checking Use this computer from your phone and claude.ai is still on) or rerun claude remote-control in the same folder.

Related

• Claude Code on the web
• Cloud environments
• Routines
• Remote Control
• Agents