Ask about the architecture, a command, or where a mechanism lives. Answers come from the ThinkFlowLab index; verify the source links.
',
+ '
',
+ '',
+ '',
+ '',
+ '
',
+ ''
+ ].join('');
+
+ document.body.appendChild(launcher);
+ document.body.appendChild(panel);
+
+ var log = panel.querySelector('#dw-log');
+ var form = panel.querySelector('#dw-form');
+ var input = panel.querySelector('#dw-input');
+ var send = panel.querySelector('#dw-send');
+ var close = panel.querySelector('#dw-close');
+ var newChat = panel.querySelector('#dw-new');
+ var emptyTemplate = log.querySelector('.dw-empty').cloneNode(true);
+ var busy = false;
+ var history = [];
+ var controller = null;
+
+ function scroll() { log.scrollTop = log.scrollHeight; }
+ function openPanel() {
+ panel.hidden = false;
+ launcher.setAttribute('aria-expanded', 'true');
+ input.focus();
+ }
+ function closePanel() {
+ panel.hidden = true;
+ launcher.setAttribute('aria-expanded', 'false');
+ launcher.focus();
+ }
+ function bindPrompts(root) {
+ Array.prototype.forEach.call(root.querySelectorAll('.dw-prompt'), function (prompt) {
+ prompt.addEventListener('click', function () {
+ input.value = prompt.getAttribute('data-q') || '';
+ form.requestSubmit();
+ });
+ });
+ }
+ function resetChat() {
+ if (controller) { controller.abort(); controller = null; }
+ history = [];
+ while (log.firstChild) log.removeChild(log.firstChild);
+ var empty = emptyTemplate.cloneNode(true);
+ log.appendChild(empty);
+ bindPrompts(empty);
+ input.value = '';
+ input.style.height = 'auto';
+ input.focus();
+ }
+
+ launcher.addEventListener('click', function () {
+ if (panel.hidden) openPanel(); else closePanel();
+ });
+ close.addEventListener('click', closePanel);
+ newChat.addEventListener('click', resetChat);
+ document.addEventListener('keydown', function (event) {
+ if (event.key === 'Escape' && !panel.hidden) closePanel();
+ });
+ document.addEventListener('click', function (event) {
+ if (!event.target || !event.target.closest) return;
+ var trigger = event.target.closest('[data-deepwiki-open]');
+ if (trigger) { event.preventDefault(); openPanel(); }
+ });
+
+ input.addEventListener('keydown', function (event) {
+ if (event.key === 'Enter' && !event.shiftKey) {
+ event.preventDefault();
+ form.requestSubmit();
+ }
+ });
+ input.addEventListener('input', function () {
+ input.style.height = 'auto';
+ input.style.height = Math.min(input.scrollHeight, 112) + 'px';
+ });
+
+ function escapeHtml(text) {
+ return String(text).replace(/[&<>"']/g, function (char) {
+ return ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[char];
+ });
+ }
+ function inline(text) {
+ var value = escapeHtml(text);
+ value = value.replace(/`([^`]+)`/g, '$1');
+ value = value.replace(/\*\*([^*]+)\*\*/g, '$1');
+ value = value.replace(/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g, '$1');
+ value = value.replace(/\[([^\]]+)\]\((\/[^\s)]+)\)/g, '$1');
+ return value;
+ }
+ function renderProse(text) {
+ var lines = text.split(/\r?\n/);
+ var html = '';
+ var paragraph = [];
+ var list = null;
+ function flushParagraph() {
+ if (paragraph.length) {
+ html += '
' + inline(paragraph.join(' ')) + '
';
+ paragraph = [];
+ }
+ }
+ function closeList() {
+ if (list) { html += '' + list + '>'; list = null; }
+ }
+ lines.forEach(function (raw) {
+ var line = raw.trim();
+ if (!line) { flushParagraph(); closeList(); return; }
+ var heading = line.match(/^(#{1,4})\s+(.*)$/);
+ if (heading) { flushParagraph(); closeList(); html += '
' + inline(heading[2]) + '
'; return; }
+ var unordered = line.match(/^[-*]\s+(.*)$/);
+ if (unordered) {
+ flushParagraph();
+ if (list !== 'ul') { closeList(); html += '
'; list = 'ul'; }
+ html += '
' + inline(unordered[1]) + '
';
+ return;
+ }
+ var ordered = line.match(/^\d+\.\s+(.*)$/);
+ if (ordered) {
+ flushParagraph();
+ if (list !== 'ol') { closeList(); html += ''; list = 'ol'; }
+ html += '
' + inline(ordered[1]) + '
';
+ return;
+ }
+ var quote = line.match(/^>\s?(.*)$/);
+ if (quote) { flushParagraph(); closeList(); html += '
' + inline(quote[1]) + '
'; return; }
+ paragraph.push(line);
+ });
+ flushParagraph();
+ closeList();
+ return html;
+ }
+ function renderMarkdown(text) {
+ var parts = String(text || '').split(/```[a-zA-Z0-9_-]*\n?([\s\S]*?)```/g);
+ var html = '';
+ for (var i = 0; i < parts.length; i += 2) {
+ if (parts[i]) html += renderProse(parts[i]);
+ if (i + 1 < parts.length) html += '
+## What it is good at
+
+| strength | in practice | go deeper |
+|---|---|---|
+| **Parallel and async search** | N workers propose diffs against ledger snapshots; the merger consumes evidence without waiting for a round barrier. | [Async](async.md) · [Parallelism](parallelism.md) |
+| **Diff-native merge** | Complementary edits union; contradicting edits are resolved or synthesized; a one-key artifact uses reflective merge. | [Aggregator](aggregator.md) · [Fusion policies](fusion-policies.md) |
+| **Evidence-bound acceptance** | A held-out gate, bootstrap/CI, canary, run health and cost decide what commits; missing evidence defers instead of inventing confidence. | [Trust evidence](trust-evidence.md) · [Trusted promotion](trusted-promotion.md) |
+| **Any artifact** | An instruction, a rule set, a directory, a program, a harness or your own state through the three-method `Strategy` contract. | [Strategies](strategies.md) · [Directory evolution](directory-evolution.md) |
+| **23 algorithm ports** | ACE, GEPA, DGM, OpenEvolve, Reflexion, Voyager and others run as plug-ins on the same engine, so scheduling is a controlled variable. | [All ports](self-evolution-examples.md) |
+| **Host integration** | Claude Code, Codex, OpenCode, DeepSeek Harness and any MCP client; local-first and model-agnostic. | [Plugins](plugins.md) · [Ask DeepWiki](deepwiki.md) |
+| **Governed change** | Blast radius, invariants, approval and a signed release path for harness or code changes. | [Governance](governance.md) · [Release](release.md) |
+
+!!! note "What it is not"
+
+ A research reference implementation, not a hosted product or a benchmark
+ leaderboard. The engine and the evidence layer are the product; a host agent
+ or a platform owns the UI. Missing evidence defers, and an unchanged artifact
+ is not repriced as a gain. Read [the main path](main-path.md) for the
+ supported surface and [the results page](results.md) for the caveats behind
+ every number.
+
+## How to use it
+
+1. **Install.** `pip install "agentdescent[mcp]>=0.10.0"`, or run the one-command
+ installer. `agentdescent doctor` shows which hosts and keys this machine has.
+ [Install and first run](install.md) · [The plugin in three commands](plugin-quickstart.md)
+2. **See the loop once, offline.** `agentdescent demo` runs a complete evolution
+ with no API key and no files changed:
+
+ ```bash
+ $ agentdescent demo
+ held-out reward: 0.000 -> 1.000 outcomes: {'committed': 1}
+ what it learned: rules.md -> 'COLUMN: amount'
+ ```
+
+ The [interactive demo](index.md#demo) walks through the same flow inside a
+ host agent.
+3. **Point it at your artifact.** From the CLI: `init → plan → evolve → show →
+ apply`. Inside an agent: `doctor → plan → start → status → show → apply`.
+ [Prompt or skill](quickstart-skill.md) · [Directory](quickstart-directory.md) ·
+ [Agent code](quickstart-agent-code.md)
+4. **Or call it from Python.** `evolve(tasks, reward, agent=..., strategy=...)`.
+ Unspecified policy slots use their defaults.
+ [The `evolve()` method](evolution.md) · [Strategies](strategies.md)
+5. **Read the evidence.** The report carries the decision, the evidence, the
+ cost and the next action. [Measured results](results.md) ·
+ [Trust evidence](trust-evidence.md) · [DeepWiki](deepwiki.md) for questions
+ about the code.
+
+## Self-evolution angles
+
+AgentDescent separates the loop into decisions you can replace. Choose the angle;
+keep the rest of the engine.
+
+| angle | the question | built-in levers | start with |
+|---|---|---|---|
+| **Artifact** | What changes? | instruction, keyed rules, append-only lessons, file tree, custom `Strategy` | [Strategies](strategies.md) |
+| **Proposal** | Who writes the next candidate? | reflection, population, genetic search, self-play, curator, code patch | [Proposal policies](proposal-policies.md) |
+| **Sampling** | Which tasks get a rollout? | round-robin, difficulty-weighted, failure-stratified | [Task sampling](sampling.md) |
+| **Selection** | Which candidates get evaluated? | single head, population, archive, quality–diversity | [Candidate selection](selection.md) |
+| **Merge** | How do concurrent edits combine? | keyed union, conflict resolution, reflective merge, tournament, custom aggregator | [Fusion policies](fusion-policies.md) · [Aggregator](aggregator.md) |
+| **Acceptance** | What evidence earns a commit? | Beta posterior, bootstrap/CI, canary, Goodhart, metamorphic, verifier, calibration | [Acceptance policies](acceptance-policies.md) · [Trust evidence](trust-evidence.md) |
+| **Promotion and staleness** | When is a version stable, and how do old snapshots age? | K survival rounds, bounded staleness, forced refresh | [Promotion policies](promotion-policies.md) · [Staleness](staleness.md) |
+| **Execution** | How does the search run? | serial, synchronous, barrier-free async, task/section/cluster parallelism, budgets | [Async](async.md) · [Parallelism](parallelism.md) · [Budget](budget.md) |
+| **Durability** | What survives and can be replayed? | git ledger, lineage, manifest, decision log, trajectory store | [Ledger](ledger.md) · [Manifest](manifest.md) · [Decision log](decisions.md) |
+| **Governance and accumulation** | What may a change touch, and what carries across runs? | blast radius, invariants, approval, release; experience, consolidation, meta-evolution | [Governance](governance.md) · [Experience](experience-cli.md) · [Meta-evolution](meta-evolution.md) |
+
+The 8 `Policies` slots, the `Strategy` contract and `aggregator_factory` are the
+seams. [Choosing policies](policies.md) · [Using the slots](policy-guide.md) ·
+[The main path](main-path.md).
+
## The three supported paths
| path | you have | the product surface |
@@ -39,6 +119,21 @@ capability belongs; it is the design contract, not another module list.
These are product surfaces over the same `evolve()` engine, not separate
algorithms. Each returns `schema_version: 1` and fails closed under `--json`.
+## New in 0.10.0
+
+The 0.10.0 line adds cost, scheduling, skill/harness tooling and host surfaces
+without changing the core loop:
+
+| area | what it adds | page |
+|---|---|---|
+| **Cost** | price each accepted diff and compare quality per cost, not only quality. | [Cost per accepted diff](cost.md) |
+| **Scheduling** | an expand-vs-evaluate HGM scheduler for where the next rollout goes. | [HGM scheduling](hgm.md) |
+| **Predictions** | predict whether an edit is worth paying for before the run. | [Edit predictions](predictions.md) |
+| **Skills** | lifecycle and drift audit for the skill bank; compile a skill into a tested function. | [Skill bank](skill-bank.md) · [Skill compilation](skill-compilation.md) |
+| **Harness** | a component manifest and edit contract for harness-level changes. | [Harness manifest](harness-manifest.md) |
+| **Hosts** | the zero-code DSH super-agent composition and the MCP/CLI Path A surface. | [DSH super-agent](dsh-super-agent.md) · [MCP / CLI Path A](mcp-path-a.md) |
+| **Algorithms** | choose a port by artifact and objective, not by name. | [Algorithm decision tree](algorithm-decision-tree.md) |
+
## Go deeper
**Understand the model.**
@@ -74,3 +169,8 @@ algorithms. Each returns `schema_version: 1` and fails closed under `--json`.
[API reference](api.md) · [Agents](agents.md) · [Plugins](plugins.md) ·
[Plugin quickstart](plugin-quickstart.md) · [Set it up and test it](testing-guide.md) ·
[Usage](usage.md).
+
+**Questions about the code?**
+[Ask DeepWiki](deepwiki.md) indexes the repository and answers with links to the
+source. The page also shows how to connect its MCP server to Claude Code, Codex,
+OpenCode or DeepSeek Harness and ask from your agent.
diff --git a/docs/github.md b/docs/github.md
index f3d14da7..528bb448 100644
--- a/docs/github.md
+++ b/docs/github.md
@@ -7,11 +7,11 @@ optional check run, so a human can review and merge it on GitHub.
```bash
agentdescent github publish --proposal proposal.json \
- --owner Birfy --repo agentdescent \
+ --owner ThinkFlowLab --repo agentdescent \
--token-env AGENTDESCENT_GITHUB_TOKEN # plan, no network
agentdescent github publish --proposal proposal.json \
- --owner Birfy --repo agentdescent --apply # write branch + PR + check
+ --owner ThinkFlowLab --repo agentdescent --apply # write branch + PR + check
```
Without `--apply` the command is a **plan**: it validates the proposal and
@@ -66,7 +66,7 @@ aborting a half-written publish.
## Status
```bash
-agentdescent github status --pr 757 --owner Birfy --repo agentdescent --json
+agentdescent github status --pr 757 --owner ThinkFlowLab --repo agentdescent --json
```
Returns the PR state, head/base, draft/mergeable and every check run. It is
@@ -106,7 +106,7 @@ requests in review bodies and inline comments — classifies them (`test`,
ready for a human click:
```bash
-agentdescent github review --pr 772 --owner Birfy --repo agentdescent --json
+agentdescent github review --pr 772 --owner ThinkFlowLab --repo agentdescent --json
```
The packet contains:
diff --git a/docs/index.md b/docs/index.md
index 2a19f73f..0cbb11b5 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,23 +3,26 @@ description: AgentDescent is a modular evolve engine for prompts, skills, progra
---
Prompts, skills, programs, agent harnesses, or your own artifact type. AgentDescent gives each a measurable evolution loop, with interchangeable modules for how candidates are proposed, selected, merged and accepted.
Diffs are the gradients; the aggregator is the optimizer.
Prompts, skills, programs, agent harnesses, or your own artifact type. AgentDescent gives each a measurable evolution loop, with interchangeable modules for how candidates are proposed, selected, merged and accepted.
AgentDescent is not tied to a prompt format. A Strategy represents your artifact as state and turns proposals into diffs. An actor tries tasks; a reward says what success means. The loop explores candidates, evaluates them and commits accepted changes to a versioned ledger.
01RepresentChoose a built-in Strategy or write your own
02ExploreRun and propose candidates in parallel
03Evaluate and mergeUse your reward and chosen policies
+
MEASURED, NOT PROMISED PROOF
Numbers with their setup.
Every row names the model, the split, the budget and the seed. The runs where nothing was left to learn are published too. This is a research reference implementation: read the caveats before quoting a number.
Single-seed rows are labeled; every headline links to the setup that produced it. Measured results ↗
+
THE MODULAR ENGINE 02 / 05
One evolve(). Many algorithms.
Keep the loop; change its decisions. Choose what the artifact is, who proposes edits, how work runs, and which candidates survive. Swap one module or supply your own optimizer.
The same entry point handles the task, reward, actor and artifact strategy. Unspecified policy slots use their defaults.
evolve(tasks, reward, agent=agent,
strategy=FileTree(files),
@@ -39,7 +42,24 @@ description: AgentDescent is a modular evolve engine for prompts, skills, progra
BUILT FOR THE WHOLE LOOP 05 / 05
Research flexibility. Engineering control.
AgentDescent includes the machinery around an algorithm: scheduling work, checking candidates, handling conflicts and keeping accepted versions. Use what you need; replace the parts your method changes.
DeepWiki indexes the repository and answers with links to the source. Use the Ask DeepWiki button in the bottom-right corner to chat here, or open the page to browse. The same MCP server works inside Claude Code, Codex, OpenCode or DeepSeek Harness.