Doofus is a local-first research platform for evolving optimizers, prompts, policies, mutation strategies, and explicitly registered project parameters.

It combines quality-diversity search, nested meta-evolution, calibrated metacognition, versioned reference-suite evaluation, proof construction, runtime health, lineage, rollback, and an information-dense evidence dashboard.

The name is playful. The research question is not:

How do you let a system change itself aggressively without mistaking activity, a higher training score, or a lucky run for improvement?

Doofus answers with diversity before convergence, predictions before outcomes, reference-suite evidence before promotion, and recovery as part of the experiment rather than an afterthought.

Designed for: research teams that want optimization systems to expose diversity, uncertainty, calibration, lineage, and failed promotion—not merely a winning score.

Explore the ObtuseAI portfolio · Inspect the learning loops · Start a technical conversation

A naive optimizer follows one signal:

mutate -> score -> keep the highest score -> repeat

That loop is vulnerable to:

• overfitting the visible objective;
• converging on one brittle champion;
• exploiting scoring bugs;
• mistaking noise for progress;
• choosing costly strategies for marginal gains;
• forgetting why a candidate exists;
• promoting a candidate that cannot be replayed;
• corrupting the source or runtime when a trial regresses;
• allowing the controller to trust its own confidence without calibration.

Doofus expands the loop:

flowchart LR
    SEED["Seed + constraints"] --> VARIANTS["Diverse candidate generation"]
    VARIANTS --> VISIBLE["Visible arenas + scorecard"]
    VISIBLE --> ARCHIVE["Quality-diversity archive"]
    ARCHIVE --> CHALLENGE["Challenger tournament"]
    CHALLENGE --> FREEZE["Freeze candidate identity"]
    FREEZE --> HOLDOUT["Versioned reference suite"]
    HOLDOUT --> AUDIT["Promotion + safety audit"]
    AUDIT -->|"evidence clears floor"| ELITE["Retained elite"]
    AUDIT -->|"regression / uncertainty"| ROLLBACK["Rollback + lineage record"]
    ELITE --> NEXT["Next-cycle seed context"]
    ROLLBACK --> NEXT
    NEXT --> VARIANTS

Visible performance can earn a candidate the right to be tested. It cannot earn promotion by itself.

Doofus treats “the thing being optimized” and “the way optimization happens” as different evolutionary layers.

flowchart TB
    SUP["Recursive supervisor<br/>health + budgets + recovery"]
    META2["Loop 4<br/>threshold research"]
    META1["Loop 3<br/>metacognitive controller"]
    STRATEGY["Loop 2<br/>evolution strategy"]
    ARCHIVE["Loop 1<br/>population + MAP-Elites"]
    CANDIDATE["Loop 0<br/>candidate mutation"]
    SCORE["Arenas + evidence"]
    HOLDOUT["Frozen reference-suite evaluation"]
    GATE{"Promotion gate"}

    SUP --> META2
    META2 --> META1
    META1 --> STRATEGY
    STRATEGY --> ARCHIVE
    ARCHIVE --> CANDIDATE
    CANDIDATE --> SCORE
    SCORE --> GATE
    GATE -->|"eligible contender"| HOLDOUT
    HOLDOUT -->|"promote"| ARCHIVE
    HOLDOUT -->|"reject / abstain"| CANDIDATE

The loops share evidence. They do not share unrestricted authority.

The MAP-Elites and elite-archive surfaces preserve different kinds of good candidates rather than collapsing all progress into a single scalar leader.

Doofus tracks:

• behavior or trait niches;
• candidate and parent identity;
• mutation lineage;
• novelty pressure;
• elite, shadow-elite, and challenger states;
• archive growth and retirement;
• best-ever records;
• next-cycle seed context;
• upgrade and retest queues.

This matters when two candidates have similar average fitness but meaningfully different cost, risk, stability, or behavior. Diversity keeps the system from forgetting the safer or more transferable option.

Before a cycle, the metacognitive subsystem can record:

• expected outcome;
• confidence;
• predicted difficulty;
• resource and effort estimates;
• known uncertainty;
• strategy selection;
• abstention or escalation recommendation.

After the cycle, those predictions are compared with observed outcomes. Calibration, not rhetorical confidence, determines whether the controller is learning to predict its own performance.

The subsystem begins in shadow mode. Shadow mode means it records what it would have done and receives a score, but does not control the runtime decision. Promotion requires sustained, independently measured calibration and safety evidence.

