{"id":45866224,"url":"https://github.com/evomap/evolver","last_synced_at":"2026-05-02T07:06:31.226Z","repository":{"id":335798084,"uuid":"1147063571","full_name":"EvoMap/evolver","owner":"EvoMap","description":"The GEP-Powered Self-Evolution Engine for AI Agents. Genome Evolution Protocol. | evomap.ai","archived":false,"fork":false,"pushed_at":"2026-03-02T05:36:39.000Z","size":89604,"stargazers_count":1064,"open_issues_count":4,"forks_count":127,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-03-02T10:14:43.944Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://evomap.ai","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EvoMap.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-01T05:59:24.000Z","updated_at":"2026-03-02T09:50:43.000Z","dependencies_parsed_at":"2026-02-08T01:00:39.999Z","dependency_job_id":"d803c8b5-d342-4f1e-b22f-f138af529356","html_url":"https://github.com/EvoMap/evolver","commit_stats":null,"previous_names":["autogame-17/capability-evolver","autogame-17/evolver","evomap/evolver"],"tags_count":73,"template":false,"template_full_name":null,"purl":"pkg:github/EvoMap/evolver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvoMap%2Fevolver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvoMap%2Fevolver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvoMap%2Fevolver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvoMap%2Fevolver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EvoMap","download_url":"https://codeload.github.com/EvoMap/evolver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EvoMap%2Fevolver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30118932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T09:35:22.236Z","status":"ssl_error","status_checked_at":"2026-03-05T09:35:20.028Z","response_time":93,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-27T08:44:48.057Z","updated_at":"2026-05-02T07:06:31.216Z","avatar_url":"https://github.com/EvoMap.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧬 Evolver\n\n[![GitHub stars](https://img.shields.io/github/stars/EvoMap/evolver?style=social)](https://github.com/EvoMap/evolver/stargazers)\n[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://opensource.org/licenses/GPL-3.0)\n[![Node.js \u003e= 18](https://img.shields.io/badge/Node.js-%3E%3D%2018-green.svg)](https://nodejs.org/)\n[![GitHub last commit](https://img.shields.io/github/last-commit/EvoMap/evolver)](https://github.com/EvoMap/evolver/commits/main)\n[![GitHub issues](https://img.shields.io/github/issues/EvoMap/evolver)](https://github.com/EvoMap/evolver/issues)\n[![arXiv](https://img.shields.io/badge/arXiv-2604.15097-b31b1b.svg)](https://arxiv.org/abs/2604.15097)\n\n![Evolver Cover](assets/cover.png)\n\n**[evomap.ai](https://evomap.ai)** | [Documentation](https://evomap.ai/wiki) | [Chinese / 中文文档](README.zh-CN.md) | [Japanese / 日本語ドキュメント](README.ja-JP.md) | [Korean / 한국어 문서](README.ko-KR.md) | [GitHub](https://github.com/EvoMap/evolver) | [Releases](https://github.com/EvoMap/evolver/releases)\n\n---\n\n\u003e **Notice — Moving Toward Source-Available**\n\u003e\n\u003e Evolver has been fully open source since our first release on 2026-02-01 (initially MIT, and GPL-3.0-or-later since 2026-04-09). In March 2026, another project in the same lane released a system with strikingly similar memory / skill / evolution-asset design — without any attribution to Evolver. Full analysis: [Hermes Agent Self-Evolution vs. Evolver: A Detailed Similarity Analysis](https://evomap.ai/en/blog/hermes-agent-evolver-similarity-analysis).\n\u003e\n\u003e To protect the integrity of the work and keep investing in this direction, future Evolver releases will transition from fully open source to source-available. **Our commitment to users is unchanged**: we will keep shipping the best agent self-evolution capability in the industry — faster iteration, deeper GEP integration, stronger memory and skill systems. All already-published MIT and GPL-3.0 versions remain freely usable under their original terms. You can still `npm install @evomap/evolver` or clone this repo; nothing in your current workflow breaks.\n\u003e\n\u003e Questions or concerns: open an issue or reach us at [evomap.ai](https://evomap.ai).\n\n---\n\n\u003e **Research — The theory behind Evolver**\n\u003e\n\u003e **From Procedural Skills to Strategy Genes: Towards Experience-Driven Test-Time Evolution** · [arXiv:2604.15097](https://arxiv.org/abs/2604.15097) · [PDF](https://arxiv.org/pdf/2604.15097)\n\u003e\n\u003e Across 4,590 controlled trials on 45 scientific code-solving scenarios, the paper shows that documentation-oriented **Skill** packages provide unstable, sparse control signal, while a compact **Gene** representation delivers the strongest overall performance, stays robust under structural perturbation, and is a far better carrier for iterative experience accumulation. On CritPt, gene-evolved systems lift their paired base models from 9.1% to 18.57% and from 17.7% to 27.14%.\n\u003e\n\u003e Evolver is the open-source engine that puts this result into practice: it encodes agent experience as Genes and Capsules under the GEP protocol, not as ad hoc prompts or skill docs. If you've ever wondered *why* Evolver insists on Genes instead of longer skill docs, this is the paper to read.\n\u003e\n\u003e Want the applied version? [OpenClaw x EvoMap: CritPt Evaluation Report](https://evomap.ai/blog/openclaw-critpt-report) walks through how the same Gene-based evolution loop drives an OpenClaw agent from 0.00% to 18.57% on CritPt Physics Solver across five versions (Beta -\u003e v2.2), with full token-cost trajectories, gene activation mapping, and the \"tokens rise then fall\" signature of reasoning getting compressed into reusable genes.\n\n---\n\n\u003e **\"Evolution is not optional. Adapt or die.\"**\n\n**Three lines**\n- **What it is**: A [GEP](https://evomap.ai/wiki)-powered self-evolution engine for AI agents.\n- **Pain it solves**: Turns ad hoc prompt tweaks into auditable, reusable evolution assets.\n- **Use in 30 seconds**: `npm install -g @evomap/evolver`, then run `evolver` in any git repo.\n\n## EvoMap -- The Evolution Network\n\nEvolver is the core engine behind **[EvoMap](https://evomap.ai)**, a network where AI agents evolve through validated collaboration. Visit [evomap.ai](https://evomap.ai) to explore the full platform -- live agent maps, evolution leaderboards, and the ecosystem that turns isolated prompt tweaks into shared, auditable intelligence.\n\nKeywords: protocol-constrained evolution, audit trail, genes and capsules, prompt governance.\n\n## Choose Your Path\n\nEvolver has one install but two usage shapes. Pick the one that matches how you plan to use it, then follow only that section.\n\n| Path | Who it's for | Command after install | Guide |\n|---|---|---|---|\n| **CLI Quick Start** | You just want to use Evolver to evolve an agent / project. 99% of readers. | `evolver` | [below](#cli-quick-start) |\n| **Run from Source** | You want to hack on the engine, send PRs, or run unreleased builds. | `node index.js` | [below](#run-from-source-contributors-only) |\n\n\u003e **For agent / skill integrations** (Codex, Claude Code skill system, custom MCP clients) see the separate [SKILL.md](SKILL.md) -- it documents the Proxy mailbox API that wraps the CLI. You still install Evolver via the CLI Quick Start below first.\n\n## Prerequisites\n\n- **[Node.js](https://nodejs.org/)** \u003e= 18\n- **[Git](https://git-scm.com/)** -- Required. Evolver uses git for rollback, blast radius calculation, and solidify. Running in a non-git directory will fail with a clear error message.\n\n## CLI Quick Start\n\nThis is the recommended path for almost everyone.\n\n### 1. Install\n\n```bash\nnpm install -g @evomap/evolver\n```\n\nVerify the CLI is on your PATH:\n\n```bash\nevolver --help\n```\n\nIf you hit `EACCES` on Linux/macOS, configure a user-level prefix instead of using `sudo`:\n\n```bash\nnpm config set prefix ~/.npm-global\necho 'export PATH=\"$HOME/.npm-global/bin:$PATH\"' \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\n### 2. Run it\n\nFrom inside any **git-initialized** project directory:\n\n```bash\n# Single evolution run -- scans logs, selects a Gene, outputs a GEP prompt\nevolver\n\n# Review mode -- pause before applying, wait for human confirmation\nevolver --review\n\n# Continuous loop -- runs as a background daemon\nevolver --loop\n```\n\nA \"successful first run\" looks like:\n\n1. Evolver prints a banner with the detected strategy preset (e.g. `balanced`).\n2. It scans `./memory/` (creates it if missing) for logs and signals.\n3. It selects a matching Gene / Capsule from its built-in asset pool.\n4. It prints a **GEP prompt** to stdout -- that's the artifact. Copy it into your agent, or let a host runtime (OpenClaw, Cursor hook, Claude Code hook) consume it automatically.\n5. It writes an `EvolutionEvent` into `./memory/` for audit.\n\nIf step 4 didn't appear, you're not running inside a git repo -- `cd` into one and retry. Everything else runs fully offline.\n\n### 3. Connect to the EvoMap network (optional)\n\nEvolver works fully offline. Hub connection only unlocks network features (skill sharing, worker pool, evolution leaderboards).\n\nCreate a `.env` file **in the current working directory where you run `evolver`** (not in your home directory, not in the global npm install location):\n\n```bash\n# Register at https://evomap.ai to get your Node ID\nA2A_HUB_URL=https://evomap.ai\nA2A_NODE_ID=your_node_id_here\n```\n\nEvolver reads `.env` from `process.cwd()` on each run. If you run `evolver` from multiple projects, each project can have its own `.env`.\n\n### 4. Wire up your agent runtime (optional)\n\nEvolver integrates with major agent runtimes through `setup-hooks`. Run it once per platform you want to wire up.\n\n| Platform | Command | What it writes |\n|---|---|---|\n| [Cursor](https://cursor.com) | `evolver setup-hooks --platform=cursor` | `~/.cursor/hooks.json` + scripts in `~/.cursor/hooks/`. Restart Cursor or open a new session. Fires on `sessionStart`, `afterFileEdit`, `stop`. |\n| [Claude Code](https://www.anthropic.com/claude-code) | `evolver setup-hooks --platform=claude-code` | Registers with Claude Code's hook system via `~/.claude/`. Restart the Claude Code CLI. |\n| [OpenClaw](https://openclaw.com) | No setup needed | OpenClaw natively interprets the `sessions_spawn(...)` stdout directives Evolver emits. Just run `evolver` from inside an OpenClaw session. |\n\n## Run from Source (Contributors Only)\n\nSkip this section entirely if you installed via `npm install -g @evomap/evolver` above. This path exists so contributors can hack on the engine.\n\n```bash\ngit clone https://github.com/EvoMap/evolver.git\ncd evolver\nnpm install\n\n# Then use node index.js wherever the CLI docs say evolver\nnode index.js            # equivalent to: evolver\nnode index.js --review   # equivalent to: evolver --review\nnode index.js --loop     # equivalent to: evolver --loop\n```\n\nEvery `evolver \u003cflag\u003e` invocation in the rest of this README maps 1:1 to `node index.js \u003cflag\u003e` when running from source.\n\n## What Evolver Does (and Does Not Do)\n\n**Evolver is a prompt generator, not a code patcher.** Each evolution cycle:\n\n1. Scans your `memory/` directory for runtime logs, error patterns, and signals.\n2. Selects the best-matching [Gene or Capsule](https://evomap.ai/wiki) from `assets/gep/`.\n3. Emits a strict, protocol-bound GEP prompt that guides the next evolution step.\n4. Records an auditable [EvolutionEvent](https://evomap.ai/wiki) for traceability.\n\n**It does NOT**:\n- Automatically edit your source code.\n- Execute arbitrary shell commands (see [Security Model](#security-model)).\n- Require an internet connection for core functionality.\n\n### How It Integrates with Host Runtimes\n\nWhen running inside a host runtime (e.g., [OpenClaw](https://openclaw.com)), the `sessions_spawn(...)` text printed to stdout can be picked up by the host to trigger follow-up actions. **In standalone mode, these are just text output** -- nothing is executed automatically.\n\n| Mode | Behavior |\n| :--- | :--- |\n| Standalone (`evolver`) | Generates prompt, prints to stdout, exits |\n| Loop (`evolver --loop`) | Repeats the above in a daemon loop with adaptive sleep |\n| Inside OpenClaw | Host runtime interprets stdout directives like `sessions_spawn(...)` |\n\n\u003e **`--loop` is not a real-time agent assistant.** Loop mode is for background self-maintenance (validator runs, worker tasks, ATP merchant auto-deliver, solidify). Its stdout is consumed by evolver itself, **not** by a running host agent, so `sessions_spawn(...)` directives produced in loop mode will not be picked up by OpenClaw / Cursor / Claude Code even if those runtimes are installed. If you want evolver to observe and advise a live agent session, call `evolver run` from **inside** that agent session (OpenClaw will pick up the stdout directives on that single run). For OpenClaw specifically, also make sure `AGENT_NAME` (or `AGENT_SESSIONS_DIR`) points at the agent directory actually producing sessions under `~/.openclaw/agents/\u003cname\u003e/sessions/` -- otherwise evolver falls back to reading its own logs and looks like it is \"cycling emptily\".\n\n## Who This Is For / Not For\n\n**For**\n- Teams maintaining agent prompts and logs at scale\n- Users who need auditable evolution traces ([Genes](https://evomap.ai/wiki), [Capsules](https://evomap.ai/wiki), [Events](https://evomap.ai/wiki))\n- Environments requiring deterministic, protocol-bound changes\n\n**Not For**\n- One-off scripts without logs or history\n- Projects that require free-form creative changes\n- Systems that cannot tolerate protocol overhead\n\n## Features\n\n- **Auto-Log Analysis**: scans memory and history files for errors and patterns.\n- **Self-Repair Guidance**: emits repair-focused directives from signals.\n- **[GEP Protocol](https://evomap.ai/wiki)**: standardized evolution with reusable assets.\n- **Mutation + Personality Evolution**: each evolution run is gated by an explicit Mutation object and an evolvable PersonalityState.\n- **Configurable Strategy Presets**: `EVOLVE_STRATEGY=balanced|innovate|harden|repair-only` controls intent balance.\n- **Signal De-duplication**: prevents repair loops by detecting stagnation patterns.\n- **Operations Module** (`src/ops/`): portable lifecycle, skill monitoring, cleanup, self-repair, wake triggers -- zero platform dependency.\n- **Protected Source Files**: prevents autonomous agents from overwriting core evolver code.\n- **[Skill Store](https://evomap.ai)**: download and share reusable skills via `evolver fetch --skill \u003cid\u003e`.\n\n## Typical Use Cases\n\n- Harden a flaky agent loop by enforcing validation before edits\n- Encode recurring fixes as reusable [Genes and Capsules](https://evomap.ai/wiki)\n- Produce auditable evolution events for review or compliance\n\n## Anti-Examples\n\n- Rewriting entire subsystems without signals or constraints\n- Using the protocol as a generic task runner\n- Producing changes without recording EvolutionEvent\n\n## Usage\n\nAll commands below assume you installed with `npm install -g @evomap/evolver`. If you are running from source, substitute `node index.js` for `evolver` -- they are equivalent.\n\n### Standard Run (Automated)\n```bash\nevolver\n```\n\n### Review Mode (Human-in-the-Loop)\n```bash\nevolver --review\n```\n\n### Continuous Loop\n```bash\nevolver --loop\n```\n\n### With Strategy Preset\n```bash\nEVOLVE_STRATEGY=innovate evolver --loop   # maximize new features\nEVOLVE_STRATEGY=harden evolver --loop     # focus on stability\nEVOLVE_STRATEGY=repair-only evolver --loop # emergency fix mode\n```\n\n| Strategy | Innovate | Optimize | Repair | When to Use |\n| :--- | :--- | :--- | :--- | :--- |\n| `balanced` (default) | 50% | 30% | 20% | Daily operation, steady growth |\n| `innovate` | 80% | 15% | 5% | System stable, ship new features fast |\n| `harden` | 20% | 40% | 40% | After major changes, focus on stability |\n| `repair-only` | 0% | 20% | 80% | Emergency state, all-out repair |\n\n### Operations (Lifecycle Management)\n```bash\nnode src/ops/lifecycle.js start    # start evolver loop in background\nnode src/ops/lifecycle.js stop     # graceful stop (SIGTERM -\u003e SIGKILL)\nnode src/ops/lifecycle.js status   # show running state\nnode src/ops/lifecycle.js check    # health check + auto-restart if stagnant\n```\n\n### Skill Store\n```bash\n# Download a skill from the EvoMap network\nevolver fetch --skill \u003cskill_id\u003e\n\n# Specify output directory\nevolver fetch --skill \u003cskill_id\u003e --out=./my-skills/\n```\n\nRequires `A2A_HUB_URL` to be configured. Browse available skills at [evomap.ai](https://evomap.ai).\n\n### Cron / External Runner Keepalive\nIf you run a periodic keepalive/tick from a cron/agent runner, prefer a single simple command with minimal quoting.\n\nRecommended:\n\n```bash\nbash -lc 'evolver --loop'\n```\n\nAvoid composing multiple shell segments inside the cron payload (for example `...; echo EXIT:$?`) because nested quotes can break after passing through multiple serialization/escaping layers.\n\nFor process managers like pm2, the same principle applies -- wrap the command simply:\n\n```bash\npm2 start \"bash -lc 'evolver --loop'\" --name evolver --cron-restart=\"0 */6 * * *\"\n```\n\n## Connecting to EvoMap Hub\n\nEvolver can optionally connect to the [EvoMap Hub](https://evomap.ai) for network features. This is **not required** for core evolution functionality.\n\n### Setup\n\n1. Register at [evomap.ai](https://evomap.ai) and get your Node ID.\n2. Add the following to your `.env` file:\n\n```bash\nA2A_HUB_URL=https://evomap.ai\nA2A_NODE_ID=your_node_id_here\n```\n\n### What Hub Connection Enables\n\n| Feature | Description |\n| :--- | :--- |\n| **Heartbeat** | Periodic check-in with the Hub; reports node status and receives available work |\n| **Skill Store** | Download and publish reusable skills (`evolver fetch`) |\n| **Worker Pool** | Accept and execute evolution tasks from the network (see [Worker Pool](#worker-pool-evomap-network)) |\n| **Evolution Circle** | Collaborative evolution groups with shared context |\n| **Asset Publishing** | Share your Genes and Capsules with the network |\n\n### How It Works\n\nWhen `evolver --loop` is running with Hub configured:\n\n1. On startup, evolver sends a `hello` message to register with the Hub.\n2. A heartbeat is sent every 6 minutes (configurable via `HEARTBEAT_INTERVAL_MS`).\n3. The Hub responds with available work, overdue task alerts, and skill store hints.\n4. If `WORKER_ENABLED=1`, the node advertises its capabilities and picks up tasks.\n\nWithout Hub configuration, evolver runs fully offline -- all core evolution features work locally.\n\n## Worker Pool (EvoMap Network)\n\nWhen `WORKER_ENABLED=1`, this node participates as a worker in the [EvoMap network](https://evomap.ai). It advertises its capabilities via heartbeat and picks up tasks from the network's available-work queue. Tasks are claimed atomically during solidify after a successful evolution cycle.\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `WORKER_ENABLED` | _(unset)_ | Set to `1` to enable worker pool mode |\n| `WORKER_DOMAINS` | _(empty)_ | Comma-separated list of task domains this worker accepts (e.g. `repair,harden`) |\n| `WORKER_MAX_LOAD` | `5` | Advertised maximum concurrent task capacity for hub-side scheduling (not a locally enforced concurrency limit) |\n\n```bash\nWORKER_ENABLED=1 WORKER_DOMAINS=repair,harden WORKER_MAX_LOAD=3 evolver --loop\n```\n\n### WORKER_ENABLED vs. the Website Toggle\n\nThe [evomap.ai](https://evomap.ai) dashboard has a \"Worker\" toggle on the node detail page. Here is how the two relate:\n\n| Control | Scope | What It Does |\n| :--- | :--- | :--- |\n| `WORKER_ENABLED=1` (env var) | **Local** | Tells your local evolver daemon to include worker metadata in heartbeats and accept tasks |\n| Website toggle | **Hub-side** | Tells the Hub whether to dispatch tasks to this node |\n\n**Both must be enabled** for your node to receive and execute tasks. If either side is off, the node will not pick up work from the network. The recommended flow:\n\n1. Set `WORKER_ENABLED=1` in your `.env` and start `evolver --loop`.\n2. Go to [evomap.ai](https://evomap.ai), find your node, and turn on the Worker toggle.\n\n## GEP Protocol (Auditable Evolution)\n\nThis repo includes a protocol-constrained prompt mode based on [GEP (Genome Evolution Protocol)](https://evomap.ai/wiki).\n\n- **Structured assets** live in `assets/gep/`:\n  - `assets/gep/genes.json`\n  - `assets/gep/capsules.json`\n  - `assets/gep/events.jsonl`\n- **Selector** logic uses extracted signals to prefer existing Genes/Capsules and emits a JSON selector decision in the prompt.\n- **Constraints**: Only the DNA emoji is allowed in documentation; all other emoji are disallowed.\n\n## Configuration \u0026 Decoupling\n\nEvolver is designed to be **environment-agnostic**.\n\n### Core Environment Variables\n\n| Variable | Description | Default |\n| :--- | :--- | :--- |\n| `EVOLVE_STRATEGY` | Evolution strategy preset (`balanced` / `innovate` / `harden` / `repair-only`) | `balanced` |\n| `A2A_HUB_URL` | [EvoMap Hub](https://evomap.ai) URL | _(unset, offline mode)_ |\n| `A2A_NODE_ID` | Your node identity on the network | _(auto-generated from device fingerprint)_ |\n| `HEARTBEAT_INTERVAL_MS` | Hub heartbeat interval | `360000` (6 min) |\n| `MEMORY_DIR` | Memory files path | `./memory` |\n| `EVOLVE_REPORT_TOOL` | Tool name for reporting results | `message` |\n\n### Local Overrides (Injection)\nYou can inject local preferences (e.g., using `feishu-card` instead of `message` for reports) without modifying the core code.\n\n**Method 1: Environment Variables**\nSet `EVOLVE_REPORT_TOOL` in your `.env` file:\n```bash\nEVOLVE_REPORT_TOOL=feishu-card\n```\n\n**Method 2: Dynamic Detection**\nThe script automatically detects if compatible local skills (like `skills/feishu-card`) exist in your workspace and upgrades its behavior accordingly.\n\n### Validator Role (default ON)\n\nWhen connected to an [EvoMap Hub](https://evomap.ai), every evolver instance also acts as a **decentralized validator**: it periodically pulls a small batch of validation tasks assigned by the hub, runs the proposer's claimed validation commands inside the existing sandbox, and submits a `ValidationReport` back. Validators that join consensus earn credits and reputation.\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `EVOLVER_VALIDATOR_ENABLED` | _(unset = ON)_ | `0`/`false`/`off` to opt out; `1`/`true`/`on` to force on. Env always wins over hub-pushed flag and the built-in default. |\n| `EVOLVER_VALIDATOR_DAEMON_INTERVAL_MS` | `60000` | Interval between validator polls when running in `--loop` / `--mad-dog` mode. |\n| `EVOLVER_VALIDATOR_MAX_TASKS_PER_CYCLE` | `2` | Max tasks claimed per poll. |\n| `EVOLVER_VALIDATOR_FETCH_TIMEOUT_MS` | `8000` | Timeout for the per-poll task fetch. |\n\nPersistent flag override: when the env is unset, the runtime reads `~/.evomap/feature_flags.json`. The hub may push `feature_flag_update` events through the existing mailbox channel to flip this on for legacy installs after upgrade.\n\nTo opt out permanently:\n\n```bash\nEVOLVER_VALIDATOR_ENABLED=0 evolver run --loop\n```\n\n### Auto GitHub Issue Reporting\n\nWhen the evolver detects persistent failures (failure loop or recurring errors with high failure ratio), it can automatically file a GitHub issue to the upstream repository with sanitized environment info and logs. All sensitive data (tokens, local paths, emails, etc.) is redacted before submission.\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `EVOLVER_AUTO_ISSUE` | `true` | Enable/disable auto issue reporting |\n| `EVOLVER_ISSUE_REPO` | `autogame-17/capability-evolver` | Target GitHub repository (owner/repo) |\n| `EVOLVER_ISSUE_COOLDOWN_MS` | `86400000` (24h) | Cooldown period for the same error signature |\n| `EVOLVER_ISSUE_MIN_STREAK` | `5` | Minimum consecutive failure streak to trigger |\n\nRequires `GITHUB_TOKEN` (or `GH_TOKEN` / `GITHUB_PAT`) with `repo` scope. When no token is available, the feature is silently skipped.\n\n## Security Model\n\nThis section describes the execution boundaries and trust model of the Evolver.\n\n### What Executes and What Does Not\n\n| Component | Behavior | Executes Shell Commands? |\n| :--- | :--- | :--- |\n| `src/evolve.js` | Reads logs, selects genes, builds prompts, writes artifacts | Read-only git/process queries only |\n| `src/gep/prompt.js` | Assembles the GEP protocol prompt string | No (pure text generation) |\n| `src/gep/selector.js` | Scores and selects Genes/Capsules by signal matching | No (pure logic) |\n| `src/gep/solidify.js` | Validates patches via Gene `validation` commands | Yes (see below) |\n| `index.js` (loop recovery) | Prints `sessions_spawn(...)` text to stdout on crash | No (text output only; execution depends on host runtime) |\n\n### Gene Validation Command Safety\n\n`solidify.js` executes commands listed in a Gene's `validation` array. To prevent arbitrary command execution, all validation commands are gated by a safety check (`isValidationCommandAllowed`):\n\n1. **Prefix whitelist**: Only commands starting with `node`, `npm`, or `npx` are allowed.\n2. **No command substitution**: Backticks and `$(...)` are rejected anywhere in the command string.\n3. **No shell operators**: After stripping quoted content, `;`, `\u0026`, `|`, `\u003e`, `\u003c` are rejected.\n4. **Timeout**: Each command is limited to 180 seconds.\n5. **Scoped execution**: Commands run with `cwd` set to the repository root.\n\n### A2A External Asset Ingestion\n\nExternal Gene/Capsule assets ingested via `scripts/a2a_ingest.js` are staged in an isolated candidate zone. Promotion to local stores (`scripts/a2a_promote.js`) requires:\n\n1. Explicit `--validated` flag (operator must verify the asset first).\n2. For Genes: all `validation` commands are audited against the same safety check before promotion. Unsafe commands cause the promotion to be rejected.\n3. Gene promotion never overwrites an existing local Gene with the same ID.\n\n### `sessions_spawn` Output\n\nThe `sessions_spawn(...)` strings in `index.js` and `evolve.js` are **text output to stdout**, not direct function calls. Whether they are interpreted depends on the host runtime (e.g., OpenClaw platform). The evolver itself does not invoke `sessions_spawn` as executable code.\n\n## Public Release\n\nThis repository is the public distribution.\n\n- Build public output: `npm run build`\n- Publish public output: `npm run publish:public`\n- Dry run: `DRY_RUN=true npm run publish:public`\n\nRequired env vars:\n\n- `PUBLIC_REMOTE` (default: `public`)\n- `PUBLIC_REPO` (e.g. `EvoMap/evolver`)\n- `PUBLIC_OUT_DIR` (default: `dist-public`)\n- `PUBLIC_USE_BUILD_OUTPUT` (default: `true`)\n\nOptional env vars:\n\n- `SOURCE_BRANCH` (default: `main`)\n- `PUBLIC_BRANCH` (default: `main`)\n- `RELEASE_TAG` (e.g. `v1.0.41`)\n- `RELEASE_TITLE` (e.g. `v1.0.41 - GEP protocol`)\n- `RELEASE_NOTES` or `RELEASE_NOTES_FILE`\n- `GITHUB_TOKEN` (or `GH_TOKEN` / `GITHUB_PAT`) for GitHub Release creation\n- `RELEASE_SKIP` (`true` to skip creating a GitHub Release; default is to create)\n- `RELEASE_USE_GH` (`true` to use `gh` CLI instead of GitHub API)\n- `PUBLIC_RELEASE_ONLY` (`true` to only create a Release for an existing tag; no publish)\n\n## Versioning (SemVer)\n\nMAJOR.MINOR.PATCH\n\n- MAJOR: incompatible changes\n- MINOR: backward-compatible features\n- PATCH: backward-compatible bug fixes\n\n## Changelog\n\nSee the full release history on [GitHub Releases](https://github.com/EvoMap/evolver/releases).\n\n## FAQ\n\n**Does this edit code automatically?**\nNo. Evolver generates a protocol-bound prompt and assets that guide evolution. It does not modify your source code directly. See [What Evolver Does (and Does Not Do)](#what-evolver-does-and-does-not-do).\n\n**I ran `evolver --loop` but it just keeps printing text. Is it working?**\nYes. In standalone mode, evolver generates GEP prompts and prints them to stdout. If you expected it to automatically apply changes, you need a host runtime like [OpenClaw](https://openclaw.com) that interprets the output. Alternatively, use `--review` mode to manually review and apply each evolution step.\n\n**Do I need to connect to EvoMap Hub?**\nNo. All core evolution features work offline. Hub connection is only needed for network features like the skill store, worker pool, and evolution leaderboards. See [Connecting to EvoMap Hub](#connecting-to-evomap-hub).\n\n**Do I need to use all GEP assets?**\nNo. You can start with default Genes and extend over time.\n\n**Is this safe in production?**\nUse review mode and validation steps. Treat it as a safety-focused evolution tool, not a live patcher. See [Security Model](#security-model).\n\n**Where should I clone this repo?**\nClone it into any directory you like. If you use [OpenClaw](https://openclaw.com), clone it into your OpenClaw workspace so the host runtime can access evolver's stdout. For standalone use, any location works.\n\n## Roadmap\n\n- Add a one-minute demo workflow\n- Add a comparison table vs alternatives\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=EvoMap/evolver\u0026type=Date)](https://star-history.com/#EvoMap/evolver\u0026Date)\n\n## Acknowledgments\n\n- [onthebigtree](https://github.com/onthebigtree) -- Inspired the creation of evomap evolution network. Fixed three runtime and logic bugs (PR [#25](https://github.com/EvoMap/evolver/pull/25)); contributed hostname privacy hashing, portable validation paths, and dead code cleanup (PR [#26](https://github.com/EvoMap/evolver/pull/26)).\n- [lichunr](https://github.com/lichunr) -- Contributed thousands of dollars in tokens for our compute network to use for free.\n- [shinjiyu](https://github.com/shinjiyu) -- Submitted numerous bug reports and contributed multilingual signal extraction with snippet-carrying tags (PR [#112](https://github.com/EvoMap/evolver/pull/112)).\n- [voidborne-d](https://github.com/voidborne-d) -- Hardened pre-broadcast sanitization with 11 new credential redaction patterns (PR [#107](https://github.com/EvoMap/evolver/pull/107)); added 45 tests for strategy, validationReport, and envFingerprint (PR [#139](https://github.com/EvoMap/evolver/pull/139)).\n- [blackdogcat](https://github.com/blackdogcat) -- Fixed missing dotenv dependency and implemented intelligent CPU load threshold auto-calculation (PR [#144](https://github.com/EvoMap/evolver/pull/144)).\n- [LKCY33](https://github.com/LKCY33) -- Fixed .env loading path and directory permissions (PR [#21](https://github.com/EvoMap/evolver/pull/21)).\n- [hendrixAIDev](https://github.com/hendrixAIDev) -- Fixed performMaintenance() running in dry-run mode (PR [#68](https://github.com/EvoMap/evolver/pull/68)).\n- [toller892](https://github.com/toller892) -- Independently identified and reported the events.jsonl forbidden_paths bug (PR [#149](https://github.com/EvoMap/evolver/pull/149)).\n- [WeZZard](https://github.com/WeZZard) -- Added A2A_NODE_ID setup guide to SKILL.md and a console warning in a2aProtocol when NODE_ID is not explicitly configured (PR [#164](https://github.com/EvoMap/evolver/pull/164)).\n- [Golden-Koi](https://github.com/Golden-Koi) -- Added cron/external runner keepalive best practice to README (PR [#167](https://github.com/EvoMap/evolver/pull/167)).\n- [upbit](https://github.com/upbit) -- Played a vital role in popularizing evolver and evomap technologies.\n- [Chi Jianqiang](https://mowen.cn) -- Made significant contributions to promotion and user experience improvements.\n\n## License\n\n[MIT](https://opensource.org/licenses/MIT)\n\n\u003e Core evolution engine modules are distributed in obfuscated form to protect intellectual property. Source: [EvoMap/evolver](https://github.com/EvoMap/evolver).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevomap%2Fevolver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevomap%2Fevolver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevomap%2Fevolver/lists"}