ZERG

Zero-Effort Rapid Growth — A parallel Claude Code execution system that coordinates multiple Claude Code instances to build software features simultaneously. ZERG auto-detects your tech stack, fetches security rules, generates dev containers, breaks features into atomic tasks with exclusive file ownership, and launches a swarm of zerglings to execute them in parallel.

Why I Built This

Every time I started a new project with Claude Code, I found myself doing the same setup work over and over:

Secure coding rules. Manually writing OWASP guidelines, language-specific security patterns, and Docker hardening rules into CLAUDE.md so Claude would actually follow them. Every. Single. Time.
Dev containers. Configuring Dockerfiles, devcontainer.json, MCP servers, and post-create scripts so workers could run in isolated environments.
Project scaffolding. Setting up directory structures, config files, linting, pre-commit hooks — the same boilerplate for every repo.
Parallel execution. Claude Code is powerful, but it's one instance. For any feature with 10+ files, I'd spend hours watching a single agent work sequentially through tasks that could run in parallel.
Context rot. The bigger the feature, the more Claude forgets. By the time it's working on file 15, it's lost track of the decisions it made in file 3.

I got tired of the repetition. So I built a system that handles all of it:

ZERG auto-detects your stack and fetches stack-specific security rules (OWASP Top 10 2025, Python, JavaScript, Docker) from TikiTribe/claude-secure-coding-rules — no manual CLAUDE.md maintenance.

ZERG generates dev containers with your detected languages, MCP server configs, and authentication baked in — workers spin up in isolated Docker environments with a single flag.

ZERG breaks features into parallel tasks with exclusive file ownership, so 5-10 Claude Code instances work simultaneously without merge conflicts. A feature that takes one agent 2 hours takes a swarm 20 minutes.

ZERG solves context rot through spec-driven execution. Workers read specification files, not conversation history. Every zergling is stateless — crash one, restart it, and it picks up exactly where it left off.

ZERG engineers context per worker. Large command files are split into core (~30%) and reference (~70%) segments. Security rules are filtered by file extension. Each task gets a scoped context budget instead of loading entire spec files. Workers use fewer tokens and stay focused.

The goal was simple: stop repeating myself and start shipping faster. ZERG is the result of wanting one command to set up security, containers, scaffolding, and parallel execution — then getting out of the way.

Quick Start (5 minutes)

# Install ZERG
pip install zerg-ai

# Or install from source (contributors)
git clone https://github.com/rocklambros/zerg.git && cd zerg
pip install -e ".[dev]"
zerg install  # Install slash commands into your project

# Inside Claude Code:
/zerg:init                    # Initialize project
/zerg:plan my-feature         # Capture requirements
/zerg:design                  # Generate architecture
/zerg:rush --workers=5        # Launch the swarm

Installation

Prerequisites

| Requirement | Check Command | Purpose | |-------------|---------------|---------| | Python 3.12+ | python --version | ZERG runtime | | Git 2.x+ | git --version | Worktrees, branching | | Claude Code CLI | claude --version | Worker instances | | Docker 20.x+ | docker info | Container mode (optional) |

Step 1: Install

pip install zerg-ai

Step 1b: Install from Source (Contributors)

git clone https://github.com/rocklambros/zerg.git
cd zerg
pip install -e ".[dev]"

Step 2: Install Pre-commit Hooks (Contributors)

pre-commit install

Step 3: Verify Installation

zerg --help

Step 4: Install Slash Commands

ZERG ships with 26 slash commands. Install them into your project:

cd your-project
zerg install          # Install to .claude/commands/

Once installed, use /zerg:* commands inside any Claude Code session. Every command also has a /z: shortcut (e.g., /z:plan, /z:rush).

Tutorial: Your First ZERG Project

This tutorial walks through building a "Minerals Store" — a Starcraft 2 themed ecommerce API — using all ZERG phases. You'll learn why each phase exists and see what the conversations with ZERG actually look like.

Initialization: Setting Up Your Project

