Skip to content
Back to search

agentdescent

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 13 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ThinkFlowLab/agentdescent with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ThinkFlowLab/agentdescent'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/thinkflowlab--agentdescent/badge.svg)](/listings/thinkflowlab--agentdescent)

HTML

<a href="/listings/thinkflowlab--agentdescent"><img src="/api/listings/thinkflowlab--agentdescent/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.

pip install "agentdescent[mcp]>=0.10.0"
agentdescent demo                         # a complete evolution, offline, no API key, ~10 s
agentdescent doctor                       # which agent CLIs and provider keys this machine has

Host / MCP default loop is **Path A** (`doctor` → `plan` → `start` → `apply`); advanced MCP tools need `agentdescent mcp --advanced` — see [docs/mcp-path-a.md](docs/mcp-path-a.md).

`[mcp]` adds the agent-facing MCP server and needs Python ≥ 3.10; the library itself supports 3.9, where you drop `[mcp]` and drive it with the CLI. Research examples are outside the wheel: to run `python -m examples.run_demo` or any algorithm port, clone the repo and follow [install and first run](docs/install.md#source-examples):

git clone https://github.com/ThinkFlowLab/agentdescent && cd agentdescent
pip install -e ".[dev,mcp]"

`agentdescent demo` builds a skill whose rules name the wrong CSV column, twelve cases with known totals and a local program as the agent, then runs the real loop — only the model is replaced — and ends with:

held-out reward: 1.000 outcomes: {'committed': 1}
what it learned: rules.md -> 'COLUMN: amount'

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 · 17 lines
  1. {
  2. "name": "agentdescent",
  3. "owner": {
  4. "name": "Birfy"
  5. },
  6. "metadata": {
  7. "description": "AgentDescent: evolve your skills, agents and plugins."
  8. },
  9. "plugins": [
  10. {
  11. "name": "agentdescent",
  12. "source": "./integrations/claude-code",
  13. "description": "Evolve skills, agents, prompts, code and plugins against examples with a parallel, merge-based optimiser.",
  14. "version": "0.10.0"
  15. }
  16. ]
  17. }
README.md · README · 279 lines
  1. # AgentDescent
  2. **[Website & interactive demo](https://thinkflowlab.github.io/agentdescent/)** ·
  3. [Get started](https://thinkflowlab.github.io/agentdescent/install/) ·
  4. [Documentation](https://thinkflowlab.github.io/agentdescent/docs/)
  5. > **Gradient descent — but the parameters are agents.** AgentDescent evolves
  6. > prompts, skills, agent directories, agent code and host plugins against your
  7. > own examples. *N* workers propose edits **in parallel**, one aggregator merges
  8. > them into a version-controlled artifact, and a held-out gate decides what is
  9. > kept. Use it from Python with one `evolve()` call, from the CLI, or from inside
  10. > Claude Code, Codex, OpenCode, DeepSeek Harness or Grok Bot — and swap in any of
  11. > the named algorithms or twenty-three published-method ports on the same engine.
  12. [![PyPI](https://img.shields.io/pypi/v/agentdescent)](https://pypi.org/project/agentdescent/)
  13. [![tests](https://github.com/ThinkFlowLab/agentdescent/actions/workflows/tests.yml/badge.svg)](https://github.com/ThinkFlowLab/agentdescent/actions/workflows/tests.yml)
  14. [![docs](https://img.shields.io/badge/docs-mkdocs--material-1f6feb)](https://thinkflowlab.github.io/agentdescent/)
  15. [![python](https://img.shields.io/badge/python-%E2%89%A53.9-1f6feb)](https://www.python.org/)
  16. [![license](https://img.shields.io/badge/license-MIT-3fb950)](https://github.com/ThinkFlowLab/agentdescent/blob/main/LICENSE)
  17. ## Install
  18. ```bash
  19. pip install "agentdescent[mcp]>=0.10.0"
  20. agentdescent demo # a complete evolution, offline, no API key, ~10 s
  21. agentdescent doctor # which agent CLIs and provider keys this machine has
  22. ```
  23. Host / MCP default loop is **Path A** (`doctor` → `plan` → `start` → `apply`); advanced MCP tools need `agentdescent mcp --advanced` — see [docs/mcp-path-a.md](docs/mcp-path-a.md).
  24. `[mcp]` adds the agent-facing MCP server and needs Python ≥ 3.10; the library
  25. itself supports 3.9, where you drop `[mcp]` and drive it with the CLI. Research examples are outside the wheel: to run
  26. `python -m examples.run_demo` or any algorithm port, clone the repo and follow
  27. [install and first run](docs/install.md#source-examples):
  28. ```bash
  29. git clone https://github.com/ThinkFlowLab/agentdescent && cd agentdescent
  30. pip install -e ".[dev,mcp]"
  31. ```
  32. `agentdescent demo` builds a skill whose rules name the wrong CSV column, twelve
  33. cases with known totals and a local program as the agent, then runs the real
  34. loop — only the model is replaced — and ends with:
  35. ```
  36. held-out reward: 1.000 outcomes: {'committed': 1}
  37. what it learned: rules.md -> 'COLUMN: amount'
  38. ```
  39. ## 60-second quickstart
  40. Runnable as-is — no API key, no dependencies. Three functions are the whole
  41. contract: how to run a task, how to score it, and what to propose on a failure.
  42. ```python
  43. from agentdescent import Task, evolve
  44. tasks = [Task(id=f"t{i}", prompt=f"item {i}") for i in range(12)]
  45. def reward(task, output): # must return [0, 1]
  46. return 1.0 if "2026" in output else 0.0
  47. def run(rendered, task): # your solver
  48. return "answer" + (" 2026" if "year" in rendered else "")
  49. def propose(rendered, task, output, reward): # what to add on a failure
  50. return "always state the year"
  51. result = evolve(tasks, reward, run=run, propose=propose,
  52. rounds=6, n_workers=3, max_concurrency=3)
  53. print(result.rendered, result.final_reward, result.error)
  54. ```
  55. ### With a real model and a real dataset
  56. Credentials are read from the environment at call time — never from code — and
  57. the base URL picks the provider
  58. ([every provider →](https://thinkflowlab.github.io/agentdescent/agents/#configuring-your-provider-and-key)):
  59. ```bash
  60. export OPENAI_BASE_URL=https://api.deepseek.com # or GLM, Ark, a local vLLM, OpenAI itself
  61. export OPENAI_API_KEY=sk-... # your key for *that* endpoint
  62. ```
  63. ```python
  64. from agentdescent import SingleSlot, evolve, openai_compatible, reflector, scorer, tasks_from
  65. from agentdescent.dataloader import hf_rows
  66. rows = hf_rows("hotpotqa/hotpot_qa", "validation", config="distractor", limit=40)
  67. model = openai_compatible(model="deepseek-v4-flash")
  68. tasks = tasks_from(rows, prompt="question", gold="answer") # rows -> Task objects
  69. run = lambda instruction, task: model(f"{instruction}\n\n{task.prompt}")
  70. result = evolve(tasks, scorer("exact"), run=run, propose=reflector(model),
  71. strategy=SingleSlot(initial_value="You are a helpful assistant."),
  72. rounds=8, n_workers=8, max_concurrency=8, held_out_frac=0.3,
  73. patience=3, target_reward=0.98)
  74. print(result.rendered) # the instruction it learned
  75. print(result.final_reward) # held-out reward
  76. print(result.outcomes()) # why it went that way
  77. ```
  78. On 40 HotpotQA items (12 held out) this took held-out exact match from **0.167
  79. to 0.583**, learning *"Respond with only the requested answer, omitting any extra
  80. explanation or restatement."* That evolves an **instruction** (`SingleSlot`), not
  81. an Agent Skill folder — for a library run `agentdescent demo --kind skill_library`.
  82. Pass `agent=LLMAgent(claude_code())` (or any
  83. [agent or LLM](https://thinkflowlab.github.io/agentdescent/agents/)) instead of
  84. `run`/`propose` to evolve against a tool-using CLI agent.
  85. [Quickstart — dataset to skill →](https://thinkflowlab.github.io/agentdescent/quickstart-skill/)
  86. ### From the CLI, on a file or directory
  87. ```bash
  88. agentdescent init ./my-skill --data cases.jsonl --out spec.json # cases: {"prompt": ..., "gold": ...} per line
  89. agentdescent plan spec.json # validates and prices it; runs nothing
  90. agentdescent evolve spec.json --detach
  91. agentdescent status # then: show <run_id>, apply <run_id> --dry-run, apply <run_id>
  92. ```
  93. Nothing is written back until `apply`, which backs up first.
  94. ## Call any algorithm
  95. Every named algorithm is a set of defaults over the same engine, selectable by
  96. name from the CLI, a spec, MCP, or the host plugins:
  97. ```bash
  98. agentdescent algorithms list # ace, archive_selection, dgm, evoskill, gepa, rrsi, skillopt, …
  99. agentdescent algorithms show gepa # what it changes, its parameters
  100. agentdescent algorithms run gepa ./prompt.txt cases.jsonl --rounds 1 --workers 1 # writes a spec and plans it
  101. agentdescent demo --algorithm archive_selection # watch one run offline
  102. ```
  103. In a spec it is one field — `"algorithm": "gepa"` or
  104. `{"name": "gepa", "params": {...}}` — and every explicit field still wins.
  105. [The catalog →](https://thinkflowlab.github.io/agentdescent/algorithms/)
  106. **Cards vs ports:** Path A names **cards** (wheel mechanism slices). The
  107. **twenty-three research ports** are source-only under `examples/` — same slug is
  108. not the same fidelity; never read a card run as paper numbers
  109. ([decision tree](https://thinkflowlab.github.io/agentdescent/algorithm-decision-tree/), #384).
  110. Ports run from a checkout, each with a `--dry-run` that needs no API key:
  111. * **Benchmark-faithful (8):** ACE · GEPA · EvoSkill · SkillOpt · ADAS · DGM ·
  112. OpenEvolve · ERA
  113. * **Microports and analogues (15):** PromptBreeder · AFlow · Self-Refine ·
  114. Reflexion · SICA · Gödel Agent · Voyager · SkillWeaver · Absolute Zero ·
  115. R-Zero · Agent0 · gskill · TextGrad · Dynamic Cheatsheet · Genesis
  116. ```bash
  117. python -m examples.gepa.gepa_prompt_evolution --dry-run
  118. python -m examples.ace.ace_context_evolution --model claude-haiku-4-5 --async # barrier-free
  119. ```
  120. Fidelity is declared per port and follows each project's *released code*;
  121. analogues are not benchmark reproductions.
  122. [All twenty-three, with measured results →](https://thinkflowlab.github.io/agentdescent/self-evolution-examples/)
  123. ## Add an algorithm
  124. * **A named card, in one PR** — a `build(ctx, params) -> Overrides` that fills
  125. [policy slots](https://thinkflowlab.github.io/agentdescent/policy-guide/) and
  126. `evolve()` knobs. Copy `agentdescent/algorithms/_TEMPLATE.py`, register it, and
  127. regenerate the catalog with `python -m tools.gen_algorithms_docs`.
  128. [Register a named Algorithm card →](https://thinkflowlab.github.io/agentdescent/algorithm-authoring/)
  129. * **From your own package** — no fork needed; expose it as an entry point and
  130. `agentdescent algorithms list` picks it up:
  131. ```toml
  132. [project.entry-points."agentdescent.algorithms"]
  133. my_method = "my_pkg:ALGORITHM"
  134. ```
  135. * **A full research port** — [porting checklist](docs/porting-checklist.md)
  136. (benchmark-faithful) or [MethodPolicy checklist](docs/porting-methodpolicy.md)
  137. (microports).
  138. ## Use it from your agent
  139. The same engine as a **plugin**: a shared skill teaches the host when to reach
  140. for it, an MCP server exposes `doctor / plan / start / status / show / apply /
  141. cancel / resume` (and the algorithm, audit and archive tools), and the CLI
  142. mirrors them, so a run started from an agent can be inspected from a shell.
  143. | host | install | then |
  144. |---|---|---|
  145. | Claude Code | `agentdescent install claude-code` | `claude --plugin-dir ~/.agentdescent/plugins/claude-code` |
  146. | Codex | `codex plugin marketplace add ThinkFlowLab/agentdescent && codex plugin add agentdescent@agentdescent` | `codex mcp list` |
  147. | OpenCode | `agentdescent install opencode` | `opencode mcp list` |
  148. | DeepSeek Harness | `agentdescent install dsh` | `dsh --profile web --dump-config \| grep agentdescent` |
  149. | Grok Bot | `agentdescent install grok-bot` (a scaffold, not one-click) | read `HOST.md`; MCP via `agentdescent mcp --transport streamable-http` behind an HTTPS tunnel |
  150. From a checkout, `bash scripts/setup-hosts.sh` installs AgentDescent and wires
  151. every agent CLI it finds. Then say *"improve this prompt against these
  152. examples"* inside the agent: it runs `doctor`, writes a spec, **quotes the call
  153. count before starting**, waits for your yes, runs detached, and asks again
  154. before it writes anything back. No cases yet is not a blocker — it drafts 8–20
  155. for you to check first.
  156. `kind` is `text`, `skill_dir`, `skill_library` (multi-file `*/SKILL.md` tree),
  157. `agent_dir`, `agent_code`, `policy_slot` — or **`plugin`**: the host plugins
  158. themselves are evolvable, each rollout in an isolated copy of the host with
  159. hooks and permissions frozen and a recursion guard. Flagship library demo:
  160. `agentdescent demo --kind skill_library`.
  161. [The plugin, step by step →](https://thinkflowlab.github.io/agentdescent/plugin-quickstart/)
  162. · [set it up and test it →](https://thinkflowlab.github.io/agentdescent/testing-guide/)
  163. ## How it works
  164. ![AgentDescent architecture: N workers roll out against ledger snapshots and emit
  165. diffs with evidence cards into a buffer; a single aggregator thread runs the
  166. five-stage merge pipeline and commits to a git-backed ledger; four pluggable
  167. seams sit under the components they select; the L0 governance layer gates the
  168. audit step.](https://raw.githubusercontent.com/ThinkFlowLab/agentdescent/main/docs/assets/architecture.png)
  169. Serial self-improvement is bounded at one accepted change per iteration;
  170. merging concurrent edits is the attempt to lift that bound. The analogy breaks
  171. exactly where the design lives: **gradients add, diffs do not**, so aggregation
  172. is conflict resolution, fusion, statistical acceptance and a transactional
  173. commit rather than averaging. The governance layer (red) is deliberately *not* a
  174. seam — a self-modifying system must not be able to replace its own evaluator.
  175. The figure is regenerated from TikZ by
  176. [`tools/gen_architecture_figure.py`](tools/gen_architecture_figure.py).
  177. **What you can replace.** Two `typing.Protocol` seams carry the algorithm:
  178. * **the strategy — what evolves.** `AppendRules` (lessons; proposals almost
  179. always fuse), `KeyedRules` (one entry per category), `FileTree` (a directory,
  180. one key per path), `SingleSlot` (one value; proposals always contradict), or
  181. your own three-method class. Its key space decides whether concurrent edits
  182. can fuse at all.
  183. * **eight policy slots — the rules of evolution:** `selection`,
  184. `task_sampler`, `proposal`, `staleness`, `conflict`, `fusion`, `acceptance`,
  185. `promotion`. Each defaults to the shipped rule; a driver *refuses* a field it
  186. cannot honour rather than ignoring it. Mechanisms that need state the
  187. pipeline does not keep take the `aggregator_factory` exit.
  188. [How to fill a slot →](https://thinkflowlab.github.io/agentdescent/policy-guide/)
  189. ## What it measures
  190. Every row names the setting that produced it; [the results
  191. page](https://thinkflowlab.github.io/agentdescent/results/) also reports the
  192. runs where there was nothing left to learn.
  193. | | measured | setting |
  194. |---|---|---|
  195. | An artifact held in **one key**, where a keyed union can never fuse | keyed union fuses **0 of 48** merges · reflective merge **42 of 48** | BBH `dyck_languages`, `GLM-5.2`, *N*=4, 4 seeds |
  196. | What that costs, at a pinned rollout budget | **40% fewer model calls** (95% CI 27–54%, same direction on every seed) | the same runs |
  197. | Wall-clock against a *faithful* serial control | median **6.8×** (three seeds, 3.1–9.5×) | GEPA on HotpotQA, *N*=4, 16 rollouts pinned |
  198. | The one-call path, end to end | held-out exact match **0.167 → 0.583** | 40 HotpotQA items, 12 held out |
  199. Quality is claimed only where the design can support it: intervals rather than
  200. *p*-values where a comparison cannot reach significance, and it says so.
  201. ## Documentation
  202. Full docs: **[thinkflowlab.github.io/agentdescent](https://thinkflowlab.github.io/agentdescent/)**.
  203. | | |
  204. |---|---|
  205. | **Start** | [Install](https://thinkflowlab.github.io/agentdescent/install/) · [The plugin, step by step](https://thinkflowlab.github.io/agentdescent/plugin-quickstart/) · [Quickstart — dataset to skill](https://thinkflowlab.github.io/agentdescent/quickstart-skill/) · [Evolve a directory](https://thinkflowlab.github.io/agentdescent/quickstart-directory/) · [Evolve agent code](https://thinkflowlab.github.io/agentdescent/quickstart-agent-code/) |
  206. | **Agents** | [Use it from your agent](https://thinkflowlab.github.io/agentdescent/plugins/) · [Set it up and test it](https://thinkflowlab.github.io/agentdescent/testing-guide/) · [Agents & LLMs](https://thinkflowlab.github.io/agentdescent/agents/) |
  207. | **Algorithms** | [Named algorithms](https://thinkflowlab.github.io/agentdescent/algorithms/) · [Register a card](https://thinkflowlab.github.io/agentdescent/algorithm-authoring/) · [Twenty-three ports](https://thinkflowlab.github.io/agentdescent/self-evolution-examples/) · [Port fidelity](https://thinkflowlab.github.io/agentdescent/port-fidelity/) |
  208. | **Engine** | [The `evolve()` method](https://thinkflowlab.github.io/agentdescent/evolution/) · [Strategies](https://thinkflowlab.github.io/agentdescent/strategies/) · [Policies](https://thinkflowlab.github.io/agentdescent/policies/) · [Architecture](https://thinkflowlab.github.io/agentdescent/architecture/) · [Concepts](https://thinkflowlab.github.io/agentdescent/concepts/) · [API reference](https://thinkflowlab.github.io/agentdescent/api/) |
  209. | **Results** | [Measured results](https://thinkflowlab.github.io/agentdescent/results/) · [Efficiency](https://thinkflowlab.github.io/agentdescent/efficiency/) · [Runtime matrix](https://thinkflowlab.github.io/agentdescent/matrix-overview/) |
  210. ## Citing, scope and contributing
  211. Use GitHub's **Cite this repository** button ([`CITATION.cff`](CITATION.cff));
  212. per-result raw data is in [`bench/results/`](bench/results/).
  213. A **research reference implementation**, not a production system. The novelty is
  214. a narrow engineering synthesis — concurrent, staleness-bounded,
  215. conflict-resolved diff-level merge over a git-backed versioned ledger — and its
  216. throughput premise is a testable hypothesis rather than community consensus.
  217. Contributions welcome: [CONTRIBUTING.md](CONTRIBUTING.md). The suite is offline
  218. and deterministic, so `pytest -q` needs no API key.

Ratings and comments

Sign in to rate this skill.

Sign in

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