Skip to content
Back to search

CyrusNuevoDia-gepa-research

MarketplaceWorks with Claude CodeGitHub

A plugin for your agentic framework that optimizes code using the GEPA algorithm (Genetic-Pareto LLM-driven search).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cyrusnuevodia--gepa-research/badge.svg)](/listings/cyrusnuevodia--gepa-research)

HTML

<a href="/listings/cyrusnuevodia--gepa-research"><img src="/api/listings/cyrusnuevodia--gepa-research/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Common: `git`, [uv](https://docs.astral.sh/uv/), Python 3.10+.

1. Install the gepa-research CLI (non-Claude Code hosts)

Claude Code bundles its own copy. Every other host calls `gepa-research` as an external binary. The CLI is not published to PyPI -- install it directly from this GitHub repo (the package lives in the `plugins/gepa-research/` subdirectory):

uv tool install "git+https://github.com/CyrusNuevoDia/gepa-research#subdirectory=plugins/gepa-research"
# or: pipx install "git+https://github.com/CyrusNuevoDia/gepa-research#subdirectory=plugins/gepa-research"
gepa-research --version              # gepa-research-cli 0.2.2

To pin a release, append `@<tag>` to the repo URL (e.g. `...gepa-research@v0.2.2#subdirectory=...`).

2. Add the plugin

**Claude Code**

/plugin marketplace add CyrusNuevoDia/gepa-research
/plugin install gepa-research@CyrusNuevoDia-gepa-research

Invoke: `/gepa-research:discover`, `/gepa-research:optimize`.