Before ZERG can coordinate parallel workers, it needs to understand your project and create the infrastructure for safe parallel execution. The initialization phase handles detection, configuration, and scaffolding automatically.

Create a new directory and enter it:

mkdir minerals-store && cd minerals-store

Inside Claude Code, run the init command:

/zerg:init

ZERG begins by analyzing your project:

ZERG: Scanning project structure...
      Detected: Empty project (no source files)
      Starting Inception wizard for new project setup.

ZERG: What type of project are you building?
YOU:  A Python REST API using FastAPI.

ZERG: What testing framework should I configure?
YOU:  pytest with coverage reporting.

ZERG: Creating infrastructure...
      ✓ .zerg/config.yaml — worker settings, quality gates
      ✓ .devcontainer/ — container mode configuration
      ✓ .gsd/ — specs and task graphs directory
      ✓ Security rules fetched (OWASP Top 10, Python rules)

Initialization matters because parallel workers need a shared understanding of project structure, coding standards, and quality gates. Without this foundation, workers would make inconsistent decisions about file organization, testing patterns, and error handling.

Brainstorming: Discovering What to Build (Optional)

Sometimes you know exactly what you want to build. But often, especially for new features, you have a vague idea that needs refinement. The brainstorming phase helps you discover and articulate requirements before committing to implementation.

If your requirements are unclear, start with Socratic discovery:

/zerg:brainstorm --socratic

ZERG asks probing questions across three rounds:

ZERG: Let's discover what you want to build. I'll ask questions to help
      clarify your vision.

      ROUND 1 — Problem Space

ZERG: What problem does the minerals store solve for users?
YOU:  Users need to browse and purchase mineral products through a REST API.

ZERG: Who are the primary users? How will they interact with the system?
YOU:  Game developers integrating mineral purchases into their Starcraft-themed games.

ZERG: What happens if this problem isn't solved? What workarounds exist?
YOU:  Developers would build custom solutions, wasting time on commodity functionality.

      ROUND 2 — Solution Shape

ZERG: What would an ideal solution look like from a user's perspective?
YOU:  Simple REST endpoints for catalog browsing, cart management, and checkout.

ZERG: What are the absolute must-haves versus nice-to-haves?
YOU:  Must-have: products, cart, orders. Nice-to-have: recommendations, reviews.

ZERG: What should this explicitly NOT do?
YOU:  No payment processing — that's handled by a separate payment service.

      ROUND 3 — Constraints

ZERG: What technical constraints exist?
YOU:  Must use PostgreSQL for persistence. Stateless for horizontal scaling.

ZERG: What's the expected scale and performance requirement?
YOU:  100 requests/second initially, with room to scale to 1000.

ZERG: Synthesizing insights...
      ✓ Output: .gsd/specs/brainstorm-session.md

Brainstorming matters because unclear requirements lead to rework. By asking structured questions, ZERG helps you think through edge cases and constraints before any code is written. The output becomes input for the planning phase.

Planning: Capturing What You Want to Build

Before ZERG can help build your feature, it needs to understand what you're trying to create in concrete terms. The planning phase transforms brainstorming insights (or your existing mental model) into a structured requirements document.

Start the planning conversation:

/zerg:plan minerals-store

ZERG begins capturing requirements:

ZERG: Let's capture the requirements for 'minerals-store'.

ZERG: What problem does the minerals store solve for users?
YOU:  Users need to browse and purchase mineral products through a REST API.

ZERG: Describe your ideal solution in 2-3 sentences.
YOU:  A FastAPI service with endpoints for products, cart, and orders.
      Products have names, descriptions, prices, and stock counts.
      Carts persist across sessions and convert to orders at checkout.

ZERG: What are the non-negotiable requirements?
YOU:  1. Product catalog with CRUD operations
      2. Shopping cart that persists items
      3. Order placement with stock validation
      4. All endpoints return JSON with proper error codes

ZERG: What should this feature explicitly NOT include?
YOU:  No payment processing, no user authentication (handled elsewhere),
      no email not

Zerg

Install / Use

README