---
**Geneclaw** extends the ultra-lightweight [nanobot](https://github.com/HKUDS/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](https://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)**
```bash
git clone https://github.com/Clawland-AI/Geneclaw.git
cd Geneclaw
pip install -e ".[dev]"
```
**With Dashboard support**
```bash
pip install -e ".[dev,dashboard]"
```
**Add upstream remote** (for syncing with nanobot)
```bash
git remote add upstream https://github.com/HKUDS/nanobot.git
```
## Quick Start
### 1. Initialize
```bash
nanobot onboard
```
### 2. Enable Geneclaw
Add or merge into `~/.nanobot/config.json`:
```json
{
"geneclaw": {
"enabled": true,
"redactEnabled": true,
"allowApplyDefault": false,
"allowlistPaths": ["geneclaw/", "docs/"],
"denylistPaths": [".env", "secrets/", ".git/", "config.json"],
"maxPatchLines": 500
}
}
```
### 3. Verify
```bash
nanobot geneclaw doctor
```
### 4. Chat (generates run events)
```bash
nanobot agent -m "Hello, what tools do you have?"
```
### 5. Generate evolution proposal
```bash
nanobot geneclaw evolve --dry-run
```
### 6. View statistics
```bash
nanobot geneclaw report
```
### 7. Launch Dashboard
```bash
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 
