{"id":49091643,"url":"https://github.com/evo-hq/evo","last_synced_at":"2026-04-26T18:01:16.270Z","repository":{"id":351120926,"uuid":"1202113460","full_name":"evo-hq/evo","owner":"evo-hq","description":"A plugin for Claude Code and Codex that turns your codebase into an autoresearch loop — discovers what to measure, instruments the benchmark, then runs tree search with parallel subagents.","archived":false,"fork":false,"pushed_at":"2026-04-25T15:29:37.000Z","size":10614,"stargazers_count":515,"open_issues_count":8,"forks_count":45,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-25T17:28:08.208Z","etag":null,"topics":["agent-skills","autonomous-agents","autoresearch","claude-code","code-optimization","codex","evolutionary-algorithms","llm-agents"],"latest_commit_sha":null,"homepage":"https://github.com/evo-hq/evo","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evo-hq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-05T16:04:50.000Z","updated_at":"2026-04-25T06:03:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/evo-hq/evo","commit_stats":null,"previous_names":["evo-hq/evo"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/evo-hq/evo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evo-hq%2Fevo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evo-hq%2Fevo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evo-hq%2Fevo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evo-hq%2Fevo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evo-hq","download_url":"https://codeload.github.com/evo-hq/evo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evo-hq%2Fevo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32307015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T17:23:19.671Z","status":"ssl_error","status_checked_at":"2026-04-26T17:23:19.195Z","response_time":129,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["agent-skills","autonomous-agents","autoresearch","claude-code","code-optimization","codex","evolutionary-algorithms","llm-agents"],"created_at":"2026-04-20T19:00:36.347Z","updated_at":"2026-04-26T18:01:16.264Z","avatar_url":"https://github.com/evo-hq.png","language":"Python","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/banner.png\" alt=\"evo banner\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n# evo\n\nA plugin for your agentic framework that optimizes code through experiments. Currently supported on [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://developers.openai.com/codex), [OpenClaw](https://github.com/openclaw/openclaw), and [Hermes](https://github.com/NousResearch/hermes-agent).\n\nYou give it a codebase. It discovers metrics to optimize, sets up the evaluation, and starts running experiments in a loop -- trying things, keeping what improves the score, throwing away what doesn't.\n\nInspired by [Karpathy's autoresearch](https://github.com/karpathy/autoresearch) -- where an LLM runs training experiments autonomously to beat its own best score. Autoresearch is a pure hill climb: try something, keep or revert, repeat on a single branch. Evo adds structure on top of that idea:\n\n- **Tree search over greedy hill climb.** Multiple directions can fork from any committed node, so exploration doesn't collapse to one path.\n- **Parallel semi-autonomous agents.** Spawn multiple subagents and run them simultaneously, each in its own git worktree. Each subagent reads traces, formulates hypotheses, and can run multiple iterations within its branch.\n- **Shared state.** Failure traces, annotations, and discarded hypotheses are accessible to every agent before it decides what to try next.\n- **Gating.** Regression tests or safety checks can be wired up as a gate. Experiments that don't pass get discarded.\n- **Observability.** A dashboard to monitor your experiments.\n- **Benchmark discovery.** The `discover` skill explores the repo, figures out what to measure, and instruments the evaluation.\n\n## Install\n\nCommon: `git`, [uv](https://docs.astral.sh/uv/), Python 3.10+.\n\n### 1. Install the evo CLI (non-Claude Code hosts)\n\nClaude Code bundles its own copy. Every other host calls `evo` as an external binary:\n\n```bash\nuv tool install evo-hq-cli   # or: pipx install evo-hq-cli\nevo --version                # evo-hq-cli 0.3.0\n```\n\n### 2. Add the plugin\n\n**Claude Code**\n\n```\n/plugin marketplace add evo-hq/evo\n/plugin install evo@evo-hq-evo\n```\n\nInvoke: `/evo:discover`, `/evo:optimize`.\n\n**Codex** (requires 0.122.0 or newer -- `npm install -g @openai/codex@latest`)\n\n```bash\ncodex plugin marketplace add evo-hq/evo\n```\n\nThen `/plugins` → `evo` → install. Invoke: `$evo discover`, `$evo optimize`.\n\n**OpenClaw**\n\n```bash\nopenclaw plugins install evo --marketplace https://github.com/evo-hq/evo\n```\n\nInvoke: `/discover`, `/optimize`.\n\n**Hermes** (per-skill install, no bundle support)\n\n```bash\nhermes skills install evo-hq/evo/plugins/evo/skills/discover --force\nhermes skills install evo-hq/evo/plugins/evo/skills/optimize\nhermes skills install evo-hq/evo/plugins/evo/skills/subagent\n```\n\n`--force` on `discover` bypasses the SKILL.md scanner (it flags evo's own install examples). Invoke: `/discover`, `/optimize`.\n\n## Usage\n\nTwo skills:\n\n- **`discover`** -- explores the repo, instruments the benchmark, runs baseline\n- **`optimize`** -- runs the optimization loop with parallel subagents until interrupted\n\nInvocation syntax depends on the host -- see the Install section above.\n\n`optimize` accepts optional parameters:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `subagents` | 5 | Number of parallel subagents per round |\n| `budget` | 5 | Max iterations each subagent can run within its branch |\n| `stall` | 5 | Consecutive rounds with no improvement before auto-stopping |\n\nExample (Claude Code): `/evo:optimize subagents=3 budget=10 stall=3`. Other hosts use their own invocation prefix.\n\nTypical flow:\n\n```\nyou: evo:discover\nevo: explores repo, instruments benchmark, runs baseline\n\nyou: evo:optimize\nevo: spawns 5 subagents in parallel, each exploring a different direction\n     each subagent can run up to 5 iterations within its branch\n     orchestrator collects results, prunes dead branches, adjusts strategy\n     repeats until interrupted or stalled\n```\n\nUnder the hood, each experiment gets its own git worktree branching from its parent. If the score improves and the gate passes, the experiment is committed. Otherwise it's discarded and the worktree is cleaned up.\n\n### Architecture\n\n```\nOrchestrator (main agent)\n  - reads state, identifies failure patterns cross-cutting the tree\n  - writes a structured brief per subagent (objective, parent, boundaries, pointer traces)\n  - collects results, prunes dead branches, adjusts strategy for next round\n\n  Subagent 1 (background, budget: 5 iterations)\n    - reads traces, analyzes failures in its focus area\n    - formulates hypothesis, edits target, runs benchmark\n    - if budget remains and sees a follow-up, iterates on its branch\n    - returns: what it tried, what worked, what it learned\n\n  Subagent 2 (background, budget: 5 iterations)\n    ...up to N subagents in parallel\n```\n\n## Dashboard\n\nThe dashboard starts automatically when you run `evo:discover` (or `evo init`). When it comes up, the agent surfaces the URL in the chat:\n\n```\nDashboard live: http://127.0.0.1:8080 (pid 12345)\n```\n\nIf `8080` is busy, evo auto-increments (`8081`, `8082`, ...) and prints the actual port. You can also start it manually:\n\n```bash\nuv run --project /path/to/evo/plugins/evo evo dashboard --port 8080\n```\n\nThe chosen port is persisted to `.evo/dashboard.port` so repeat runs re-use it.\n\n## Dev install\n\nFor working on evo itself (not just using it):\n\n```bash\ngit clone https://github.com/evo-hq/evo\ncd evo\nuv run --project plugins/evo evo --version   # evo-hq-cli 0.3.0\n```\n\n`uv run` resolves dependencies on first use -- no `pip install` step.\n\nThe SDKs live in separate packages:\n\n- `sdk/python/` -- `evo-hq-agent`, Python 3.10+, zero deps. Tests: `cd sdk/python \u0026\u0026 uv run --with pytest pytest test/`.\n- `sdk/node/` -- `@evo-hq/evo-agent`, Node 18+, zero deps. Tests: `cd sdk/node \u0026\u0026 npm test`.\n\n## TODO\n\n- [ ] Distributed evaluation via [Harbor](https://github.com/harbor-framework/harbor) -- run benchmarks in containers instead of locally, use Harbor's cloud providers to parallelize.\n\n## License\n\nLicensed under the [Apache License 2.0](LICENSE).\n","funding_links":[],"categories":["Multi-Agent \u0026 Orchestration"],"sub_categories":["Other IDEs"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevo-hq%2Fevo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevo-hq%2Fevo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevo-hq%2Fevo/lists"}