Getting Started›Quick Start

Quick Start

Three commands to evolve your first function. From install to optimized code in under 60 seconds.

Three commands

pip install hezgene
hezgene init
hezgene run src/

That is it. Your functions now have mutants competing. By default, winners are written to .hezgene/sandbox/ — add --apply when you want to deploy changes to your source files.

Common commands (80/20)

hezgene init                          # Initialize in a project
hezgene run src/utils.py              # Evolve a file (sandbox mode)
hezgene run src/utils.py:func         # Evolve a specific function
hezgene run --target slowest          # Auto-find and evolve worst function
hezgene run src/ --llm                # Include AI-powered mutations
hezgene run src/utils.py --apply      # Deploy directly (not just sandbox)
hezgene verify                        # Confirm evolved code matches original
hezgene freeze src/auth.py:verify     # Protect critical functions

Codebase Intelligence commands

hezgene health                        # Project Health Score
hezgene audit --apply                 # Unified master audit (auto-fix)
hezgene dead-code --apply             # Auto-delete unreachable code
hezgene dupes                         # Detect code duplication families
hezgene boundaries                    # Enforce architecture layers
hezgene trace <script.py>             # Hook runtime execution
hezgene deps --apply                  # Auto-delete unused dependencies
hezgene mcp                           # Start MCP Server for AI Agents

Quick demo

Run the built-in terminal demo to see a full evolution in action:

hezgene-demo

A short terminal walkthrough: original slow code → DNA extracted → mutants spawned → arena fight → winner announced → sandbox output → verification.

Try it now
The demo requires no LLM — it uses pure AST mutations and runs entirely locally.
‹ Previous
Installation
Install via pipx, uv, or npm
Design Philosophy
The principles behind evolution
Next ›