How to run Claude Code across multiple projects at once

Claude Code ties each session to the directory you start it in, so the way to work on several projects at once is one session per repository: run claude from each project folder in its own terminal tab, tmux session, background session or desktop app session. Each session loads that project's CLAUDE.md, settings and history, and all of them draw on the same plan usage. Use --add-dir only when one task has to edit two repositories.

One session per repository is the default

The sessions documentation defines a session as a saved conversation tied to a project directory, and by default Claude has access to the files in the directory where you launched it. So the baseline needs no setup: open one terminal tab per project and start Claude in each:

cd ~/code/shop && claude -n shop
cd ~/code/client-site && claude -n client-site

-n (long form --name) sets a display name that appears in the terminal title and the resume picker, and you can return to the session later with claude --resume shop. Inside a session, /rename changes the name and /color sets the prompt bar color, which helps when the tabs look alike.

The cost is attention: a row of tabs does not show which agent has stopped to ask for permission. Claude Code fires a notification when it finishes or pauses for a permission prompt while you are away from the terminal, but by default that is a desktop notification only in Ghostty, Kitty and iTerm2. In other terminals, turn on the terminal bell in ~/.claude/settings.json:

{
  "preferredNotifChannel": "terminal_bell"
}

tmux keeps each project's session running in one terminal

A terminal multiplexer replaces the row of tabs with named sessions that keep running after you detach. With tmux, create one detached session per project, each starting in that project's directory, then attach to one:

tmux new-session -d -s shop -c ~/code/shop
tmux new-session -d -s client -c ~/code/client-site
tmux attach -t shop

-d creates the session without attaching to it, -s names it and -c sets its start directory. Run claude in each. Ctrl+b then s opens a list of sessions to switch to, Ctrl+b then d detaches and leaves everything running, and tmux ls lists the sessions from the shell.

Inside tmux, Claude Code's desktop notifications do not reach the outer terminal and Shift+Enter submits instead of adding a line, until you add the lines the terminal configuration page gives for ~/.tmux.conf:

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

tmux solves persistence and switching, but you still see one project at a time and depend on those notifications to learn that another is waiting.

Agent view lists background sessions from every project

Claude Code's own answer to "which one needs me" is agent view, opened with claude agents. It is one screen that groups your background sessions by state (needs input, working, completed) and, by default, lists every one you have started across all your projects, whichever directory you opened it from. Start a background session in each project, then open the list:

cd ~/code/shop && claude --bg "upgrade the payment SDK and fix what breaks"
cd ~/code/client-site && claude --bg "add the contact form described in BRIEF.md"
claude agents

Ctrl+S groups the list by directory, and claude agents --cwd ~/code/shop narrows it to one project. A session you already have open in a terminal appears only after you send it to the background with /bg.

Two caveats. Agent view is a research preview whose interface and shortcuts may change. And in a git repository, a session started with --bg or from agent view moves into its own worktree under .claude/worktrees/ before it edits files, so its changes land there, not in the checkout you have open. It commits its work, and pushes the branch when the repository has a remote, unless your instructions say you handle git yourself.

The desktop app runs sessions side by side in a sidebar

In the Code tab of the Claude desktop app, each session has its own chat history and project folder, and the sidebar lets several run in parallel. Click + New session (Cmd+N on macOS), choose the project folder and start. You can filter the sidebar by status, project or environment, group sessions by project, and Cmd-click a second session to open it in a pane beside the first. The app sends an OS notification when a session finishes a task you are not looking at. It runs on macOS and Windows, with a Linux beta.

The app and the CLI read the same configuration, including CLAUDE.md files, settings and MCP servers, but each keeps its own session list. What you give up is scripting: flags such as --print have no desktop equivalent.

--add-dir gives one session access to a second repository

Sometimes the projects are not independent, such as a shared library and the app that consumes it. Then give one session both directories instead of running two:

cd ~/code/shop
claude --add-dir ../shared-ui

--add-dir adds a working directory that Claude can read and edit under the same permission rules as the first, and it accepts several paths. /add-dir does the same in a running session, and permissions.additionalDirectories in a settings file makes the access permanent.

What you get is file access, not configuration. The added directory's CLAUDE.md is not loaded unless you set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. Its skills, commands and subagents load when you add it with the flag or the command, and nothing loads when you add it through the settings key. Directories added with the flag are not restored when you resume, so pass them again. It is still one conversation, so treat it as a tool for a task that crosses repositories, not as a way to run projects in parallel. To move a session to another project altogether, use /cd.

What stays per project and what is shared

claude --continue reopens the most recent conversation in the current directory, and claude --resume opens a picker for the current project. Press Ctrl+A in the picker to list sessions from every project on the machine; choosing one from an unrelated project copies a cd and resume command to your clipboard.

Every session draws on the same usage limits

Usage is counted against your account, not per project. Plan usage is shared across all your Claude Code surfaces, running several sessions at once multiplies token usage, and the agent view documentation puts a number on it: ten agents in parallel use quota roughly ten times as fast as one. Cloud sessions share the same rate limits.

Subscription plans have a session limit and a weekly limit, both shared across all models. When one runs out, Claude Code blocks further requests until the reset time shown in the message. Run /usage in any session to see your plan limits and when they reset; its usage breakdown is computed from session history on that machine, so it leaves out other devices. With Claude Console sign-in instead of a subscription, usage is billed per token.

How Armadai lays out multiple projects

Armadai is a native macOS app built around one workspace per project. Each project folder becomes a workspace on one infinite canvas, with its own agents, terminals, code, browser, notes and tasks. Claude Code runs in a real terminal tile inside the workspace, next to that project's editor and browser preview.

Its answer to the attention problem is a sidebar that lists the sessions across all your projects with a status for each: working, idle or needs approval. You can review a waiting session's request and approve it from the sidebar without leaving the workspace you are in. The choices depend on the agent and the request, and some prompts have to be answered in the session itself.

Projects can share one canvas or be split across several, and Tab View gives each workspace its own tab. A workspace you close reopens with its saved tiles and layout.

Armadai runs the Claude Code you already have installed, under your own account, so the usage limits above and your Mac's resources still apply; the Armadai plan itself does not limit workspaces or agents. It is a paid app with no free plan: $20 a month or $120 a year after a 7-day free trial that requires a payment method.

If two or three terminal tabs, or a tmux session per project, cover your work, you do not need another app. A canvas pays off when you want each project's agent, code, preview and notes visible together, with one place that shows which agent is waiting.