Running Claude Code Across Multiple Projects: A Structured Approach

If you're maintaining more than one codebase—a web application and its API, a CLI tool and its documentation site, or multiple client projects—you know the rhythm: switch directories, remember the project's build commands, remind yourself which environment is which.

Add Claude Code to that workflow and the complexity multiplies. Claude Code in one project uses different settings, standards, and dependencies than Claude Code in another. Running tasks across multiple projects without a structure quickly becomes chaotic.

This post covers how to organise Claude Code for multiple projects, avoid context bleed-over, and coordinate automation across your codebase portfolio.

The Multi-Project Problem

When you're working with a single project, Claude Code setup is straightforward:

• Clone the repo
• Run Claude Code
• Work happens in that one directory
• One set of rules and standards
• Done

With multiple projects, complexity emerges:

Context switching overhead. Moving from project A to project B means changing directories, loading a different CLAUDE.md, understanding different architecture, remembering different testing patterns. If Claude Code is running tasks automatically, it needs to know which rules apply where.

Rules collision. Project A might require TypeScript strict mode; Project B might not. Project A deploys to AWS; Project B uses Vercel. If you try to reuse the same Claude Code configuration across projects, you'll end up with rules that contradict each other.

Accidental cross-project changes. The most dangerous scenario: a prompt intended for Project A somehow runs against Project B's codebase. A batch file deletion, a database migration, a git force-push—these are catastrophic if they run against the wrong project.

Scheduling complexity. If you want multiple projects to run automated tasks on a schedule, you need a system for managing multiple jobs, multiple schedules, and multiple failure modes. Running 20 different projects with cron entries scattered across your machine is unmaintainable.

The Solution: Structured Workspaces

The key to multi-project Claude Code management is structured workspaces. Here's the pattern:

~/Projects/
├── workspace.config.json       # Master configuration
├── client-web/                 # Project 1
│   ├── CLAUDE.md
│   ├── .claude/
│   │   └── commands/
│   └── ...
├── client-api/                 # Project 2
│   ├── CLAUDE.md
│   ├── .claude/
│   │   └── commands/
│   └── ...
└── internal-tools/             # Project 3
    ├── CLAUDE.md
    ├── .claude/
    │   └── commands/
    └── ...

Each project gets:

• Its own directory
• Its own CLAUDE.md with project-specific rules
• Its own .claude/commands/ directory for custom commands

The workspace.config.json (or similar) is a registry that documents:

• Which projects exist
• How to access each project
• What automated tasks run in each project
• Which environment variables are project-specific

Setting Up Individual Project Contexts

Each project's CLAUDE.md should make clear:

1. What the project does
2. How to run it locally
3. What tests exist and how to run them
4. Deployment procedures
5. Which environments it talks to (staging, production)
6. Key dependencies and versions

Here's a minimal structure:

# Client Web

React frontend for the Acme dashboard.

## Quick Start

npm install

npm run dev

# Opens at http://localhost:3000

## Testing

npm test

npm run e2e # Playwright tests in staging

## Deployment

- Main branch → staging (automatic)
- Create a release tag → production (manual via GitHub UI)

## Do Not

- ❌ Commit NEXT_PUBLIC_* env vars with real values
- ❌ Run `npm run build` against production API
- ❌ Force-push to main

This context is enough for Claude Code to work safely in this project without accidentally interfering with other projects.

Avoiding Context Switching Mistakes

Here's where things can go wrong. Imagine you're running automated Claude Code tasks in two projects:

Mistake 1: Shared configuration

You create one global Claude Code config that applies to all projects. Project A's rules override Project B's rules, or vice versa. Claude Code follows the wrong standards.

Prevention: Each project gets its own CLAUDE.md. No global overrides.

Mistake 2: Ambiguous prompts

You queue a task: "Fix the failing tests." If Claude Code isn't absolutely clear which project this applies to, it might run against the wrong one.

Prevention: Always specify the project explicitly. In OpenHelm, each job belongs to a specific project directory. At the terminal, always cd into the correct project before running Claude Code.

Mistake 3: Environment variable bleed

You set an environment variable for Project A (DATABASE_URL=prod-a). You forget to unset it. You then run Claude Code in Project B, and it connects to Project A's production database.

Prevention: Use project-specific .env files (not git-committed) that are loaded per project. Use .env.project-name naming to make it explicit which environment is active.

Mistake 4: Accidental git operations

Claude Code commits and pushes changes. If the wrong project's directory is active, changes might go to the wrong repo.