Promotion is assembled from multiple evidence surfaces:

A high raw score can still be rejected for weak proof, instability, safety findings, or reference-suite regression.

Doofus includes a public, versioned reference suite across three task families. The committed tasks support deterministic comparison and regression detection; they do not claim secret evaluator custody or independence from the repository:

• optimization — candidate behavior on objective landscapes not exposed to the visible loop;
• code repair — bounded source-repair tasks evaluated through executable behavior;
• calibration — confidence and prediction quality against known outcomes.

The candidate is serialized and hashed before the reference tasks are evaluated. The report records:

• suite version and engine reference;
• frozen candidate identity;
• per-task score and details;
• task-family aggregates;
• weighted suite score;
• uncertainty and promotion verdict.

sequenceDiagram
    participant E as Evolution loop
    participant F as Freeze boundary
    participant H as Reference-suite runner
    participant G as Promotion gate

    E->>E: Optimize on visible objectives
    E->>F: Submit contender
    F->>F: Serialize and hash identity
    F->>H: Release frozen candidate
    H->>H: Run unseen task families once
    H->>G: Scores, uncertainty, provenance
    G-->>E: Promote, reject, quarantine, or abstain

The slower reference-suite workflow is opt-in on pull requests through the historical run-heldout label and can also be started manually. This keeps routine CI fast while making benchmark promotion an explicit act.

See the reference-suite benchmark protocol.

Doofus can tune an explicitly registered numeric parameter in another repository.

The contract requires:

• a named project and absolute root;
• a declared fitness command;
• an exact source file and parameter;
• a bounded numeric search space;
• source snapshot before mutation;
• isolated fitness execution with a sanitized environment;
• comparison against the previous accepted score;
• rollback on regression or failure;
• separate project and process gates before a change can remain applied.

flowchart LR
    REGISTER["Registered project<br/>root + target + fitness"] --> SNAPSHOT["Snapshot source"]
    SNAPSHOT --> MUTATE["Bounded candidate value"]
    MUTATE --> FITNESS["Sanitized fitness process"]
    FITNESS --> CHECK{"Non-regressing,<br/>valid evidence?"}
    CHECK -->|"no"| RESTORE["Restore exact snapshot"]
    CHECK -->|"yes"| REVIEW["Retain candidate evidence"]
    REVIEW --> APPLY{"Project auto_apply<br/>AND process gate?"}
    APPLY -->|"no"| SHADOW["Shadow result only"]
    APPLY -->|"yes"| SOURCE["Keep candidate change"]

The Doofus workspace, protected roots, and any path outside the registered project root are rejected.

Promising candidates often fail promotion because their evidence is incomplete rather than because their behavior is poor. The proof-builder lane makes that distinction visible.

It can:

• identify high-scoring rejected candidates;
• classify missing replay, stability, arena, lineage, or density evidence;
• queue bounded proof work;
• build replay and score-stability artifacts;
• track rescue budgets;
• report whether additional evidence changed the verdict;
• avoid changing the candidate while proof is being constructed.

This turns “almost passed” into a specific research question instead of an excuse to lower the threshold.

Always-on research introduces a second optimization target: operational reliability.

Doofus includes:

• heartbeats and process identity;
• duplicate-process detection;
• runtime and dashboard supervisors;
• on/off and emergency-stop controls;
• checkpoints and atomic JSON state;
• metrics-database failover;
• stale-state and contamination detection;
• baseline certification;
• capped calls, spend, pressure, and run windows;
• watchdog evidence and recovery reports.

Recovery state is part of the promotion story. A candidate is not operationally better if reaching it makes the system unrecoverable.

The NiceGUI dashboard is a live research observatory rather than a decorative status page.

It brings together:

• current candidate and best-known state;
• MAP-Elites and shadow-elite archive growth;
• lineage and mutation variants;
• visible, reference-suite, proof-density, and promotion scores;
• metacognitive predictions and calibration;
• model/provider usage and cost;
• safety, budget, and quarantine events;
• proof-builder queues and rescue outcomes;
• supervisor, watchdog, checkpoint, and failover health;
• promotion audits and full-run reports.

The dashboard reads evidence produced by the runtime. A chart does not become a gate merely because it is visible.

Suppose a project exposes a bounded THRESHOLD constant and a reproducible test command.

