What is fanout?

<p align="center">
  <img src="assets/logo.png" alt="fanout logo" width="300">
</p>

# What is fanout?

Basically:

**Any-opt map/reduce primitives for agents**

Fanout is directly inspired my methods like GEPA and Alphaevolve, but gives more fine-grained control over the sampling, agentic optimizaiton, selection, and aggregation components of each to an orchestrating agent, like e.g. Claude Code (see claude/skill), allowing model sets, different materializer strategies for evaluation, among other things. This is useful any time you want to treat LLM outputs as a population rather than a single shot: code generation, prompt engineering, config tuning, creative writing, or any task where quality varies across models and samples. I'm considering adding backends to this as well, so you get large compute when needed.

In a nutshell, fanout takes a prompt, fans it out across multiple LLM models in parallel either via sampling or through agentic threads (the *map* phase), evaluates and scores every response, storing them in a common channel (possibly an SQLite, Redis, or in memory) then selects the best outputs to seed the next round (the *reduce* phase), this is then iteratively repeated. In a one-shot LLM response (sampling), this means repeating for N rounds, reuslting in evolutionary refinement — the same prompt is re-sampled, but each generation is informed by what worked before. In an agentic LLM thread (launching), agents communicate their solutions to each other via the channel, selecting solutions via selection strategies as they go along.

## How it works

There are two kinds of workflows: **Launch** (recommended) and **Sample**. Both fan out work across multiple models in parallel, but they differ in how solutions are produced and refined.

### Launch workflow (recommended)

The launch workflow spawns concurrent **agents** that autonomously iterate on solutions. Each agent reads the prompt, writes solutions, evaluates them, reads what other agents have produced, and improves — all in a shared solution pool. This is the recommended workflow: agents naturally explore diverse strategies, learn from each other in real time, and consistently outperform the sample workflow on optimization benchmarks.

<p align="center">
  <img src="assets/launch_workflow.png" alt="Launch workflow diagram" width="700">
</p>

Each agent runs for up to `--max-steps` iterations, using tools to read the task, submit solutions, run evaluations, and inspect other agents' work.

```bash
# Launch 3 agents, each with up to 10 steps
uv run fanout launch "Write a fast matrix multiply" \
  -m openai/gpt-4o-mini -n 3 --max-steps 10 --eval-script ./eval.sh -v
```

Use `--mode agent` in benchmark runners to use the launch workflow.

### Sample workflow

The sample workflow is a multi-round evolutionary loop. Each round samples solutions from models, evaluates them, selects the best, and uses those to seed the next generation. This is the classic map-reduce pattern applied to LLM outputs. It's useful when you want fine-grained control over selection strategies, or when agents aren't needed (e.g. simple prompt optimization).

<p align="center">
  <img src="assets/sampling_workflow.png" alt="Sample workflow diagram" width="700">
</p>

**Each round is one map-reduce cycle:**

1. **Fan out (map):** Send the prompt to one or more models, drawing N samples. Models can be specified explicitly (`-m`) or pulled from a weighted *model set* (`-M`).
2. **Evaluate:** Run every solution through a stack of evaluators — built-in (latency, cost, accuracy) or a custom eval script that tests the output for real.
3. **Select (reduce):** A selection strategy picks the top solutions. These become the parents for the next round.
4. **Repeat:** The loop runs for as many rounds as you want, converging on better outputs each generation.

## Install

### Prerequisites

Fanout uses **Redis** for persistent storage. Install the Redis server:

```bash
# macOS
brew install redis

# Ubuntu / Debian
sudo apt install redis-server
```

When you run fanout, it will automatically connect to Redis on `localhost:6379`, starting the server if it finds `redis-server` on your PATH. If Redis is unavailable, it falls back to an ephemeral in-memory store (data is lost when the process exits).

### Local development

```bash
git clone https://github.com/dimenwarper/fanout.git
cd fanout
uv sync
```

This installs fanout into a local virtualenv. Use `uv run fanout` to run it.

### System-wide install (CLI + Claude Code skills)

The install script does two things: installs the `fanout` CLI globally via `uv tool`, and registers `/fanout` and `/fanout-setup` as slash commands in Claude Code.

```bash
git clone https://github.com/dimenwarper/fanout.git
cd fanout
./install.sh
```

After install:
- **`fanout`** is available as a global command from any directory
- **`/fanout`** is available as a slash command in any Claude Code session — it walks you through running a fanout loop
- **`/fanout-s

... (truncated)