Claude Code Projects: Retire an API Across 3 Repos

On September 17, 2026, Anthropic quietly shipped one of the biggest changes to how you actually manage agentic coding: a rebuilt Claude Code Projects. It went from "a folder of chats and reference files" to something closer to a chief-of-staff conversation that spins up, tracks, and reports back on parallel coding threads for you. A week later it's still spreading through dev Twitter/X and Hacker News threads, alongside coverage from VentureBeat, MarkTechPost, and The New Stack, because it solves a problem every agentic-coding user has run into: running five Claude Code sessions at once means you become the scheduler, repeating context in each one and manually checking which finished.

This guide walks through the whole feature end to end, using the exact real-world scenario Anthropic itself points to: retiring a deprecated API endpoint across three repositories (a backend service, a web app, and a mobile app) with one coordinator conversation instead of three separate terminals. By the end, you'll know how to create a project, write project instructions that every thread inherits, hand off multi-repo work, review the pull requests that come back, and avoid the usage traps that catch people in week one.

This is a beta, UI-driven feature (not a new API), so "code" here means the actual config text you'll paste into Claude Code: project instructions, a CLAUDE.md, a .claude/settings.json permission block, and a cloud environment setup script. Every one of these is copy-pasteable and verified against Anthropic's own docs as of this guide's publish date.

What you'll need

A Claude Pro or Max plan with Projects showing in the sidebar at claude.ai/code or in the Code tab of the Claude desktop app. It's a gradual rollout — if you don't see it yet, there's a waitlist at claude.com/form/projects.
Code on github.com (not GitHub Enterprise Server, GitLab, or Bitbucket) — Projects only works with GitHub repos plus uploaded files/folders/Google Drive.
Push access on the GitHub account you connect, with the Claude GitHub App installed on the repos you'll use.
Roughly 20 minutes and three toy (or real) repos you don't mind Claude opening branches and PRs against.

Why this is different from just running three Claude Code tabs

Claude Code has let you run multiple sessions for a while — worktrees, agent view, background subagents. What Projects adds is a persistent coordinator sitting above all of that. You talk to one conversation; it decides whether your message is a quick question, new work for a new thread, or a follow-up for a thread that's already running. Every thread it starts is a full Claude Code cloud session with its own git branch, and the coordinator reads what threads report back (not their step-by-step actions) so it can keep working for weeks without you re-explaining the goal.

Three pieces of state carry across every thread automatically, and this is the part worth understanding before you start: project instructions (a standing brief, up to 16,000 characters), project memory (an auto-written MEMORY.md index of decisions and pitfalls Claude accumulates as it works), and the project's repositories, files, and cloud environment. Get those three right once and every thread you spawn for the next month starts from the same page.

Step 1: Create the project

Go to claude.ai/code (or the Code tab in the desktop app), click Projects in the sidebar, then New project — or jump straight to claude.ai/code/projects/browse.
Name it something that describes an ongoing stream of work, not a single task — for example "Retire /v1/users" rather than "Fix bug". A single fixable bug belongs in a normal cloud session, not a project.
Optionally set a Goal (one line Claude works toward, e.g. "Remove every caller of the deprecated /v1/users endpoint and delete the route") and add Context: the GitHub repos and any files the project should start with.
Click Create project. On your very first project, Claude takes an unprompted turn: it may explore a repo read-only and propose next steps, or post Setup recommendations (repos to add, routines to create) pulled from your recent cloud sessions. Review and toggle those before clicking Update setup — or just ignore them and type your own instructions.

Step 2: Write project instructions

This is the single highest-leverage step. Every new thread starts by reading this text, so put your non-negotiables here instead of repeating them in every message. Open the gear icon → Project settings → Memory → Project instructions and paste something like this (adapted from Anthropic's own example):

This project removes every caller of the deprecated /v1/users endpoint
across api-service, web-app, and mobile-app, then deletes the route.

- Branch from main. Name branches retire-v1-users/<repo>.
- Open one draft pull request per thread, one thread per repository.
- Before you call work done, run the repo's test suite and lint command
  and paste the summary lines in your final message.
- If you can't reach something you need (a repo, a secret, an API, a
  connector), say exactly what's missing in your first message and stop.
  Don't substitute, mock, or guess at the missing piece.