**Codex** (requires 0.121.0-alpha.2 or newer -- `npm install -g @openai/codex@alpha` if you're on 0.120.0 stable)

codex marketplace add CyrusNuevoDia/gepa-research

Then `/plugins` → `gepa-research` → install. Invoke: `$gepa-research discover`, `$gepa-research optimize`.

**OpenClaw**

openclaw plugins install gepa-research --marketplace https://github.com/CyrusNuevoDia/gepa-research

Invoke: `/discover`, `/optimize`.

**Hermes** (per-skill install, no bundle support)

hermes skills install CyrusNuevoDia/gepa-research/plugins/gepa-research/skills/discover --force
hermes skills install CyrusNuevoDia/gepa-research/plugins/gepa-research/skills/optimize

`--force` on `discover` bypasses the SKILL.md scanner (it flags gepa-research's own install examples). Invoke: `/discover`, `/optimize`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 13 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "CyrusNuevoDia-gepa-research",
  3. "owner": {
  4. "name": "CyrusNuevoDia"
  5. },
  6. "plugins": [
  7. {
  8. "name": "gepa-research",
  9. "source": "./plugins/gepa-research",
  10. "description": "Research harness for optimizing code with the GEPA algorithm (LLM-driven genetic-Pareto search)."
  11. }
  12. ]
  13. }
README.md · README · 167 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # GEPAResearch
  2. A plugin for your agentic framework that optimizes code using the [GEPA](https://github.com/gepa-ai/gepa) algorithm (Genetic-Pareto LLM-driven search). 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).
  3. You give it a codebase. It discovers metrics to optimize, sets up the evaluation, and hands the search to GEPA -- a reflection-driven evolutionary optimizer that maintains a Pareto frontier of candidates and uses an LLM to propose targeted improvements from diagnostic feedback.
  4. - **GEPA-backed search.** The optimization inner loop is [`gepa.optimize_anything`](https://github.com/gepa-ai/gepa): LLM-driven reflection over rich side-info, Pareto-efficient candidate selection, and automatic stall/budget handling.
  5. - **Per-candidate git worktrees.** Every candidate GEPA proposes is applied in an isolated worktree and committed if it passes gates -- full audit trail, safe rollback.
  6. - **Gating.** Regression tests or safety checks can be wired up as a gate. Candidates that fail the gate score 0.0 and are discarded.
  7. - **Observability.** A local dashboard renders the candidate lineage DAG (from `GEPAResult.parents`) and per-task traces.
  8. - **Benchmark discovery.** The `discover` skill explores the repo, figures out what to measure, and instruments the evaluation.
  9. ![screenshot](./assets/screenshot.png)
  10. ## Install
  11. Common: `git`, [uv](https://docs.astral.sh/uv/), Python 3.10+.
  12. ### 1. Install the gepa-research CLI (non-Claude Code hosts)
  13. Claude Code bundles its own copy. Every other host calls `gepa-research` as an external binary. The CLI is not published to PyPI -- install it directly from this GitHub repo (the package lives in the `plugins/gepa-research/` subdirectory):
  14. ```bash
  15. uv tool install "git+https://github.com/CyrusNuevoDia/gepa-research#subdirectory=plugins/gepa-research"
  16. # or: pipx install "git+https://github.com/CyrusNuevoDia/gepa-research#subdirectory=plugins/gepa-research"
  17. gepa-research --version # gepa-research-cli 0.2.2
  18. ```
  19. To pin a release, append `@<tag>` to the repo URL (e.g. `...gepa-research@v0.2.2#subdirectory=...`).
  20. ### 2. Add the plugin
  21. **Claude Code**
  22. ```
  23. /plugin marketplace add CyrusNuevoDia/gepa-research
  24. /plugin install gepa-research@CyrusNuevoDia-gepa-research
  25. ```
  26. Invoke: `/gepa-research:discover`, `/gepa-research:optimize`.
  27. **Codex** (requires 0.121.0-alpha.2 or newer -- `npm install -g @openai/codex@alpha` if you're on 0.120.0 stable)
  28. ```bash
  29. codex marketplace add CyrusNuevoDia/gepa-research
  30. ```
  31. Then `/plugins` → `gepa-research` → install. Invoke: `$gepa-research discover`, `$gepa-research optimize`.
  32. **OpenClaw**
  33. ```bash
  34. openclaw plugins install gepa-research --marketplace https://github.com/CyrusNuevoDia/gepa-research
  35. ```
  36. Invoke: `/discover`, `/optimize`.
  37. **Hermes** (per-skill install, no bundle support)
  38. ```bash
  39. hermes skills install CyrusNuevoDia/gepa-research/plugins/gepa-research/skills/discover --force
  40. hermes skills install CyrusNuevoDia/gepa-research/plugins/gepa-research/skills/optimize
  41. ```
  42. `--force` on `discover` bypasses the SKILL.md scanner (it flags gepa-research's own install examples). Invoke: `/discover`, `/optimize`.
  43. ## Usage
  44. Two skills:
  45. - **`discover`** -- explores the repo, instruments the benchmark, runs baseline
  46. - **`optimize`** -- hands the benchmark to GEPA and backports candidates into the local graph
  47. Invocation syntax depends on the host -- see the Install section above.
  48. `optimize` accepts optional parameters:
  49. | Parameter | Default | Description |
  50. | ------------------ | ------- | --------------------------------------------------------------- |
  51. | `max-metric-calls` | 50 | Total evaluator calls GEPA may make this run |
  52. | `stall` | 5 | Consecutive iterations with no improvement before auto-stopping |
  53. Example (Claude Code): `/gepa-research:optimize max-metric-calls=100 stall=10`. Other hosts use their own invocation prefix.
  54. Typical flow:
  55. ```
  56. you: gepa-research:discover
  57. gepa-research: explores repo, instruments benchmark, runs baseline
  58. you: gepa-research:optimize
  59. gepa-research: hands the seed candidate + evaluator to gepa.optimize_anything
  60. GEPA proposes mutations via LLM reflection over side-info
  61. each candidate is applied in an isolated git worktree, gate-checked, and committed on success
  62. runs until budget or stall limit reached
  63. ```
  64. Under the hood, each GEPA candidate gets its own git worktree branching from its parent. If the score improves and the gate passes, the candidate is committed. Otherwise it's discarded and the worktree is cleaned up.
  65. ### Architecture
  66. ```
  67. Orchestrator (this plugin):
  68. - reads current best committed candidate from .gepa-research/<run>/graph.json
  69. - assembles seed_candidate: dict[target_path -> file_contents]
  70. - calls gepa.optimize_anything(seed_candidate, evaluator=adapter.evaluate, ...)
  71. GepaResearchAdapter.evaluate (called by gepa per candidate):
  72. - allocates a git worktree for the candidate
  73. - writes candidate dict to target files
  74. - runs the benchmark subprocess, parses score, captures traces
  75. - runs gates; on failure returns (0.0, {"gate_failed": ..., "traces": ...})
  76. - commits the worktree on success; discards on failure
  77. - returns (score, side_info) back to GEPA
  78. GEPA (external library):
  79. - maintains Pareto frontier of candidates
  80. - selects parent candidate for next iteration
  81. - reflects on side_info via LLM, proposes targeted edits
  82. - stops on budget / stall / signal
  83. ```
  84. ## Dashboard
  85. The dashboard starts automatically when you run `gepa-research:discover` (or `gepa-research init`). When it comes up, the agent surfaces the URL in the chat:
  86. ```
  87. Dashboard live: http://127.0.0.1:8080 (pid 12345)
  88. ```
  89. If `8080` is busy, gepa-research auto-increments (`8081`, `8082`, ...) and prints the actual port. You can also start it manually:
  90. ```bash
  91. uv run --project /path/to/gepa-research/plugins/gepa-research gepa-research dashboard --port 8080
  92. ```
  93. The chosen port is persisted to `.gepa-research/dashboard.port` so repeat runs re-use it.
  94. ## Dev install
  95. For working on gepa-research itself (not just using it):
  96. ```bash
  97. git clone https://github.com/CyrusNuevoDia/gepa-research
  98. cd gepa-research
  99. uv run --project plugins/gepa-research gepa-research --version # gepa-research-cli 0.2.2
  100. ```
  101. `uv run` resolves dependencies on first use -- no `pip install` step.
  102. The SDKs live in separate packages:
  103. - `sdk/python/` -- `gepa-research-agent`, Python 3.10+, zero deps. Tests: `cd sdk/python && uv run --with pytest pytest test/`.
  104. - `sdk/node/` -- `gepa-research`, Node 18+, zero deps. Tests: `cd sdk/node && npm test`.
  105. ## TODO
  106. - [ ] Distributed evaluation via [Harbor](https://github.com/harbor-framework/harbor) -- run benchmarks in containers instead of locally, use Harbor's cloud providers to parallelize.
  107. - [ ] Pareto-frontier visualization in the dashboard using `GEPAResult.per_val_instance_best_candidates`.
  108. ## Acknowledgements
  109. GEPAResearch is a fork of [evoresearch](https://github.com/evo-hq/evo).
  110. ## License
  111. Licensed under the [Apache License 2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.