How do I work on several projects with Claude Code at the same time?

Start a separate Claude Code session in each repository's directory, so each one loads that project's CLAUDE.md, settings and history. Group the terminals per project, with one terminal window or one tmux session each. claude agents gives you an overview of background sessions across all projects. Use --add-dir only when a single task really spans two repositories.

The hard part isn't running the sessions. It's knowing, from inside project A, that something in project C is waiting for you.

Step 1: one session per repository, started in its directory

Claude Code is directory-aware. Where you start it decides what it loads:

• Instructions. It loads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it. Your ~/.claude/CLAUDE.md applies to every project.
• Settings. .claude/settings.json and .claude/settings.local.json apply to that project only.
• History. claude --continue loads the most recent conversation in the current directory.
• Memory. Auto memory lives in one directory per git repository, shared across that repo's worktrees.

So:

cd ~/code/api && claude
cd ~/code/web && claude
cd ~/code/infra && claude

Each session stays in its lane. Put rules you want everywhere, like your commit style, in ~/.claude/CLAUDE.md, and project rules in each repo's CLAUDE.md. More in keeping notes your agents can read.

Step 2: group terminals per project

Mixing tabs from three projects in one window is how you type into the wrong session. Group them.

Option A: one terminal window per project. Name the window after the project. Inside it, one tab per agent, each in its own worktree if several agents share the repo.

Option B: one tmux session per project.

tmux new-session -d -s api -c ~/code/api
tmux new-session -d -s web -c ~/code/web
tmux attach -t api

-s names the session, -c sets its starting directory, and -d creates it without attaching. Inside tmux, the prefix key followed by s lets you pick another session interactively, and prefix d detaches. See whether you need tmux at all.

Step 3: get one view across projects

Agent view, a research preview as of October 2026, is the built-in overview:

claude agents

By default it lists every background session you've started, across all your projects, grouped by state, with the ones that need you at the top. To narrow it to one project:

claude agents --cwd ~/code/api

To start a background session in another project, cd there and run:

claude --bg "update the API client to the new pagination"

Or open claude agents in a parent directory such as ~/code and mention the repository with @api in the prompt. Agent view lists git repositories one level below the launch directory as targets.

Step 4: when one task spans two repos

Sometimes a change needs both the API and the client. Give one session access to both:

cd ~/code/web
claude --add-dir ../api

Or /add-dir ../api during a session. This grants file access only. Claude Code doesn't load the added directory's CLAUDE.md or most of its .claude/ configuration by default. To load its instruction files too:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../api

Keep this for real cross-repo tasks. For everything else, one session per repo is easier to review.

Limits of this setup

• Agent view only shows background sessions. The interactive session in your infra window isn't in the list unless you background it.
• Waiting is per window. A permission prompt in a project window you aren't looking at is easy to miss, unless your terminal shows Claude Code's notifications or you set up hooks. See which session is waiting for input.
• Limits are shared. Every session on your plan draws from the same session and weekly limits, whichever project it's in. See checking your usage limits.
• Context lives in your head. Each project's open tasks, notes and git state sit in different places.

With Kanbell

Kanbell is a macOS app (Apple Silicon) that uses the same layout: one window per project.

• Each project window has its own terminals, real ones, in panes and tabs. You run claude, codex or gemini in them as usual.
• Each project has its own board, local or GitHub Issues, its own markdown notes, and its own Git panel with changes, diffs, history and worktrees.
• Waiting shows outside the window too. When an agent waits, the orange dot shows in its window, in the menu bar and in the overview, with a macOS notification. ⌘⇧J jumps to the next agent that is waiting.
• Usage in one place. For Claude Code, Kanbell shows subscription usage for the session and the week, which is shared across all your projects anyway.

Claude Code gets full tracking, including subagents. Codex CLI and Gemini CLI show state and permission waits. Other CLI agents run without tracking. There is no account and no Kanbell server.