- Don't merge, force-push, or touch CI configuration without asking me
  directly in the thread first.
- Land the api-service thread's PR before the web-app and mobile-app
  threads merge theirs, since they depend on the new endpoint shipping.

Notice the second-to-last rule: cross-thread ordering. The coordinator conversation is the only place that knows all three threads exist, so sequencing instructions like "land the backend first" belong here, not in any single repo's CLAUDE.md.

Step 3: Add repositories and let Claude fan out

In Project settings → Environment, add api-service, web-app, and mobile-app. Every thread from now on clones all three and loads each one's CLAUDE.md and .claude/skills/, whether or not that thread's task touches all of them — so keep this list to the repos most tasks actually need. For a project spanning many more repos, add only the one or two that nearly every task touches and name the rest in project instructions; a thread can still add a repo to itself mid-task when it discovers it needs one.

Now send the actual work in the project's message box:

Retire /v1/users. It's replaced by /v2/users everywhere.

Start with api-service: add a deprecation warning header on /v1/users
for one release, then remove the route and its tests once web-app and
mobile-app no longer call it. Start web-app and mobile-app in parallel:
find every caller of /v1/users, migrate them to /v2/users (the response
shape changed: "id" is now a string UUID, not an int), and update the
tests that assert on the old shape.

Claude reads that, splits it into three threads (one per repo, since you named them), and each shows up as a card under your message. Three unrelated tasks in one message reliably become three separate threads — Anthropic's docs confirm this is the default routing behavior, not something you have to force.

Step 4: Give threads what only your machine or account has

Cloud threads don't inherit anything from the Claude Code setup on your laptop — no local MCP servers, no locally-installed CLI tools, no local skills unless they're committed to a repo. To close those gaps:

Skills, subagents, commands: commit them to a project repo at .claude/skills/<name>/SKILL.md, .claude/agents/, or .claude/commands/ — every thread clones every project repo, so a skill in any one of them is available everywhere.
MCP servers: connect them once at claude.ai/customize/connectors. Every thread gets every connector on your account automatically — there's no per-project MCP config. (The coordinator conversation itself has zero connectors; route anything needing a tool call to a thread.)
Plugins: add them under Project settings → Plugins. A plugin only enabled in a repo's own .claude/settings.json does not load into cloud threads — you have to add it at the project level.
Command-line tools, private registries, secrets: these live in the project's cloud environment (Project settings → Environment), configured with a setup script, same as any other Claude Code cloud session.

If a task truly needs your own machine — a local database, a device emulator, something behind your VPN — you don't have to skip Projects. Run claude remote-control in the target folder (requires Claude Code v2.1.280+) and ask the project to run that one thread through Remote Control instead of the cloud.

Step 5: Lock down permissions with .claude/settings.json

Threads run in auto mode by default (most tool calls execute without a prompt), but you can still hard-block or pre-approve specific commands. This only applies when the project has a single repository — with multiple repos, per-repo permission rules don't carry over, so put broad rules in project instructions instead. For a single-repo project, drop this in the repo's .claude/settings.json:

{
  "permissions": {
    "allow": ["Bash(npm test:*)", "Bash(npm run lint:*)"],
    "deny": ["Bash(git push --force:*)", "Bash(rm -rf:*)"]
  }
}

Step 6: Review what comes back in Overview

The Overview pane beside the conversation groups every thread into six states: Ready for review (PR open, waiting on you), Waiting on you (needs a reply, approval, or failed), Working, Landing (approved or queued to merge), Idle, and Resolved. When a thread pushes a branch or opens a PR, its card grows action buttons — Resolve conflicts, Fix CI, Address comments, Merge it, Review PR — so you can nudge a specific thread without hunting for its tab.

Every cloud thread also watches its own PR with auto-fix on by default: if CI fails, it pushes a fix on its own and pings the thread when checks go green, whether or not auto-fix is enabled on your other cloud sessions.

Worked example: the full retirement flow

Here's what actually happens end to end for the /v1/users example above, based on the workflow Anthropic describes and the thread lifecycle documented for Projects:

