Claude Code across many projects: keep them apart

Claude Code keeps multiple projects apart by folder. Whatever directory you start claude in decides which sessions it saves to, which CLAUDE.md it reads, which .claude/settings.json applies and which .mcp.json servers load. So run one session per project folder, each in its own terminal tab, tmux session or editor window, and put what all your projects share in user scope once.

That is a different job from one task that spans several repositories, where a single session needs both at once: for that, --add-dir is the tool, covered in Claude Code with multiple repos. Everything below comes from Anthropic's pages on settings, memory, MCP and sessions, read on 24 October 2026.

What Claude Code keeps per project, and what it shares#

The <project> name is your working directory's path with every character that isn't a letter or a digit turned into -. Start Claude Code in ~/code/api and in ~/code/web and you get two history folders, two sets of project settings and two lists of local MCP servers, with nothing crossing between them. Auto memory is the one exception to "per folder": it is keyed to the git repository, so every worktree and subdirectory of one repo shares it.

When a key is set in more than one settings file, the project's local file beats the committed project file, which beats your user file (managed settings from an organisation beat all three). MCP servers follow the same idea: a server name defined in local scope wins over the same name in project scope, which wins over user scope, and Claude Code connects to it once.

How to switch between projects in Claude Code#

The plain way is to exit and start again in the other folder: cd ~/code/web && claude. claude --continue then reopens the most recent session in that directory, and claude --resume opens a picker of that directory's sessions.

When you can't remember which folder a conversation lives in, open the --resume or /resume picker and press Ctrl+A. The list then shows sessions from every project on the machine; press Ctrl+A again to go back to the current repository (Ctrl+W widens to all worktrees of the repository instead). Pick a session from an unrelated project and Claude Code doesn't open it in the wrong folder: it copies a cd and resume command to your clipboard, for you to paste and run.

To carry the same conversation into another project, type /cd ../web inside the session. Anthropic's permissions page says Claude Code keeps the conversation, loads the new folder's CLAUDE.md, applies its project settings, hooks and .mcp.json servers, and disconnects the previous folder's project and local MCP servers. The session's history moves to the new folder's storage too, so --resume finds it from there. Applying the new folder's settings, hooks and MCP servers on the spot needs Claude Code 2.1.246 or later; before that, /cd left them until you resumed the session.

Naming sessions makes all of this quicker. Start with claude -n auth-refactor or run /rename auth-refactor, and claude --resume auth-refactor takes you straight back from anywhere in that repository.

Running Claude Code on multiple projects at once#

Each claude process belongs to the folder it started in, so running several projects at once is a matter of giving each one a place to live.

Terminal tabs or windows are the simplest: one per project, each opened in its folder. They are fine until you have more tabs than you can name at a glance.

tmux gives each project a named session that survives a closed terminal window:

tmux new -d -s api -c ~/code/api claude     # a detached session named api, started in ~/code/api
tmux new -d -s web -c ~/code/web claude
tmux attach -t api                          # look at one; Ctrl+B d detaches again

Inside tmux, Ctrl+B s lists the sessions so you can jump between projects, and tmux switch-client -t web does the same from a command (the tmux manual has both). For several Claude Code sessions inside one project, each in its own worktree, see running multiple Claude Code sessions in tmux.

Editor windows work the same way. Open each project as its own window and run Claude Code in that window's terminal; it starts in the project folder.

Agent view is the built-in option. claude agents lists every background session you've started, across all your projects, and is still a research preview. It groups the list by state by default; press Ctrl+S to group it by directory instead, and the choice sticks. With a directory group selected, a new prompt starts its session in that group's folder, so you can dispatch work into another project without retyping a path. claude agents --cwd ~/code/api narrows the list to one project. The setup and its limits are in Claude Code agent view.

A projects folder: what it shares and what it doesn't#

Many people keep every repository under one folder, such as ~/code. Claude Code loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it, so a ~/code/CLAUDE.md reaches every session you start below it. The files are joined, not swapped: the parent's comes first in context and the project's own after it, so Claude reads the project's instructions last.

Settings don't inherit that way. Claude Code reads the shared .claude/settings.json from the folder the session starts in (in a git repository, it keeps the local file at the repository root), so a ~/code/.claude/settings.json does nothing for a session started in ~/code/api. Put settings meant for every project in ~/.claude/settings.json.

Set shared things up once, in user scope#

The usual cause of "I keep adding the same thing to every project" is that Claude Code's defaults are per project. claude mcp add without a flag uses local scope, so the server loads only in the folder where you ran it. To give every project the same server:

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

The same goes for rules and preferences. Rules that apply everywhere ("use pnpm", "never commit to main") belong in ~/.claude/CLAUDE.md or a file in ~/.claude/rules/, and permission rules you want everywhere belong in ~/.claude/settings.json. Keep the project files for what is true of that project alone, and commit the shared ones (CLAUDE.md, .claude/settings.json, .mcp.json) so teammates get them too. Picking a scope per server, and the Codex side of the same question, is in set up MCP servers once for every project.

User scope is all or nothing: a user-scope server loads in every project on that machine. A server you want in four projects out of ten has to be added to each of the four.

How Shuriken does it#

Shuriken is a harness for coding agents, and it is built around projects. Home shows every project as a card, with its state on the card when it has one ("Working", "Needs you"); it arrived in Shuriken 4.0. The project switcher (⌘P on a Mac, Ctrl+P elsewhere) searches your projects and lists the recent ones, and the sidebar shows the chats of the project you're in. Chats in different projects run at the same time.

A Claude chat in a project starts in that project's folder and reads your user settings plus the project's own and local ones, so its CLAUDE.md, .claude/settings.json and .mcp.json apply as they would in a terminal. A chat without a project reads only your user settings.

MCP servers live in one list, under Settings › Extensions › MCP servers. When you add one, Shuriken asks which projects can use it: All projects puts it in Claude Code's user config on each of your computers, and switching All projects off lets you pick projects one by one, which covers the four-out-of-ten case above. One sign-in covers every project the server runs in (global MCPs). If you want your projects on one screen, download Shuriken.