🧬 Geneclaw — Self-Evolving AI Agent Framework

geneclaw.ai · GitHub · Protocol Spec · Quickstart

Built on nanobot — adds closed-loop self-improvement via the Geneclaw Evolution Protocol (GEP)

Geneclaw extends the ultra-lightweight nanobot AI agent with a self-evolution engine — enabling the agent to observe its own failures, diagnose root causes, propose constrained fixes, and safely apply them behind a multi-layered gatekeeper.

Everything is dry-run by default. Nothing is applied without explicit human approval.

📖 Visit geneclaw.ai for documentation, demos, and community resources.

Key Capabilities

Capability	Description
Observability	JSONL event recording for every agent interaction (inbound, tools, errors, outbound)
Diagnosis	Heuristic failure analysis + optional LLM-assisted root cause identification
Evolution Proposals	Structured JSON proposals with unified diffs, risk levels, and rollback plans
Gatekeeper	5-layer safety validation (allowlist, denylist, diff size, secret scan, code pattern detection)
Safe Apply	Git-branched patch application with automated test execution and rollback on failure
Autopilot	Configurable multi-cycle evolution loop with risk-based auto-approve
Dashboard	Read-only Streamlit web dashboard for evolution audit, timeline, and benchmark visualisation
Benchmarks	Pipeline performance measurement with synthetic workloads and JSONL persistence
Event Store	Append-only evolution lifecycle logging with secret redaction
Reporting	Aggregated pipeline statistics (table + JSON output)
Doctor	Read-only health checks with actionable suggestions

Architecture

                     Geneclaw Evolution Protocol (GEP v0)
    ┌─────────────────────────────────────────────────────────────┐
    │                                                             │
    │   Observe ──→ Diagnose ──→ Propose ──→ Gate ──→ Apply      │
    │      │            │            │          │         │       │
    │   recorder    evolver      evolver    gatekeeper  apply     │
    │   (JSONL)    (heuristic    (JSON +    (5 checks)  (git +   │
    │               + LLM)       diff)                  pytest)  │
    │      │            │            │          │         │       │
    │      └────────────┴────────────┴──────────┴─────────┘       │
    │                         │                                   │
    │                    event_store                               │
    │                    (audit log)                               │
    │                                                             │
    ├─── autopilot   (multi-cycle controller)                     │
    ├─── dashboard   (Streamlit read-only visualisation)          │
    ├─── benchmarks  (performance measurement)                    │
    ├─── doctor      (health checks)                              │
    └─── report      (statistics aggregation)                     │
                                                                  │
    ┌─────────────────────────────────────────────────────────────┐
    │                  nanobot (upstream)                          │
    │   agent/loop.py ←→ channels ←→ providers ←→ tools           │
    └─────────────────────────────────────────────────────────────┘

Project Structure

Clawland-AI/Geneclaw
├── geneclaw/                      # GEP v0 evolution engine
│   ├── __init__.py                # Package metadata (v0.1.0)
│   ├── models.py                  # RunEvent, EvolutionProposal, EvoEvent
│   ├── redact.py                  # Secret redaction (regex-based)
│   ├── recorder.py                # JSONL run event recorder
│   ├── evolver.py                 # Heuristic + LLM proposal generator
│   ├── gatekeeper.py              # Safety validation (5 checks)
│   ├── apply.py                   # Git-branched diff application
│   ├── event_store.py             # Append-only evolution event log
│   ├── report.py                  # Statistics aggregation
│   ├── doctor.py                  # Health checks
│   ├── autopilot.py               # Multi-cycle evolution controller
│   ├── benchmarks.py              # Pipeline performance benchmarks
│   ├── cli.py                     # Typer CLI subcommands
│   └── dashboard/                 # Streamlit dashboard (read-only)
│       ├── app.py                 # Streamlit entry point
│       ├── loader.py              # Data loading, filtering, redaction
│       └── views/                 # Overview, Timeline, Audit, Benchmarks
├── nanobot/                       # Upstream agent framework (HKUDS/nanobot)
│   ├── agent/                     # Core agent loop + tools
│   ├── channels/                  # Chat platform integrations
│   ├── providers/                 # LLM providers
│   ├── config/                    # Configuration schema
│   └── cli/                       # Main CLI entry point
├── tests/                         # 123 tests across 8 files
│   ├── test_geneclaw_recorder.py
│   ├── test_geneclaw_evolver.py
│   ├── test_geneclaw_gatekeeper.py
│   ├── test_geneclaw_doctor.py
│   ├── test_geneclaw_events.py
│   ├── test_geneclaw_autopilot.py
│   └── test_geneclaw_dashboard.py
├── docs/
│   ├── specs/GEP-v0.md            # Protocol specification
│   ├── quickstart/Geneclaw-Runbook.md
│   ├── ops/
│   │   ├── github-governance.md   # Branch protection & PR checklist
│   │   ├── release-runbook.md     # Tagging & release process
│   │   ├── llm-provider-setup.md  # Secure LLM provider configuration
│   │   ├── first-real-proposal.md # Guide: first non-no-op proposal
│   │   ├── upstream-sync.md       # Upstream merge strategy
│   │   ├── dashboard-runbook.md   # Dashboard operations
│   │   └── first-live-run-*.md    # Audit records
│   └── devlog/                    # Daily development logs
└── .github/
    ├── workflows/ci.yml           # CI pipeline
    └── pull_request_template.md