python scripts\doofus_register_project.py --add `
  --id my-project `
  --root C:\path\to\project `
  --fitness "python -m pytest -q" `
  --target "src\config.py:THRESHOLD:bounded tuning threshold"

python scripts\doofus_register_project.py --measure my-project

The baseline establishes whether the fitness command is valid and stable enough to support an experiment.

python scripts\doofus_register_project.py --enable my-project
python scripts\doofus_evolve_project.py my-project --generations 10

By default, results remain shadow evidence. To retain a source mutation, both the reviewed project configuration and the process-level DOOFUS_CODEEVOLVE_AUTO_APPLY=1 gate must be present. A failed or regressing fitness run restores the snapshot.

Review candidate lineage, parameter values, measured scores, subprocess evidence, rollback state, and whether either apply gate remained closed.

This is bounded parameter research, not permission for arbitrary code rewriting.

Requirements: Windows, Python 3.11+, and PowerShell.

git clone https://github.com/ObtuseAI/doofus.git
cd doofus
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest tests -q

Run the versioned reference-suite baseline:

.\.venv\Scripts\python.exe -m doofus.benchmarks `
  --engine-ref local `
  --out heldout-report.json

Launch the local evidence dashboard:

.\.venv\Scripts\python.exe -m doofus.dashboard.doofus_dashboard_app

The test suite, benchmark runner, and dashboard work without provider credentials. The runtime remains dry and provider-free when no optional provider is configured.

Optional research extras expose quality-diversity and agent-evolution integrations:

.\.venv\Scripts\python.exe -m pip install -e ".[sota]"

Review provider, cost, secret, and runtime policies before enabling any live model lane.

The public workflows separate routine correctness from expensive benchmark evidence:

Routine CI intentionally does not claim a long-running local evolution history exists on a fresh runner. Machine-local live-runtime tests are marked and isolated from clean-clone proof.

doofus/
|-- evolution/             candidates, archives, novelty, tournaments, lineage
|-- metacognition/         predictions, calibration, memory, abstention, control
|-- meta/                  strategy, prompt, gene, and external-project evolution
|-- benchmarks/            frozen reference-suite runner and task families
|-- scoring/               scorecards, proof density, promotion and quarantine
|-- proof/                 replay, stability, lineage, and rescue evidence
|-- runtime/               health, failover, process identity, recovery
|-- supervisor/            always-on coordination and watchdogs
|-- dashboard/             live research observatory
|-- model_router/          optional provider policies, validation, and ledgers
|-- safety/                budgets, switches, and secret boundaries
config/                    reviewed runtime and evolution policy
scripts/                   setup, experiments, validation, and operator controls
tests/                     clean-clone behavior and safety proof
docs/                      benchmark, operation, dashboard, and research guides
runtime/                   machine-local state, metrics, controls, and recovery

Recommended reading:

1. Metacognitive evolution — runtime modes, evidence loop, and authority.
2. Reference-suite benchmark protocol — task inventory and isolation.
3. External project guide — fitness contracts and bounded source experiments.
4. Safety boundary — mutation, providers, budgets, and recovery.
5. 24/7 autonomy policy — unattended-runtime constraints.
6. Dashboard guide — observability surfaces.
7. Security policy and contribution guide.

Doofus is useful to:

• researchers studying evolutionary optimization and quality diversity;
• agent engineers evaluating prompt, policy, or strategy adaptation;
• developers who need reversible tuning against an executable fitness command;
• teams exploring calibrated metacognition rather than self-reported confidence;
• operators who want a visible promotion and recovery trail for long-running experiments.

Doofus is experimental software.

A passing benchmark establishes performance only on the named tasks, suite version, seed policy, candidate identity, and environment represented in the report. It is not proof of general intelligence, universal optimization, production fitness, safety outside the tested boundary, or financial return.

Live provider and external-project modes can incur cost or modify source when separately enabled. Use isolated repositories, review every target and fitness command, protect credentials, and preserve recovery artifacts.

Doofus does not:

• guarantee that a fitness function measures what you intended;
• make a public reference suite immune to leakage or equivalent to an externally administered holdout;
• turn internal score growth into real-world improvement;
• remove the need for operator judgment;
• authorize arbitrary self-modification;
• promise that a long-running research process will discover a better candidate.

Sometimes the honest outcome is no promotion.

Citation metadata is available in CITATION.cff.

MIT © 2026 Chris Harris.