Prevention: Make commit/push operations explicit in Claude Code prompts. Instead of "fix the issue and push", say "fix the issue in the client-web project and commit to the client-web repository". Double-specificity prevents ambiguity.

Coordinating Automation Across Projects

If you're running scheduled, unattended Claude Code tasks across multiple projects, use a job orchestrator. This is where tools like OpenHelm shine.

OpenHelm lets you:

1. Define each job within its specific project directory
2. Assign a unique cron schedule to each job
3. View run history across all projects from a single dashboard
4. Set up silence detection and self-correction per job
5. Route failures to the right Slack channel

Without a tool like this, you'd be managing cron entries scattered across your machine, with no unified view of what's running, what failed, and when.

Example OpenHelm setup for three projects:

Job 1: client-web - Nightly tests
  Directory: ~/Projects/client-web
  Schedule: 0 2 * * *  (daily at 2 AM)
  Command: npm test && npm run e2e
  On failure: Retry once, then Slack #client-web

Job 2: client-api - Weekly backup
  Directory: ~/Projects/client-api
  Schedule: 0 3 * * 0  (Sundays at 3 AM)
  Command: npm run db:backup
  On failure: Slack #ops

Job 3: internal-tools - Daily sync
  Directory: ~/Projects/internal-tools
  Schedule: 0 4 * * *  (daily at 4 AM)
  Command: npm run sync:external-data
  On failure: Retry, then Slack #engineering

Each job runs in its own project context. Each has its own schedule. Failures are routed appropriately.

Directory Structure Best Practices

1. Use a consistent naming scheme

All your projects live in one parent directory (~/Projects/). Makes automation easier. Machine can discover projects by scanning the directory.

2. Each project has a README

The README explains what the project does, how to set it up, and how to deploy it. It's the first thing you (or Claude Code) read.

3. Each project has a CLAUDE.md

Project-specific rules and context for Claude Code.

4. Each project has a .env.example

Shows which environment variables are needed. Developers copy it to .env and fill in values locally. Never commit .env.

5. Automation lives in the root

If you have a workspace-level job orchestrator (like OpenHelm), it runs from the parent directory and knows where each project is.

Common Multi-Project Workflows

Scenario 1: Running tests across all projects nightly

Create a wrapper script that loops through each project directory and runs tests:

#!/bin/bash
for project in ~/Projects/*/; do
  echo "Testing $(basename "$project")..."
  cd "$project"
  npm test
done

Then schedule this script in OpenHelm or cron.

Scenario 2: Pulling changes from main and testing

Each project has a main branch. Each night, you want to:

1. Pull the latest changes from main
2. Run tests
3. Report results

for project in ~/Projects/*/; do
  cd "$project"
  git pull origin main
  npm test || echo "Tests failed in $(basename "$project")"
done

Scenario 3: Deploying multiple projects on a schedule

You have a multi-project dashboard. Each project deploys independently on different schedules:

• client-web: every push to main (automatic via CI)
• client-api: weekly on Mondays
• internal-tools: on-demand via CLI command

OpenHelm handles this by defining separate jobs per project with different schedules.

Gotchas and How to Avoid Them

Gotcha 1: Forgetting which directory you're in

Solution: Use a shell prompt that shows the current directory and project name. Make it visually obvious.

Gotcha 2: Environment variables from one project affecting another

Solution: Use .env files per project, load them explicitly with source .env, and unset them when leaving a project.

Gotcha 3: Git confusion (committing to the wrong repo)

Solution: Double-check git remote -v before committing. Require explicit branch names in prompts: "commit to client-web's develop branch".

Gotcha 4: One project's tests failing silently, thinking all projects are healthy

Solution: Centralised run logging. Use OpenHelm or a similar tool so you have a single place to check results from all projects.

FAQ

Q: Should I use git submodules or monorepo?

A: Neither for this pattern. Keep projects as separate repositories in separate directories. Simpler, fewer merge conflicts, clearer ownership.

Q: Can I run Claude Code against multiple projects in one session?

A: Not recommended. Keep Claude Code focused on one project per session. If you need cross-project work, break it into separate, sequential tasks.

Q: How do I know which project Claude Code is working on?

A: The prompt should be explicit. "In the client-web project, fix the login bug." If there's ambiguity, stop and clarify before proceeding.

Q: Do all my projects need identical setups?

A: No. Each project should have its own setup, standards, and deployment process. The only requirement is that each has a CLAUDE.md explaining its own rules.