<!-- studiomeyer-mcp-stack-banner:start -->

Part of the StudioMeyer MCP Stack — Built in Mallorca 🌴 · ⭐ if you use it

<!-- studiomeyer-mcp-stack-banner:end --> <div align="center">

darwin

<!-- badges -->

<!-- /badges -->**AI agents that improve themselves.**

Build AI agent teams that learn from every run.<br>Self-evolving prompts. A/B tested. Safety-gated.

Quick Start · Agents · How It Works · CLI · FAQ

</div>

npm install darwin-agents better-sqlite3
export ANTHROPIC_API_KEY=sk-ant-...  # or OPENAI_API_KEY, or use Claude CLI
npx darwin run writer "Explain quantum computing simply"

---

A note from us

We have been building tools and systems for ourselves for the past two years. The fact that this repo is small and has few stars is not because it is new. It is because we only just decided to share what we have built. It is not a fresh experiment, it is a long story with a recent commit.

We love building things and sharing them. We do not love social media tactics, growth hacks, or chasing stars and followers. So this repo is small. The code is real, it gets used, issues get answered. Judge for yourself.

If it helps you, sharing, testing, and feedback help us. If it could be better, an issue is more useful. If you build something with it, tell us at hello@studiomeyer.io. That genuinely makes our day.

From a small studio in Palma de Mallorca.

What is this?

Darwin is a TypeScript framework for building AI agents that automatically optimize their own prompts through experimentation, evaluation, and evolution.

Traditional AI agents use static prompts. You write them once, and they never improve. Darwin changes that:

1. Your agent runs a task
2. A Critic agent evaluates the output (quality, sources, structure)
3. After enough runs, Darwin detects patterns ("weak on technical topics")
4. It generates an improved prompt variant
5. A/B tests the new variant against the current one
6. The winner becomes the default — your agent got better, automatically

You run an agent
       │
       ▼
Darwin measures quality
       │
       ▼
Patterns emerge over time
       │
       ▼
New prompt variant generated
       │
       ▼
A/B tested against current
       │
       ▼
Winner becomes default
       │
Your agent got better.
You did nothing.

Why this isn't a toy. The loop runs behind a real production safety gate — regression rollback to last-known-good, data-quality guards that pause evolution during a tool outage, and an alignment check on every mutation so a rewrite can't quietly erode a safety constraint. It can drive that mutation with a GEPA reflective optimizer running online, inside the gate (not as an offline batch step), and the A/B gate supports sequential tests built for continuous monitoring (mSPRT / Hoeffding), which is a different thing from a fixed-n threshold checked repeatedly. How much better, measured rather than asserted: Hoeffding's boundary is proved, mSPRT's real type-I error still drifts from 0.059 to 0.069 as the horizon grows against a nominal 0.05, and the zero-config default is a plain margin heuristic with no calibrated α at all. What each one guarantees, what it only approximates, and the boundary we shipped wrong until v0.15 are all in statistical scope. Details: reflective evolution · statistical rigor.

Quick Start

# Install
npm install darwin-agents better-sqlite3

# Set your API key (or use Claude CLI if installed)
export ANTHROPIC_API_KEY=sk-ant-...

# Run your first agent
npx darwin run writer "Explain the CAP theorem in simple terms"

# Enable evolution
npx darwin evolve writer --enable

# Watch it improve over time
npx darwin status writer

Define your own agent in 12 lines

import { defineAgent } from 'darwin-agents';

export default defineAgent({
  name: 'summarizer',
  role: 'Text Summarizer',
  description: 'Summarizes text into key points.',
  systemPrompt: `Summarize the given text in 3 bullet points.
Be concise. No fluff. Capture the essence.`,
  evolution: {
    enabled: true,
    evaluator: 'critic',
  },
});

Reflective evolution — GEPA, online (v0.6, opt-in)

By default Darwin mutates prompts from aggregate stats. Turn on useGepa and the evolution loop instead generates each challenger with a GEPA-style reflector — it reads the recent critic feedback Darwin already collects and writes the smallest targeted edit that fixes the failure modes, then A/B-tests it against live traffic like any other variant. This is the part no other TypeScript framework ships: a GEPA reflective optimizer running inside a production safety gate, not as an offline batch job.

evolution: {
  enabled: true,
  evaluator: 'multi-critic',
  useGepa: true,                       // reflective generation instead of stats-meta-prompt
  reflectionModel: 'claude-opus-4-8',  // GEPA's leverage point — use a STRONGER model here
  paretoGate: true,                    // activate a challenger only if it's a true Pareto improvement
},

