evolver

Evolver — Codex Desktop plugin

Self-evolution workflows for Codex Desktop, powered by Evolver (@evomap/evolver) and EvoMap.

This plugin packages Evolver as a Codex-ready workflow: a model-invoked skill, a local status helper, and an MCP bridge to the Evolver Proxy mailbox for Genes and Capsules.

"Evolution is not optional. Adapt or die."

What it does

Layer	Mechanism	Behavior
Passive recall	Skill guidance	Prompts Codex to look for past outcomes, local memory, and relevant Genes before starting substantive work.
Network bridge	MCP server evolver-proxy	Exposes evolver_status, evolver_search_assets, evolver_fetch_asset, evolver_publish_asset, evolver_distill_conversation, and evolver_poll through the local EvoMap Proxy mailbox.
Codex guidance	MCP tool evolver_install_codex_guidance	Installs or refreshes the global ~/.codex/AGENTS.md Evolver guidance section when the user explicitly asks. It makes a timestamped backup before writing.
Active control	CLI workflow	Guides Codex through evolver, evolver --review, evolver --loop, strategy presets, and Codex hook setup.
Safety boundary	Git + review	Evolver emits protocol-bound GEP prompts and auditable events; Codex should not auto-apply generated output unless the user asks.

The plugin is self-contained on the Codex side. Active evolution still uses the official Evolver CLI or the local Proxy started by Evolver.

Prerequisites

• Node.js 18 or newer.
• Git.
• A git-initialized workspace for project runs.
• Optional: global Evolver CLI.

npm install -g @evomap/evolver

If the CLI is not installed globally, Codex can still explain setup and use npx -y @evomap/evolver when the user approves network access.

Configure

Evolver works offline by default. Hub features use project-local environment variables:

A2A_HUB_URL=https://evomap.ai
A2A_NODE_ID=your_node_id_here

The MCP bridge reads the live Proxy URL and token from:

~/.evolver/settings.json

If that file is absent, it falls back to:

http://127.0.0.1:19820

Start the Proxy by running evolver once inside a git repo.

Optional Codex hooks

The plugin gives Codex the evolver_* MCP tools. To add global Codex guidance without installing hooks, ask Codex to call evolver_install_codex_guidance. Use dry_run: true first if you want to preview the AGENTS.md section.

To also install Codex hooks that inject local evolution memory at session start and record local outcomes at session end, install the CLI and run:

npm install -g @evomap/evolver@latest
evolver setup-hooks --platform=codex

Current hook setup writes an AGENTS.md section that tells Codex to use evolver_status, evolver_search_assets, evolver_fetch_asset, and evolver_publish_asset. If an older section mentions gep_recall or gep_record_outcome as the default Codex tools, upgrade @evomap/evolver and rerun setup.

Verify

From a workspace where you want to use Evolver:

node ~/plugins/evolver/scripts/evolver-status.js

After installing the plugin from a repo marketplace, the same script lives inside the plugin cache. In normal Codex use, ask Codex to check Evolver status; when the MCP bridge is loaded it should call evolver_status first.

Typical Codex prompts

• "Use Evolver to check whether this repo has reusable Genes before we change the architecture."
• "Run Evolver review mode and explain the GEP output before applying anything."
• "Check Evolver Proxy status and search for assets related to flaky tests."
• "Distill this reusable workflow from the conversation into a Gene."
• "Set up Evolver Codex hooks for this machine."

Uninstall

Remove or disable the plugin from Codex Plugins. Local Evolver memory under ~/.evolver/ is left intact.

License

GPL-3.0-or-later, matching the upstream Evolver engine. See LICENSE.