How to run Claude Code in parallel

The biggest limitation of Claude Code today is simple: you can only run one task at a time. While one agent is refactoring auth, you’re stuck waiting. It can’t write tests or document changes in parallel.

Think about it like CI/CD. You don’t sit around waiting for a test suite to finish. You run jobs, let them cook in the background, and review the results when you’re ready. Claude Code needs the same kind of orchestration.

There are emerging workarounds—tools like Claude Squad uses tmux to split terminals; Vibe Kanban overlays a kanban UI on top of agents; others isolate agents in containers.

But they all share the same flaw: they’re all just workarounds.

Why current parallel solutions fall short

Claude Code is a CLI tool. It’s not an orchestrator, not a runtime, not an environment. It doesn’t manage state, handle concurrency, or isolate compute.

That means most community-built solutions end up fragile, manual, or both:

• Git worktrees isolate your source code, but agents still fight over the same resources.
• Kanban UIs give you visibility but not full isolation between agents.
• Tmux gives you multiple windows, not multiple environments. You’re still constrained by your local machine.
• SSH to another machine works, for one or two agents. But what about ten? Do you spin up VMs manually? What about teardown, state, and recovery?

Run each Claude Code in its own environment

This is where Gitpod comes in. Instead of hacking around limitations, you get purpose-built infrastructure that supports real agent parallelism:

• Each Claude Code agent runs in its own environment
• Environments start, stop, and persist (even when you close your laptop)
• Dev Container ensures that every agent has identical tools and configuration
• Jump into any environment with VS Code, JetBrains, or your preferred editor
• Each environment gets its own CPU, memory, file system, git state, and services

Gitpod is crafted for parallel development as each development environment can run tests, compile code, and manage dependencies.

Setting up Claude Code in Gitpod

Here’s how to run parallel Claude Code agents:

1. Configure your Dev Container with Claude Code
2. Create a file secret for credentials
3. Set up authentication with dotfiles
4. Launch multiple environments

See this video for a demo.

Step 1: Configure your Dev Container

Create a .devcontainer/devcontainer.json that includes the Claude Code Dev Container feature:

{
	"name": "Claude Code Development",
	"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
	"features": {
		"ghcr.io/devcontainers-contrib/features/claude-cli:1": {}
	}
}

The ghcr.io/devcontainers-contrib/features/claude-cli:1 feature automatically installs Claude Code and its dependencies.

Rebuilding your environment

After creating or modifying your .devcontainer/devcontainer.json, you’ll need to rebuild the environment to apply the changes:

Using VS Code command palette

1. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
2. Type and select Gitpod: Rebuild Container
3. The environment will rebuild and reconnect automatically

Alternatively

Run gitpod environment devcontainer rebuild

From inside or outside the environment.

Step 2: Create a File Secret for authentication

Now that Claude Code is installed in your environment through the Dev Container feature, you need to authenticate it:

1. Open a Gitpod environment with your configured Dev Container
2. Connect with a local editor (VS Code, JetBrains, or Cursor) - not the browser-based editor as the auth flow redirects to localhost, which requires port forwarding
3. Run claude login in the terminal
4. Complete authentication in your browser
5. Copy your authentication file ~/.claude.json from the environment

Create the Gitpod secret

1. Go to gitpod.io/user/secrets
2. Create a new File Secret
3. Name: CLAUDE_AUTH (or any name you prefer)
4. File location: /root/.claude.json
5. Paste your entire .claude.json file

Step 3: Set up authentication with dotfiles

In ephemeral environments, you need to ensure each environment is authenticated. With Gitpod, you do this through dotfiles–scripts that run personally for you in every environment.

1. Create a dotfiles repository (e.g., github.com/yourusername/dotfiles)
2. Add Claude setup script at claude/.run:

#!/bin/bash

# Check if Claude is already installed
if command -v claude &> /dev/null; then
    echo "✨ Claude Code is already installed"
else
    if ! command -v npm &> /dev/null; then
        echo "⚠️ Skipping claude code install, npm not found"
        return 0
    else
        echo "🚀 Installing Claude Code..."
        npm install -g @anthropic-ai/claude-code
    fi
fi

# Set theme preference
claude config set -g theme dark

# Copy Claude config from mounted secret
DEST="$HOME/.claude.json"
if [ ! -f "$DEST" ]; then
    echo "📋 Copying Claude config from root..."
    sudo cp /root/.claude.json "$DEST" 2>/dev/null || {
        echo "ℹ️ No Claude config found in root, skipping copy"
        return 0
    }
fi

# Fix permissions
sudo chown "$(id -u):$(id -g)" "$DEST" 2>/dev/null

# Set up Claude settings with pre-approved permissions
echo "⚙️ Setting up Claude settings..."
mkdir -p ~/.claude
if [ ! -f ~/.claude/settings.json ]; then
    cat > ~/.claude/settings.json << 'EOF' { "permissions": { "allow": [ "Read(**)", "Edit(**)", "Bash(ls:*)", "Bash(grep:*)", "Bash(git status:*)", "Bash(git diff:*)", "Bash(git add:*)", "Bash(git commit:*)", "Bash(npm test:*)", "Bash(yarn test:*)", "WebFetch(domain:*.gitpod.io)" ], "deny": [] } } EOF
    echo "✅ Created ~/.claude/settings.json"
fi

1. Configure Gitpod to use your dotfiles:
   • Go to gitpod.io/user/preferences
   • Set your dotfiles repository URL
   • Ensure the script gets sourced (e.g., from .bashrc or .bash_aliases)

Step 4: Launch multiple environments

Now you can create multiple Gitpod environments, each running its own Claude Code instance.

You can launch new environments directly from the Gitpod UI or from the terminal. Below is an example script that will launch a repository and start Claude automatically.

#!/bin/bash
BEFORE_IDS=$(gitpod environment list --field id)
gitpod environment create \
    --class-id <your-environment-class-id>
    https://github.com/<your-org>/<your-repository>
AFTER_IDS=$(gitpod environment list --field id)
ENV_ID=$(comm -13 <(echo "$BEFORE_IDS" | sort) <(echo "$AFTER_IDS" | sort))
gitpod environment ssh $ENV_ID -- -t "claude; exec bash"

The future runs in parallel

The draw of parallel agents is real—but so are the limits of our current tools. Claude Code is powerful, but it wasn’t built for concurrency. Gitpod gives it the scaffolding it needs to grow. Each agent gets its own CPU, memory, and git state. No conflicts. No collisions. Just parallel execution at scale.

And if you love Claude Code, you’ll love Ona too. Ona is Gitpod’s software engineering agent. It runs in parallel, has shared context of all your repos, and works in full environments.

Get started with Gitpod and Claude Code today or request a trial of Ona.