You send the retirement task in the project conversation. Claude matches "api-service", "web-app", and "mobile-app" to three separate threads and posts three cards.
The api-service thread adds a deprecation header, opens a draft PR against main, and — per your instructions — waits before deleting the route.
The web-app and mobile-app threads run in parallel, each greps for /v1/users callers, rewrites them against /v2/users, updates assertions for the new string-UUID id field, and opens its own draft PR.
CI fails on the mobile-app thread because a snapshot test still expects an integer ID. Auto-fix kicks in: the thread pushes a fix on its own branch and replies in its card once checks pass, no message from you required.
You open Overview the next morning. All three show Ready for review. You click Review PR on each, approve, and merge api-service first per your ordering rule, then the other two.
You tell the coordinator "remember: mobile-app snapshot tests need regenerating whenever a response shape changes" — that becomes a project memory entry, so the next thread that touches a response shape starts already knowing it.

Common pitfalls

It burns plan usage fast. Every running thread is a full Claude Code session, and there's no fixed concurrency cap (only an enforced 200-new-threads-per-day ceiling). Three threads running at once uses roughly three sessions' worth of your five-hour and weekly limits simultaneously. On a Pro plan especially, expect to hit limits sooner on days you run a project — a thread that hits the limit just waits and resumes automatically when it resets, it doesn't fail.
New projects default to Opus at high effort for every thread. That's the most capable and most expensive combination. Drop to a smaller model or lower effort in Project settings → General for threads that don't need it — reserve Opus/high for genuinely hard multi-file refactors.
A thread belongs to exactly one project, forever. You cannot move or copy a thread to a different project, and a project can't be shared with another user or team during the beta — this is a single-user tool for now, with Team/Enterprise support "coming later."
Permission rules silently stop applying once you add a second repo. If you were relying on a single repo's .claude/settings.json to block a command, that protection disappears the moment the project has multiple repos — you have to restate the rule in project instructions instead.
Idle threads aren't free forever. A thread watching a merged PR wakes back up (and spends usage again) if CI fails or a new review comment lands, even weeks later. Tell a thread explicitly to stop watching its PR once you're done with it.
It's cloud-only for now. Projects live at claude.ai/code, the desktop app, and the mobile app — not the terminal CLI, and not on Bedrock, Vertex AI, or Microsoft Foundry. The CLI's existing claude project command manages unrelated local directory state and has nothing to do with this feature.
Uncommitted work can vanish between turns. A cloud thread's sandbox pauses between turns and resumes when you send the next message; if the pause can't resume cleanly, the thread restarts from a fresh clone and loses anything it hadn't committed. On long-running threads, tell Claude to commit and push work-in-progress regularly.

Quick reference

Setting	Where	Default	Notes
Thread model / effort	Project settings → General	Opus, high effort	Lower it for routine tasks to save usage
Coordinator model / effort	Project settings → General	Opus, low effort	Rarely needs raising
Project instructions	Project settings → Memory	Empty	Up to 16,000 characters, sent to every new thread
Project memory (MEMORY.md)	Project settings → Memory	Auto-written	Claude writes/edits this itself as it works
New threads per day	Account-wide cap	200	Hard enforced limit, not per-project
Permission rules from .claude/settings.json	Repo config	Applies	Only when the project has exactly one repository
Local machine access	Remote Control	Off	Run `claude remote-control` in the target folder, needs v2.1.280+
Availability	Plans	Pro, Max (beta)	Not yet on Team, Enterprise, or via the CLI/Bedrock/Vertex/Foundry

Next steps

Start small: move one cloud session you already have running into a project with Continue as a project from its menu, and watch how Claude proposes the setup before you build one from scratch.
Once a project is producing PRs you trust, ask Claude to turn part of the recurring work into a scheduled routine so it fires without you opening the conversation.
If your work needs your laptop's tools (a local emulator, an internal database), pair Projects with Remote Control rather than forcing everything into the cloud sandbox.
Read the full reference at code.claude.com/docs/en/claude-projects — the troubleshooting section covers exact error strings ("Couldn't start the session", "Reached the turn limit") and the fix for each.

Sources: Anthropic's Claude Code Projects documentation (code.claude.com/docs/en/claude-projects), the "Projects redesigned" launch post (claude.com/blog/projects-redesigned), and coverage from VentureBeat, The New Stack, and MarkTechPost, all published between September 17–25, 2026.