Install

From source (recommended)

git clone https://github.com/Clawland-AI/Geneclaw.git
cd Geneclaw
pip install -e ".[dev]"

With Dashboard support

pip install -e ".[dev,dashboard]"

Add upstream remote (for syncing with nanobot)

git remote add upstream https://github.com/HKUDS/nanobot.git

Quick Start

1. Initialize

nanobot onboard

2. Enable Geneclaw

Add or merge into ~/.nanobot/config.json:

{
  "geneclaw": {
    "enabled": true,
    "redactEnabled": true,
    "allowApplyDefault": false,
    "allowlistPaths": ["geneclaw/", "docs/"],
    "denylistPaths": [".env", "secrets/", ".git/", "config.json"],
    "maxPatchLines": 500
  }
}

3. Verify

nanobot geneclaw doctor

4. Chat (generates run events)

nanobot agent -m "Hello, what tools do you have?"

5. Generate evolution proposal

nanobot geneclaw evolve --dry-run

6. View statistics

nanobot geneclaw report

7. Launch Dashboard

nanobot geneclaw dashboard
# opens http://localhost:8501

CLI Reference

All commands are under nanobot geneclaw:

Command	Description
`nanobot geneclaw doctor`	Health checks — config, paths, permissions
`nanobot geneclaw status`	Current state — enabled, sessions, last run
`nanobot geneclaw evolve --dry-run`	Generate evolution proposal (dry-run default)
`nanobot geneclaw evolve --apply`	Generate and apply proposal (requires config)
`nanobot geneclaw apply <file.json>`	Apply a saved proposal file
`nanobot geneclaw report`	Pipeline statistics (table)
`nanobot geneclaw report --format json`	Pipeline statistics (JSON)
`nanobot geneclaw autopilot`	Multi-cycle evolution loop
`nanobot geneclaw benchmark`	Pipeline performance benchmarks
`nanobot geneclaw benchmark --save`	Run benchmarks and persist results to JSONL
`nanobot geneclaw dashboard`	Launch Streamlit dashboard (read-only)

Autopilot Options

nanobot geneclaw autopilot \
  --max-cycles 5 \
  --cooldown 10 \
  --auto-approve low \
  --dry-run \
  --format table

Option	Default	Description
`--max-cycles`	3	Maximum evolution cycles
`--cooldown`	5.0	Seconds between cycles
`--auto-approve`	low	Risk threshold for auto-approve (`none`, `low`)
`--dry-run/--apply`	dry-run	Apply mode requires `allow_apply_default=true`
`--stop-on-failure/--continue`	stop	Halt on first apply failure
`--format`	table	Output format (`table`, `json`)

Benchmark Options

nanobot geneclaw benchmark \
  --event-counts 100,500,1000 \
  --gate-iterations 100 \
  --save \
  --format table

Dashboard Options

nanobot geneclaw dashboard \
  --port 8501 \
  --events /path/to/events.jsonl \
  --benchmarks /path/to/benchmarks.jsonl

The dashboard provides four read-only views: Overview (KPIs, risk distribution), Event Timeline (charts with time filters), Proposal Audit (per-proposal metadata inspection), and Benchmarks (performance trends).

Configuration

The geneclaw section in ~/.nanobot/config.json:

Field	Type	Default	Description
`enabled`	bool	`false`	Enable geneclaw observability + evolution
`logMaxChars`	int	`500`	Max chars per event preview
`redactEnabled`	bool	`true`	Redact secrets in all logs
`allowApplyDefault`	bool	`false`	Must be `true` to allow `--apply`
`allowlistPaths`	list	`["geneclaw/", "nanobot/", "tests/", "docs/"]`	Paths proposals may modify
`denylistPaths`	list	`[".env", "secrets/", ".git/", "config.json"]`	Paths that are always blocked
`maxPatchLines`	int	`500`	Maximum diff lines allowed

Safety Model

Geneclaw enforces multiple layers of protection:

1. Dry-Run Default

All commands default to --dry-run. Proposals are generated and validated but never applied without explicit --apply flag AND allowApplyDefault=true in config.

2. Gatekeeper (5 Checks)

Every proposal must pass all five checks before application:

