Geneclaw

https://geneclaw.ai/docs
Admin
Geneclaw is an open-source framework for safe, auditable self-evolving agents, ensuring every...
Tokens:4,878
Snippets:73
Trust Score:2.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Geneclaw using pip, uv, or pipx

Source: https://geneclaw.ai/docs-getting-started.html

Choose your preferred package manager to install Geneclaw. Pipx provides an isolated environment.

```bash
pip install geneclaw
```

```bash
uv pip install geneclaw
```

```bash
pipx install geneclaw
```

--------------------------------

### Install and Verify Geneclaw

Source: https://geneclaw.ai

Installs the Geneclaw package using pip and verifies the installation with a health check. Ensure you have Python and pip installed.

```bash
# Install Geneclaw
pip install geneclaw

# Verify installation (read-only health check)
geneclaw doctor

# Expected output:
# ✓ nanobot connection OK
# ✓ Event store writable
# ✓ Gatekeeper config loaded
# ✓ Git repository detectedCopy
```

--------------------------------

### Create Geneclaw Configuration File (geneclaw.toml)

Source: https://geneclaw.ai/docs-getting-started.html

Define agent, gatekeeper, store, safety, and diagnosis settings in the geneclaw.toml file. Start with a minimal allowlist for prompts and config directories.

```toml
# 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
```

--------------------------------

### Autopilot Configuration Example

Source: https://geneclaw.ai/docs-gep-v0.html

This TOML configuration sets parameters for Autopilot mode, including the maximum number of evolution cycles, the maximum risk score for auto-approval, and the delay between cycles.

```toml
[autopilot]
max_cycles = 5
max_risk   = 30    # proposals with risk > 30 pause for human review
cycle_delay_s = 60
```

--------------------------------

### Install Geneclaw and Run Doctor

Source: https://geneclaw.ai

Install the Geneclaw package using pip and then run the `geneclaw doctor` command for a non-destructive health check of your agent configuration and environment. This command has zero side effects.

```bash
$ pip install geneclaw && geneclaw doctor
```

--------------------------------

### Example Agent Event Structure (JSONL)

Source: https://geneclaw.ai/docs-gep-v0.html

This JSONL structure represents a single event captured during the Observe stage. It includes timestamp, event type, agent ID, and payload details, with PII redacted.

```json
{"ts": "2025-01-15T10:23:41Z", "type": "tool_call", "agent": "my-agent",
 "tool": "web_search", "status": "error", "latency_ms": 3412, "error": "timeout"}
{"ts": "2025-01-15T10:23:42Z", "type": "llm_response", "agent": "my-agent",
 "tokens": 842, "latency_ms": 1203, "finish_reason": "stop"}
```

--------------------------------

### Geneclaw Doctor Expected Output

Source: https://geneclaw.ai/docs-getting-started.html

Example output from the 'geneclaw doctor' command, indicating the status of various checks.

```text
✓ 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
```

--------------------------------

### Geneclaw Gatekeeper Expected Output

Source: https://geneclaw.ai/docs-getting-started.html

Example output from the 'geneclaw gate' command, showing the status of each safety layer.

```text
# [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
```

--------------------------------

### Example Geneclaw Evolution Proposal (GEP JSON)

Source: https://geneclaw.ai/docs-gep-v0.html

This JSON document details a proposed evolution, including its ID, rationale, affected paths, diff, and gate status. It's used in the Propose stage.

```json
{
  "id": "gep-001",
  "created_at": "2025-01-15T10:30:00Z",
  "agent": "my-agent",
  "diagnosis_ref": "diag-2025-01-15-001",
  "rationale": "Retry logic missing for web_search tool; 23% failure rate observed",
  "risk_score": 28,
  "affected_paths": ["src/prompts/tool_retry.txt"],
  "diff": "--- a/src/prompts/tool_retry.txt\n+++ b/src/prompts/tool_retry.txt\n@@ -1 +1,3 @@\n+If a tool call fails with a timeout, retry up to 2 times before escalating.\n+Wait 1 second between retries.\n Use the most reliable available tool first.",
  "rollback_plan": "git revert commit on branch geneclaw/gep-001",
  "gate_status": "pending",
  "apply_status": "not_applied"
}
```

--------------------------------

### Generate and Report an Evolution Proposal (Dry Run)

Source: https://geneclaw.ai/docs-getting-started.html

Generate a dry-run evolution proposal and then view it using the 'report' command. The proposal is not applied to your files at this stage.

```bash
# 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
```

--------------------------------

### Configure Geneclaw Agent

Source: https://geneclaw.ai

Sets up the minimal configuration for a Geneclaw agent using a TOML file. This includes agent name, repository path, gatekeeper rules, event store settings, and safety configurations like dry-run mode.

```toml
# geneclaw.toml — minimal configuration

[agent]
name = "my-agent"
repo = "."

[gatekeeper]
# Only allow changes in these paths
allowlist = ["src/prompts/", "config/"]
denylist  = [".env", "secrets/", "*.key"]
max_diff_lines = 200

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

[safety]
dry_run = true   # always true by default
require_tests = trueCopy
```

--------------------------------

### Run Geneclaw Evolution Cycle

Source: https://geneclaw.ai

Commands to generate a dry-run evolution proposal, review it, explicitly run the gate check, apply the changes, and rollback if necessary. Human approval is required before applying changes.

```bash
# Generate a dry-run evolution proposal
geneclaw evolve --dry-run

# Review the proposal (unified diff + risk score)
geneclaw report --last 1

# If you approve, run the gate check explicitly
geneclaw gate --proposal proposals/gep-001.json

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

# If something goes wrong, rollback is one command
geneclaw apply --rollbackCopy
```

--------------------------------

### Apply Geneclaw Proposal with --apply Flag

Source: https://geneclaw.ai/docs-getting-started.html

Apply a reviewed and gate-passed proposal to your codebase using the '--apply' flag. This is the step where files are actually modified.

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

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

--------------------------------

### Geneclaw Gatekeeper Allowlist and Denylist Configuration

Source: https://geneclaw.ai

Configure the paths that Geneclaw is allowed to modify and those that should be explicitly blocked. This is part of the Gatekeeper's path filtering layer.

```toml
[gatekeeper]
allowlist = [
  "src/prompts/",
  "config/"
]
denylist = [
  ".env",
  "secrets/",
  "*.key",
  "*.pem"
]
```

--------------------------------

### Run Geneclaw Gatekeeper Check

Source: https://geneclaw.ai/docs-getting-started.html

Explicitly run the 5-layer Gatekeeper check on a proposal to ensure it meets all safety requirements before applying.

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

--------------------------------

### Run Geneclaw Doctor for a health check

Source: https://geneclaw.ai/docs-getting-started.html

Execute the 'doctor' command to perform a read-only health check of your environment and Geneclaw configuration. This command does not modify any files.

```bash
geneclaw doctor
```
Tokens:
Raw