How to Use claude-swarm | Running Multiple Claude Code Sessions in Parallel

What Is claude-swarm — The Background of Multi-Session Coordination

Once you start making full use of Claude Code, parallel workflows — running multiple sessions simultaneously — can seem effective for large-scale refactoring or implementing multiple features at once. However, several problems tend to emerge in practice:

• When session A is modifying the backend, session B rewrites the same file, causing conflicts
• One session doesn't know about the interface definitions decided by the other, leading to type mismatches
• Multiple sessions try to git push simultaneously, causing conflicts

claude-swarm resolves all three of these problems as a unified "coordination layer." It uses a SQLite database as shared storage, providing a mechanism to track in real time which session is responsible for what.

Version 0.3.3 was released on April 9, 2026. It is published as open-source software under the MIT license and runs on Python 3.11 or higher (source: https://pypi.org/project/claude-swarm/).

Installation and Requirements

pip install claude-swarm

The requirements for installation are as follows:

• Python 3.11 or higher (does not work on 3.10 or below)
• An environment where pip is available
• A repository with Git set up

After installation, if you can verify the version with claude-swarm --version, setup is complete. Internally, a SQLite database is automatically created, managing inter-session state across 6 tables (sessions, messages, reviews, git_locks, file_claims, shared_contexts). No special server or daemon is required — everything runs on the local filesystem.

Managing Shared Context Across Sessions

The core feature of claude-swarm is shared context. When one session records architectural decisions or API interface definitions, other sessions automatically receive them the next time they run sync.

Adding and Syncing Context

To record context, use the following command:

# Session A: Record the decision to use JWT authentication
claude-swarm context add "Using JWT authentication. Bearer token in the Authorization header"

To receive context in another session, run sync:

# Session B: Receive context and heartbeats from other sessions
claude-swarm sync --session B

sync handles message reception, shared context loading, and heartbeat sending all in a single command. Running it periodically keeps you informed of the status of other sessions.

How to Use the 5 Core Commands

The main commands provided by claude-swarm can be organized into 5 categories.

1. Inter-Session Messaging

# Send a question from session A to session B
claude-swarm message B "Can you share type information for the User model?"

Bidirectional messaging similar to a chat is possible, allowing you to send questions, confirmations, and notifications to other sessions.

2. File Claims (Exclusive Ownership)

# Session A: Declare exclusive edit rights for src/auth.py
claude-swarm claim src/auth.py --session A

This is a mechanism for declaring "ownership" before editing a file. If another session tries to claim the same file, a warning is issued, preventing conflicts before they occur.

3. Requesting a Peer Review

# Request session B to review session A's changes
claude-swarm review request --from A --to B

This is a gate feature that requires approval from another session before merging. Even in parallel development across multiple sessions, it prevents important changes from being integrated without a review.

4. Git-Locked Push

# Push safely via SQLite lock
claude-swarm push --session A

This resolves the problem of multiple sessions trying to push simultaneously using SQLite's locking mechanism. Other sessions wait in a queue until the first session completes its push.

5. Listing Sessions

claude-swarm sessions list

This lets you view a list of currently active sessions, along with the files each session has claimed and the time of their last sync.

Preventing Edit Conflicts with File Claims

File claims are one of the most practically useful features in claude-swarm. When multiple Claude Code sessions are editing the same codebase, "who is responsible for which file" is the biggest source of collisions.

The claim workflow is as follows:

1. Before starting edits, run claude-swarm claim <file path> --session <session name>
2. If another session tries to claim the same file, a warning appears indicating that ownership already exists
3. Once editing is complete, release ownership with claude-swarm release <file path> --session <session name>

This mechanism ensures that even when a frontend session, a backend session, and an infrastructure session are working in parallel, file-level conflicts do not occur.

Peer Review Feature — Approval Flow Before Merging

Peer review is one of claude-swarm's distinctive features. Just as in team code development, it automates a flow where another session reviews and approves changes before they are merged.

A typical use case is when a backend session finishes implementing authentication logic and asks a frontend session to verify the consistency of the API interface. Session A's changes remain in a pending state until session B returns its approval.

# Session B: Confirm review request and approve
claude-swarm review approve --from B --to A

Peer review results are recorded in SQLite's review table, so you can later track "which session approved and when."

Resolving Push Conflicts with the Git Lock Mechanism

The biggest risk of running multiple Claude Code sessions simultaneously is git push conflicts. If sessions A and B try to push at the same time, one of them will fail and a rebase will be necessary.

claude-swarm's push command resolves this problem by routing through SQLite's lock table. The session requesting a push writes a lock to SQLite, and other sessions wait until that lock is released. The lock hold duration is configurable, allowing deadlocks caused by long-running processes to be avoided as well.

Differences from Claude Code's Built-in Sub-Agent Feature

claude-swarm and Claude Code's built-in sub-agent feature are often confused, but they operate at fundamentally different layers.

Claude Code's sub-agent is for "a single session to internally split and process tasks in parallel." claude-swarm is for "multiple independent sessions cooperating to modify a single codebase" — understanding it this way makes the distinction clear (source: https://pypi.org/project/claude-swarm/).

Notes on Adoption and Current Limitations

Here are key points to be aware of before integrating claude-swarm into a production workflow.

Python 3.11 or higher is required. It does not work on 3.10 or below. If your existing Python environment is older, you will need to set up 3.11 or higher using pyenv or a virtual environment.

SQLite is local-only. Since claude-swarm manages state using a local SQLite database, it cannot sync in real time with sessions running on a different remote machine. At this point, it is designed for parallel sessions on the same machine.

Version 0.3.3 is in early development. This tool was just released as open-source software, and its API and command specifications may change. It is recommended to check the changelog before using it in a production environment.

Subscriptions are required for each parallel Claude Code session. claude-swarm merely provides a coordination layer; separate access to Claude Code itself is required. Prepare an environment that accommodates the number of parallel sessions needed.

Summary

claude-swarm is a CLI tool that resolves the greatest challenges of running multiple Claude Code sessions in parallel — file conflicts, context disconnection, and Git conflicts — through a SQLite-based coordination layer. It combines simple installation via pip install claude-swarm with 5 practical features: shared context, file claims, peer review, and Git locks.

For developers who want to leverage parallel sessions for large-scale refactoring or simultaneous implementation of multiple features, combining claude-swarm with Claude Code's sub-agents creates a powerful parallel development environment. While version 0.3.3 is still in early development, it is a noteworthy option that can be tried immediately with a Python 3.11 environment.