Check	What it does
Path Allowlist	All `files_touched` must start with an allowed prefix
Path Denylist	No file may match a denied path (`.env`, `secrets/`, etc.)
Diff Size Limit	Line count must not exceed `maxPatchLines`
Secret Scan	Diff is scanned for API keys, tokens, PEM keys
Code Pattern Scan	Detects `eval()`, `exec()`, `os.system()`, `subprocess.call()`

3. Git Safety

Creates a dedicated evo/<timestamp>-<slug> branch
Runs git apply --check before actual application
Executes pytest -q after patching
Automatic rollback on test failure (branch deleted, previous state restored)

4. Secret Redaction

All event logs (run events + evolution events) pass through regex-based redaction before being written to disk. Patterns include API keys, tokens, passwords, PEM blocks, and Bearer tokens. The dashboard re-applies redaction at the display layer.

5. Recommended Allowlist Strategy

Start minimal and expand only after successful, reviewed evolution cycles:

Phase	Allowlist	When
Bootstrap	`geneclaw/`, `docs/`	Day 1
Expanded	+ `tests/`	After 5+ reviewed proposals
Full	+ `nanobot/`	After 20+ reviewed proposals

See docs/specs/GEP-v0.md Section 10 for the complete strategy.

Slash Command

When chatting with the agent, use /evolve to trigger an in-conversation evolution analysis:

You: /evolve
Bot: Evolution analysis started in background. Results will be posted shortly.
Bot: [Evolution Proposal: ...] (always dry-run, never auto-applies)

Data Layout

All runtime data lives under the nanobot workspace (~/.nanobot/workspace/):

~/.nanobot/workspace/geneclaw/
├── runs/                      # Run event logs (per session, per day)
│   └── <session_key>/
│       └── YYYYMMDD.jsonl
├── events/                    # Evolution lifecycle events
│   └── events.jsonl
├── proposals/                 # Generated proposals
│   └── proposal_YYYYMMDD_HHMMSS.json
└── benchmarks/                # Performance benchmark results
    └── benchmarks.jsonl

Testing

# Run all geneclaw tests
pytest tests/test_geneclaw_*.py -q

# Run full test suite
pytest -q

Current test coverage: 123 tests across 8 test files.

Development

Upstream Sync

git fetch upstream
git merge upstream/main --no-edit
# resolve conflicts if any

See docs/ops/upstream-sync.md for the complete strategy.

Branch Naming

Prefix	Purpose
`feat/<topic>`	New features
`fix/<topic>`	Bug fixes
`chore/<topic>`	Maintenance
`evo/<timestamp>-<slug>`	Auto-generated by evolution engine

Commit Convention

feat(geneclaw): add autopilot controller

Evo-Event-ID: abc123
Risk-Level: low
Tests: pytest tests/test_geneclaw_autopilot.py -q

Documentation

Document	Description
GEP v0 Protocol Specification	Core protocol design
Operator Runbook	Day-to-day operations guide
Dashboard Runbook	Dashboard setup & usage
GitHub Governance	Branch protection & PR review
Release Runbook	Tagging, releases, rollback
LLM Provider Setup	Secure API key configuration
First Real Proposal	Generating your first proposal
Upstream Sync	Merge strategy for HKUDS/nanobot
First Live Run Audit	Audit trail
Changelog	Release history
Development Log	Daily engineering notes

Repository


Website	geneclaw.ai
Origin	Clawland-AI/Geneclaw
Upstream	HKUDS/nanobot
Organization	Clawland-AI

License

MIT — see LICENSE.

_{Built by Clawland-AI · Powered by HKUDS/nanobot · geneclaw.ai}

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
.github		.github
bridge		bridge
case		case
docs		docs
geneclaw		geneclaw
nanobot		nanobot
tests		tests
workspace		workspace
.cursorrules		.cursorrules
.dockerignore		.dockerignore
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
COMMUNICATION.md		COMMUNICATION.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
core_agent_lines.sh		core_agent_lines.sh
docker-compose.yml		docker-compose.yml
nanobot_arch.png		nanobot_arch.png
nanobot_logo.png		nanobot_logo.png
pyproject.toml		pyproject.toml

License

Clawland-AI/Geneclaw

Folders and files

Latest commit

History

Repository files navigation

🧬 Geneclaw — Self-Evolving AI Agent Framework

Key Capabilities

Architecture

Project Structure

Install

Quick Start

1. Initialize

2. Enable Geneclaw

3. Verify

4. Chat (generates run events)

5. Generate evolution proposal

6. View statistics

7. Launch Dashboard

CLI Reference

Autopilot Options

Benchmark Options

Dashboard Options

Configuration

Safety Model

1. Dry-Run Default

2. Gatekeeper (5 Checks)

3. Git Safety

4. Secret Redaction

5. Recommended Allowlist Strategy

Slash Command

Data Layout

Testing

Development

Upstream Sync

Branch Naming

Commit Convention

Documentation

Repository

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 2

Uh oh!

Languages

Packages