fart-deluxe

Evolutionary multi-agent framework. Assign a task, spawn diverse agent personalities, let them compete and evolve across generations, and synthesize the best results.

Quick Start

npm install
cp .env.example .env
# Edit .env -- set OPENROUTER_API_KEY and TASK at minimum
npm start

That is it. The framework will:

1. Generate diverse agent personalities (SOULs)
2. Run them in parallel against your task
3. Have a super-model judge all outputs
4. Select the top performers, cull the rest
5. Birth a new generation from survivors
6. Repeat until max generations
7. Synthesize a final output from the best work

Results are written to output/RESULTS.md.

Configuration

All settings live in .env. Copy .env.example and edit.

Required

| Variable | Description | |----------|-------------| | OPENROUTER_API_KEY | Your OpenRouter API key | | TASK | The task description (be detailed) |

Agent Instances

| Variable | Default | Description | |----------|---------|-------------| | INSTANCE_COUNT | 10 | Parallel agents per generation | | INSTANCE_MODEL | anthropic/claude-haiku-4.5 | Model for worker agents |

Evolution

| Variable | Default | Description | |----------|---------|-------------| | MAX_GENERATIONS | 5 | Rebirth cycles | | SURVIVORS_TOP_PERCENT | 10 | Top X% survive | | SURVIVORS_MIN | 2 | Minimum survivors | | SURVIVORS_MAX | 10 | Maximum survivors | | CHILDREN_PER_SURVIVOR | 2 | Children per survivor |

Super-Model

| Variable | Default | Description | |----------|---------|-------------| | SUPER_MODEL | anthropic/claude-opus-4.6 | Evaluator model | | SUPER_MODEL_TEMPERATURE | 0.3 | Judge temperature |

Personality

| Variable | Default | Description | |----------|---------|-------------| | STORE_BEST_SOULS | false | Save best personalities to HALL_OF_FAME.md | | ELITISM | true | Carry best agent unchanged to next gen | | CROSSOVER_RATE | 0.2 | Chance of blending two parent souls |

Output

| Variable | Default | Description | |----------|---------|-------------| | VERBOSE | false | Print full agent outputs | | SAVE_GENERATIONS | true | Save per-generation data |

How It Works

The SoulForge

Every agent gets a unique cognitive identity defined across five axes:

• Epistemology -- how it knows (empirical, rationalist, intuitive, dialectical, phenomenological, pragmatic, skeptical, mystical)
• Temperament -- how it feels (urgent, contemplative, playful, grave, restless, serene, obsessive, detached)
• Methodology -- how it works (systematic, exploratory, reductive, holistic, iterative, revolutionary, minimalist, maximalist)
• Lens -- what metaphors it uses (mathematical, poetic, biological, architectural, musical, economic, mythological, mechanical)
• Voice -- how it speaks (terse, lyrical, clinical, conversational, aphoristic, narrative, interrogative, declarative)

8 values per axis = 32,768 unique combinations. The SoulForge guarantees no two agents in a generation share more than one axis value.

The Arena Loop

Each generation: all agents run in parallel, a super-model scores every output on relevance, originality, quality, and coherence. The top K survive. The rest are culled. Survivors birth children through soul mutation (keep some axes, resample others) or crossover (blend two parents). Fresh random souls fill any remaining slots to maintain population diversity.

Synthesis

After the final generation, the super-model reads all top outputs and produces a single definitive synthesis -- the combined intelligence of every surviving perspective.

Hall of Fame

When STORE_BEST_SOULS=true, the framework writes output/HALL_OF_FAME.md containing every winning personality with its score, generation, and full soul narrative. Copy these into future runs to seed known-good cognitive orientations.

Concepts

| Term | Meaning | |------|---------| | Soul | An agent's cognitive identity (5-axis personality) | | Generation | One full cycle: spawn, run, judge, select, rebirth | | Instance | A single agent in a generation | | SoulForge | The personality generator ensuring maximum diversity | | Arena | The orchestrator that runs the evolutionary loop | | Judge | The super-model that scores all outputs | | Synthesis | Final output combining the best work | | Hall of Fame | Stored best personalities for future reuse |

Supported Models

Any model on OpenRouter works. Examples:

| Model | Identifier | |-------|-----------| | Claude Opus 4 | anthropic/claude-opus-4.6 | | Claude Sonnet 4 | anthropic/claude-haiku-4.5 | | GPT-4o | openai/gpt-4o | | Gemini 2.5 Pro | google/gemini-2.5-pro-preview | | DeepSeek V3 | deepseek/deepseek-chat-v3-0324 | | Llama 3.1 405B | meta-llama/llama-3.1-405b-instruct |

Read More

See SOUL.md for the full philosophy behind personality-driven multi-agent cognition.

License

MIT