Getting Started with Geneclaw

This guide walks you from installation to your first dry-run evolution proposal. All steps are safe by design — nothing is applied to your codebase until you explicitly approve it.

Safety First

Every command in this guide runs in dry-run mode by default. No files are modified until you pass --apply after explicit review.

Prerequisites

  • Python 3.9 or later
  • pip (or uv / pipx)
  • A git-initialized project directory
  • Optional: An LLM provider API key (for LLM-powered diagnosis; heuristic mode works without it)

Step 1 — Install

# Using pip
pip install geneclaw

# Or with uv (faster)
uv pip install geneclaw

# Or with pipx (isolated environment)
pipx install geneclaw

Step 2 — Run Doctor (Read-Only Health Check)

The doctor command is always safe to run. It performs a read-only health check of your environment and configuration — it never modifies anything.

geneclaw doctor

Expected output:

✓ nanobot connection OK        (v0.3.1)
✓ Event store writable         (data/events.jsonl)
✓ Gatekeeper config loaded     (geneclaw.toml)
✓ Git repository detected      (.git/)
✓ pytest available             (7.4.0)
⚠ No allowlist configured — using safe defaults

Step 3 — Create Configuration

Create a geneclaw.toml in your project root. Start with a minimal allowlist — only allow Geneclaw to touch your prompts and config directories.

# geneclaw.toml

[agent]
name = "my-agent"
repo = "."             # path to your git repo
nanobot_config = "nanobot.toml"

[gatekeeper]
# Only touch these paths (start minimal)
allowlist = ["src/prompts/", "config/"]
denylist  = [".env", "secrets/", "*.key", "*.pem"]
max_diff_lines = 200
secret_scan = true

[store]
events_path = "data/events.jsonl"
redact_secrets = true

[safety]
dry_run = true    # always true by default
require_tests = true
test_command = "pytest tests/"

[diagnosis]
mode = "heuristic"   # or "llm" if you have an API key
# llm_provider = "openai"  # optional

Step 4 — Generate Your First Proposal (Dry Run)

With nanobot running and some agent events in the store, you can generate a dry-run evolution proposal. This does not modify any files.

# Generate a dry-run proposal
geneclaw evolve --dry-run

# View the proposal
geneclaw report --last 1 --format table

# View as JSON
geneclaw report --last 1 --format json

The output will show you the proposed change as a unified diff, a risk score (0–100), and a human-readable rationale.

Step 5 — Review and Gate

Before applying, run the Gatekeeper check explicitly to confirm the proposal passes all five safety layers:

# Run the 5-layer gatekeeper check
geneclaw gate --proposal proposals/gep-001.json

# Expected gate output:
# [1/5] ✓ Path allowlist/denylist check passed
# [2/5] ✓ Diff size check passed (48 lines ≤ 200)
# [3/5] ✓ Secret scan passed (no secrets found)
# [4/5] ✓ Code pattern check passed
# [5/5] ✓ Dry-run pytest gate passed (12/12 tests)
# ✓ GATE PASSED — proposal is safe to apply

Step 6 — Apply (Explicit Human Approval)

Only after reviewing the proposal and confirming the gate passed, apply the change with --apply:

# Apply with explicit human approval
geneclaw apply --proposal proposals/gep-001.json --apply

# If tests fail after apply, rollback immediately
geneclaw apply --rollback

Next Steps