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.
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.
# 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| 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) |
pip install zerg-aigit clone https://github.com/rocklambros/zerg.git
cd zerg
pip install -e ".[dev]"pre-commit installzerg --helpZERG 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).
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.
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-storeInside 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.
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.
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 notifications.
ZERG: Generating requirements document...
✓ .gsd/specs/minerals-store/requirements.md (Status: DRAFT)
Review and change status to APPROVED when ready for design.
Planning matters because ZERG workers are stateless — they don't remember previous conversations. The requirements document becomes the shared source of truth that every worker reads. Without clear requirements, workers would interpret the feature differently, leading to inconsistent implementations.
With approved requirements, ZERG can design the technical architecture. This phase analyzes your codebase, creates component designs, and — critically — breaks work into atomic tasks with exclusive file ownership.
First, mark your requirements as approved by editing .gsd/specs/minerals-store/requirements.md and changing Status: DRAFT to Status: APPROVED.
Then generate the design:
/zerg:design
ZERG analyzes and generates architecture:
ZERG: Reading approved requirements...
Feature: minerals-store
Non-negotiables: 4 requirements identified
Non-goals: 3 exclusions noted
ZERG: Analyzing existing codebase...
Project type: Python (FastAPI)
Patterns detected: Repository pattern, Pydantic models
Test location: tests/
ZERG: Generating architecture...
Components:
├── models/ — Pydantic schemas, SQLAlchemy models
├── routers/ — FastAPI route handlers
├── services/ — Business logic layer
└── repositories/ — Data access layer
ZERG: Creating task graph...
Level 1: Foundation (4 tasks, parallelizable)
├── TASK-001: Create Product model and schema
├── TASK-002: Create Cart model and schema
├── TASK-003: Create Order model and schema
└── TASK-004: Create database migrations
Level 2: Data Access (3 tasks, parallelizable)
├── TASK-005: Product repository
├── TASK-006: Cart repository
└── TASK-007: Order repository
Level 3: Business Logic (3 tasks, parallelizable)
└── ...
✓ .gsd/specs/minerals-store/design.md
✓ .gsd/specs/minerals-store/task-graph.json
Design matters because parallel execution requires careful planning. Each task declares exclusive file ownership — which files it creates, modifies, and reads. This prevents merge conflicts when multiple workers run simultaneously. Without this upfront design, workers would step on each other's changes.
With the task graph ready, you can launch parallel workers. Each worker claims a task, executes it in an isolated git worktree, and reports results. The orchestrator manages task distribution and level progression.
Launch the swarm:
/zerg:rush --workers=4
Real output as workers execute:
ZERG: Starting rush execution...
Feature: minerals-store
Task graph: 12 tasks across 4 levels
Workers requested: 4
Creating git worktrees...
✓ .zerg/worktrees/worker-1
✓ .zerg/worktrees/worker-2
✓ .zerg/worktrees/worker-3
✓ .zerg/worktrees/worker-4
=== LEVEL 1 (4 tasks) ===
[Worker-1] Claimed TASK-001: Create Product model
[Worker-2] Claimed TASK-002: Create Cart model
[Worker-3] Claimed TASK-003: Create Order model
[Worker-4] Claimed TASK-004: Database migrations
[Worker-1] ✓ TASK-001 complete (47s)
[Worker-3] ✓ TASK-003 complete (52s)
[Worker-2] ✓ TASK-002 complete (58s)
[Worker-4] ✓ TASK-004 complete (63s)
Running quality gates...
✓ ruff check . — passed
✓ pytest tests/ — passed (4 tests)
Merging Level 1 branches...
✓ All branches merged to feature/minerals-store
=== LEVEL 2 (3 tasks) ===
...
Rush matters because parallel execution is ZERG's core value proposition. A feature that takes one agent 2 hours takes a swarm 20 minutes. But parallelism requires infrastructure — worktrees for isolation, task claiming for coordination, quality gates for verification, and automated merging for integration.
Execution modes let you choose the isolation level:
| Mode | Flag | When to Use |
|---|---|---|
| Task | --mode task |
Default. Runs as Claude Code tasks. Fast, good for development. |
| Subprocess | --mode subprocess |
Runs as separate processes. More isolation than task mode. |
| Container | --mode container |
Full Docker isolation. Best for production or untrusted code. |
While workers execute, you can monitor progress in real-time. The status command shows task states, worker assignments, and quality gate results.
Watch execution progress:
/zerg:status --watch
Real-time output:
╔══════════════════════════════════════════════════════════════╗
║ ZERG Status: minerals-store ║
╠══════════════════════════════════════════════════════════════╣
║ Progress: Level 2 of 4 | Tasks: 7/12 complete ║
╠══════════════════════════════════════════════════════════════╣
║ WORKERS ║
║ ├── Worker-1: TASK-005 (Product repository) — running 23s ║
║ ├── Worker-2: TASK-006 (Cart repository) — running 31s ║
║ ├── Worker-3: TASK-007 (Order repository) — running 28s ║
║ └── Worker-4: idle (no tasks at current level) ║
╠══════════════════════════════════════════════════════════════╣
║ RECENT EVENTS ║
║ 14:23:07 Level 1 quality gates passed ║
║ 14:23:12 Level 1 branches merged ║
║ 14:23:15 Level 2 started (3 tasks) ║
╚══════════════════════════════════════════════════════════════╝
For detailed worker activity, use the logs command:
/zerg:logs --follow # Stream all workers
/zerg:logs --worker 2 # Specific worker
/zerg:logs --aggregate # All workers sorted by time
After all levels complete, ZERG provides commands to verify the implementation meets requirements and quality standards.
Review code against the spec:
/zerg:review --mode full
Run tests with coverage:
/zerg:test --coverage
Scan for security vulnerabilities:
/zerg:security --preset owasp
Quality matters because parallel execution can introduce subtle bugs — especially at integration points between tasks. Automated review, testing, and security scanning catch issues before they reach production.
With quality verified, merge your feature branch to main:
/zerg:git --action ship
Output:
ZERG: Preparing to ship minerals-store...
Pre-ship checks:
✓ All tasks complete (12/12)
✓ Quality gates passed
✓ No uncommitted changes
Merging feature/minerals-store → main...
✓ Merge complete
✓ Feature branch cleaned up
🎉 minerals-store shipped successfully!
Other git operations available:
| Action | Command | Purpose |
|---|---|---|
| Commit | /zerg:git commit |
Commit current changes with generated message |
| Create PR | /zerg:git --action pr |
Open pull request for review |
| Ship | /zerg:git --action ship |
Merge to main after verification (--admin to bypass branch protection) |
| Full workflow | /zerg:git --action finish |
PR → review → merge in one command |
| Command | Purpose |
|---|---|
/zerg:init |
Initialize ZERG infrastructure |
/zerg:brainstorm |
Feature discovery with interactive questioning |
/zerg:plan <feature> |
Capture requirements |
/zerg:design |
Generate architecture and task graph |
/zerg:rush |
Launch parallel zerglings |
| Command | Purpose |
|---|---|
/zerg:status |
Real-time progress dashboard |
/zerg:logs |
Stream, filter, aggregate worker logs |
/zerg:stop |
Stop workers gracefully or forcefully |
/zerg:retry |
Retry failed or blocked tasks |
/zerg:merge |
Manually trigger level merge |
/zerg:cleanup |
Remove ZERG artifacts |
| Command | Purpose |
|---|---|
/zerg:build |
Build orchestration with error recovery |
/zerg:test |
Execute tests with coverage |
/zerg:analyze |
Static analysis, complexity metrics |
/zerg:review |
Two-stage code review |
/zerg:security |
Vulnerability scanning |
/zerg:refactor |
Automated code improvement |
| Command | Purpose |
|---|---|
/zerg:git |
Git operations (commit, PR, ship, bisect, etc.) |
/zerg:debug |
Deep diagnostic investigation |
/zerg:worker |
Internal zergling execution protocol |
/zerg:plugins |
Plugin system management |
| Command | Purpose |
|---|---|
/zerg:document |
Generate component documentation (--tone educational|reference|tutorial) |
/zerg:index |
Generate project documentation wiki |
/zerg:estimate |
Effort estimation with PERT intervals |
/zerg:explain |
Educational code explanations |
/zerg:select-tool |
Intelligent MCP tool routing |
ZERG is configured via .zerg/config.yaml:
version: "1.0"
project_type: python
workers:
default_count: 5
max_count: 10
timeout_seconds: 3600
quality_gates:
lint:
command: "ruff check ."
required: true
test:
command: "pytest"
required: true
plugins:
context_engineering:
enabled: true
command_splitting: true| Resource | Description |
|---|---|
| Wiki: Home | Overview and quick navigation |
| Wiki: Command Reference | All 26 commands with flags and examples |
| Wiki: Tutorial | Complete minerals-store walkthrough |
| Wiki: Configuration | Config files and tuning options |
| Wiki: Architecture | System design and module reference |
| Wiki: Plugins | Quality gates, hooks, custom launchers |
| Wiki: Context Engineering | Token optimization techniques |
| Wiki: Troubleshooting | Common issues and solutions |
| ARCHITECTURE.md | Detailed system architecture |
| CONTRIBUTING.md | Development setup and PR process |
| SECURITY.md | Vulnerability reporting |
| Discussions | Questions, ideas, and community chat |
| Concept | Description |
|---|---|
| Spec as Memory | Zerglings read spec files, not conversation history. Stateless and restartable. |
| Exclusive File Ownership | Each task owns specific files. No merge conflicts within a level. |
| Levels | Tasks grouped by dependencies. Level N completes before Level N+1. |
| Verification Commands | Every task has automated verification. Pass or fail, no subjectivity. |
| Context Engineering | Per-task context scoping minimizes token usage by 30-50%. |
By default, ZERG tracks the active feature in .gsd/.current-feature. This works well for single-feature development, but causes cross-epic interference when two terminals work on different features simultaneously.
Export ZERG_FEATURE in each terminal to scope all commands to that feature:
# Terminal 1
export ZERG_FEATURE=epic-auth
/z:plan epic-auth
/z:design
/z:rush --workers=5
# Terminal 2
export ZERG_FEATURE=epic-payments
/z:plan epic-payments
/z:design
/z:rush --workers=5The ZERG_FEATURE env var takes priority over the .gsd/.current-feature file. Each terminal's commands operate exclusively on its own feature with no cross-contamination.
When /z:rush starts, it creates .gsd/specs/{feature}/.lock. If another terminal tries to rush the same feature, it receives a warning about the concurrent session. This prevents accidental double-execution of the same feature.
Single-epic users do not need to change anything. The ZERG_FEATURE env var is only required for parallel multi-epic workflows. Without it, ZERG falls back to .gsd/.current-feature as before.
| Problem | Solution |
|---|---|
| Zerglings not starting | Check Docker (docker info), API key, port availability |
| "No active feature" | Run /zerg:plan <feature> first |
| "Task graph not found" | Run /zerg:design first |
| Task stuck | /zerg:debug to diagnose, /zerg:retry to retry |
| Need to restart | /zerg:rush --resume continues from checkpoint |
MIT — see LICENSE for full text.