Everything degrades safely: with no critic feedback yet (cold start), on any reflector error, or if a mutation would erode a safety constraint, the loop falls back to the default optimizer. The same alignment guard now runs on both paths. Pair with requireConfidence plus confidenceMethod: 'msprt' on your SafetyThresholds for an A/B gate built for repeated looks. (requireConfidence alone selects the 'effect-size' heuristic, which has no calibrated α.) All of it is off unless you opt in — existing agents behave exactly as before.

Statistical rigor + coverage sampling (v0.7, opt-in)

v0.7 added sequential testing to the evolution loop and brought the GEPA optimizer closer to the paper. (One of those tests was wrong until v0.15; see statistical scope.) Every piece is additive and off by default (one exception: the feedback window default rose from 5 to 15):

import { SafetyGate, DarwinLoop } from 'darwin-agents';

// Sequential A/B gate, built for peeking after every run.
// 'msprt' is the one that can resolve realistic lifts at these run counts.
// It is NOT calibrated here: see "Statistical scope" for the measured error.
const safety = new SafetyGate({
  minDataPoints: 10,
  maxRegression: 0.2,
  failureRollbackThreshold: 3,
  requireConfidence: true,
  confidenceMethod: 'msprt',   // Mixture SPRT. 'hoeffding' is σ-free but needs
                               // ~900 runs per arm even for a 0.2 composite
                               // gap, ~20x the quality component we measured.
});

const loop = new DarwinLoop({
  memory, tracker, optimizer, safety, patterns, agent,
  embed: myBatchEmbedder,      // opt-in semantic alignment guard (zero hard deps — injected)
});

• mSPRT / Hoeffding confidence sequences: a margin win is adopted only when it clears a significance bar designed for repeated looks, so monitoring after every run no longer inflates false positives the way a fixed-n threshold does. Read statistical scope before relying on either one. 'msprt' is the method to reach for.
• ε-Pareto gate (evolution.paretoEpsilon) — forgive a microscopic regression on one objective when a challenger wins decisively on another.
• Instance-wise coverage sampling (useCoverage + per-variant perKeyScores) — GEPA Algorithm 2: keep/sample the variants that excel on the most different task subsets, not N copies of the global-average winner.
• System-aware merge (useMerge + mergeEveryK) — every K-th cycle, merge the two best Pareto-front prompt versions in the agent's history into one challenger (paper Appendix-D, ~+5% lift), instead of a reflective mutation.
• Semantic alignment guard — a reworded safety constraint is no longer a false rejection; a removed one still is (fail-closed without an embedder).
• Epoch-shuffled reflection minibatch (reflectionMinibatchSize) + a configurable feedbackWindow (default 15).
• Style-bias-free judging (normalizeForJudging): strip markdown before the critic scores, so it measures content not formatting.

Statistical scope: what the sequential tests do and do not guarantee

Darwin is applied engineering that borrows from the sequential-testing literature. It is not a statistics library, and this section says exactly where the line runs, because "always-valid" is a phrase that gets thrown around and we threw it around too loosely ourselves.

We shipped a Hoeffding boundary whose stated proof does not work, from v0.7 through v0.14. It used w(n) = R·√(ln((n+1)/α) / (2n)) and the code called it "a standard union-bound time-uniform Hoeffding bound". That boundary allows 2α/(n+1) of the error budget at every look, and Σ 2α/(n+1) diverges, so the union bound never closes and the justification establishes nothing. Being exact about the scope of that, because not overclaiming is the point: what is refuted is the argument, not the boundary. A divergent chain of upper bounds does not prove the true crossing probability diverges. Nobody has produced a construction that covers it either, and we are not going to gate promotions on an unproven bound. Both arms also spent the full α rather than α/2, so even the nominal accounting was off by a factor of two. Note the limit of that statement: since the per-arm boundary had no established level in the first place, this is a bookkeeping error in the allocation, not a proof that the old procedure ran at 2α. Both are fixed in v0.15, and tests/sequential-coverage.test.ts now re-derives the α-spend numerically instead of asserting it in a comment: the corrected schedule converges to the budget, the old one is shown diverging past it. Related reading: Howard, Ramdas, McAuliffe and Sekhon, Time-uniform, nonparametric, nonasymptotic confidence sequences, which makes the same point about pointwise Hoeffding intervals.

Where each method stands today:

| | What is guaranteed | The honest caveat | |---|---|---| | 'msprt' (the practical choice) | Mixture SPRT over the difference in means, prior δ ~ N(0, τ²), reject at Λ ≥ 1/α. Valid under repeated looks given a known variance AND a Gaussian (or suitably sub-Gaussian) sampling model. The mixture likelihood ratio is built from a Gaussian likelihood, so a known variance on its own is not enough, and Darwin has neither. |