openfusion

KO | EN

gitlite — search

#javascript #hacktoberfest #react #llm #android #rust #deep-learning #docker #macos #java #awesome #cli #mcp #openai

(★ 12)

Best-of-N and consensus CLI for multiple LLM backends

openfusion Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# OpenFusion

**Don't pick a model. Pick a panel.**

OpenFusion is a local-first CLI for running the same prompt through multiple LLM backends and getting one synthesized answer. Use it for model consensus, best-of-N answers, code review, CI gates, and local OpenAI-compatible routing.

OpenFusion works with API providers, local models, and installed agent CLIs:

- OpenRouter
- OpenAI-compatible APIs: OpenAI, LiteLLM, vLLM, LM Studio, LocalAI, etc.
- Anthropic / Claude API
- Ollama
- Codex CLI
- Claude Code CLI
- Gemini CLI
- Any custom non-interactive command

## Install

Requires Rust/Cargo. If you do not have Cargo yet, install it with [rustup](https://rustup.rs/).

```bash
cargo install --git https://github.com/nachoiacovino/openfusion
openfusion --help
```

If your shell cannot find `openfusion` after install, add Cargo's bin directory to PATH:

```bash
export PATH="$HOME/.cargo/bin:$PATH"
```

## Update

After a new commit lands on GitHub, reinstall from the same Git URL with `--force`:

```bash
cargo install --git https://github.com/nachoiacovino/openfusion --force
```

If you installed from a local checkout instead, pull and reinstall:

```bash
git pull
cargo install --path . --force
```

From a local checkout:

```bash
git clone https://github.com/nachoiacovino/openfusion.git
cd openfusion
cargo install --path .
```

For coding agents that use [skills.sh](https://skills.sh/), preview the companion skill install command, then opt in explicitly:

```bash
openfusion skills install          # dry-run; prints the npx command only
openfusion skills install --yes    # actually writes agent skill files
```

## Quick start

Create a starter config and verify the setup:

```bash
openfusion init
openfusion list
openfusion doctor
```

`openfusion init` prefers logged-in local CLIs: Codex, Claude Code, and Gemini. It makes a tiny live probe before enabling each one, so a new user with Codex or Claude already installed and logged in does not need an API key to start. To generate config without live model calls, use `openfusion init --no-probe`.

Then run a prompt:

```bash
openfusion ask "What is the biggest risk in this launch plan?"
```

Long-running calls print queue/progress events to stderr before the final stdout answer, for example:

```txt
openfusion: strategy consensus: queued 3 candidate call(s)
openfusion: calling claude (opus-4.8)...
openfusion: calling codex (gpt-5.5)...
openfusion: candidate claude finished ok in 42137ms
openfusion: judging with claude (opus-4.8)...
```

Progress is intentionally on stderr so stdout remains parseable when JSON is selected automatically or explicitly. Use `--quiet` to suppress it.

Show each model's answer before the final synthesis:

```bash
openfusion ask --show-candidates "Should this PR merge?"
```

Run the fastest successful backend:

```bash
openfusion ask --strategy race "Give me a one-sentence answer."
```

## Common commands

```bash
openfusion init                         # create global config
openfusion init --local                 # create ./openfusion.toml for this project
openfusion list                         # show runners and strategies
openfusion doctor                       # live-check keys, local servers, and CLI model calls
openfusion keys set openrouter          # store key in OS keychain
openfusion keys list                    # list stored/discovered key refs
openfusion keys list -c ./other.toml     # include refs from an explicit config
openfusion keys check openrouter        # verify key exists without printing it
openfusion ask "Question..."            # markdown on a terminal; JSON when piped
openfusion ask --format json "Q"        # force machine-readable trace
openfusion ask --format markdown "Q"    # force human-readable answer
openfusion ask --quiet "Question"       # suppress progress/status lines
openfusion review src/main.rs           # code review panel
openfusion ci-gate src/main.rs          # JSON verdict + non-zero exit on fail
openfusion serve --port 8787            # local OpenAI-compatible API
```

## Configuration

`openfusion init` writes a global user config. On macOS this is usually:

```txt
~/Library/Application Support/openfusion/config.toml
```

On Linux it is usually:

```txt
~/.config/openfusion/config.toml
```

For a project-specific override, run:

```bash
openfusion init --local
```

Config resolution order:

1. `--config path/to/config.toml`
2. `./openfusion.toml`, if present
3. global user config

Secrets are not stored in TOML. Config stores key references like `api_key_ref = "openrouter"`; the key itself lives in the OS keychain.

## Add API keys

```bash
openfusion keys set openrouter      # paste key securely
openfusion keys set openai
openfusion keys set anthropic
openfusion keys list -c ./openfusion.toml
openfusion keys check openrouter
openfusion keys remove openrouter
```

Import from an existing environment variable:

```bash
openfusion keys set openrouter --value-env OPENROUTER_API_KEY
```

Example OpenRouter runner:

```toml
[[runners]]
name = "qwen-cheap"
kind = "openrouter"
model = "qwen/qwen3.5-flash-02-23"
api_key_ref = "openrouter"
api_key_env = "OPENROUTER_API_KEY" # fallback if keychain is missing
weight = 0.8
max_tokens = 900
```

## Backends

### OpenAI-compatible APIs

Use this for OpenAI, LiteLLM, vLLM, LM Studio, LocalAI, and compatible proxies.

```toml
[[runners]]
name = "openai-small"
kind = "openai_compat"
base_url = "https://api.openai.com/v1"
model = "gpt-4o-mini"
api_key_ref = "openai"
api_key_env = "OPENAI_API_KEY"
weight = 0.8
```

### Anthropic / Claude API

```toml
[[runners]]
name = "claude-api"
kind = "anthropic"
model = "claude-sonnet-4-5"
api_key_ref = "anthropic"
api_key_env = "ANTHROPIC_API_KEY"
max_tokens = 1200
weight = 1.0
```

### Ollama

```bash
ollama serve
ollama pull llama3.2
```

```toml
[[runners]]
name = "ollama"
kind = "ollama"
base_url = "http://localhost:11434"
model = "llama3.2"
weight = 0.3
```

### LM Studio

Start the LM Studio local server, then use an OpenAI-compatible runner:

```toml
[[runners]]
name = "lmstudio"
kind = "openai_compat"
base_url = "http://127.0.0.1:1234/v1"
api_key_env = "LOCAL_LLM_API_KEY"
model = "your-loaded-model"
weight = 0.4
```

For local servers that do not require a real key:

```bash
export LOCAL_LLM_API_KEY=local
```

### Codex CLI

Requires `codex` installed and logged in.

```toml
[[runners]]
name = "codex"
kind = "codex"
model = "gpt-5.5"
weight = 1.2
```

### Claude Code CLI

Requires `claude` installed and logged in.

```toml
[[runners]]
name = "claude"
kind = "claude"
model = "opus-4.8"
weight = 1.1
```

### Gemini CLI

Requires `gemini` installed and logged in or configured.

```toml
[[runners]]
name = "gemini"
kind = "gemini"
model = "gemini-3-pro"
weight = 1.0
```

### Any CLI

Wrap any command that can take a prompt non-interactively:

```toml
[[runners]]
name = "custom-cli"
kind = "process"
command = "your-ai-cli"
args = ["--non-interactive", "{{prompt}}"]
extract = "text"
weight = 0.7
```

## Strategies

Strategies decide which runners are called and how the final answer is produced.

```toml
[[strategies]]
name = "consensus"
type = "consensus"
runners = ["qwen-cheap", "claude", "codex"]
judge = "qwen-cheap"
```

Available strategy types:

- `consensus` — ask multiple runners, then ask a judge to synthesize.
- `best-of-n` — run multiple attempts, then choose/synthesize the best answer.
- `review` — code-review prompt for bugs, false positives, and recommendations.
- `fallback` — try runners in order until one succeeds.
- `race` — run candidates in parallel and return the first successful answer.

Run the same runner multiple times with `runner*N`:

```toml
[[strategies]]
name = "best-of-qwen"
type = "best_of_n"
runners = ["qwen-cheap*5"]
judge = "qwen-cheap"
```

## Reasoning controls

Each runner can have its own reasoning profile.

```toml
[[runners]]
name = "fast-scout"
kind = "openrouter"
model = "qwen/qwen3.5-flash-02-23"
reasoning_effort = "low"        # minimal | low | medium | high
reasoning_budget_tokens = 512
reasoning_include = false
max_tokens = 700

[[runners]]
name = "deep-judge"
kind = "openai_compat"
base_url = "https://api.openai.com/v1"
api_key_ref = "openai"
api_key_env = "OPENAI_API_KEY"
model = "gpt-5.1"
reasoning_effort = "high"
reasoning_budget_tokens = 4096
reasoning_include = true
max_tokens = 2000
```

Provider-specific request fields can be passed through with TOML inline tables:

```toml
reasoning_extra = { summary = "auto" }
extra_body = { top_p = 0.9, seed = 42 }
```

## Code review and CI gates

Review one or more files:

```bash
openfusion review src/main.rs templates/openfusion.toml
```

Use `ci-gate` when you want a strict pass/fail result for automation:

```bash
openfusion ci-gate src/main.rs
```

`ci-gate` prints JSON and exits non-zero on failure.

OpenFusion is agent-friendly without making direct human runs ugly: `ask` and `review` default to Markdown when stdout is a terminal, and JSON when stdout is piped/non-TTY. Progress messages always go to stderr. Use `--format json` or `--format markdown` to override detection, and `--quiet` to silence stderr for automation.

## OpenAI-compatible API mode

Start the local server:

```bash
openfusion serve --port 8787
```

Point any OpenAI-compatible client at it:

```bash
export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
export OPENAI_API_KEY=local
```

Strategies appear as models:

```txt
openfusion/consensus
openfusion/best-of-n
openfusion/review
openfusion/fallback
```

Example request:

```bash
curl http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openfusion/consensus",
    "messages": [{"role":"user","content":"Give one launch risk."}]
  }'
```

Streaming/SSE mode is supported:

```bash
curl http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"openfusion/consensus","stream":true,"messages":[{"role":"user","content":"Give one launch risk."}]}'
```

Note: for CLI-backed runners such as Codex, Claude Code, Gemini, or `process`, OpenFusion receives the complete runner response and then splits it into small SSE deltas. This is OpenAI-client-compatible incremental framing, not true upstream token-by-token latency.

## Agent-friendly discovery

Commands agents should know:

```bash
openfusion init                  # write starter config
openfusion list                  # show runners/strategies
openfusion doctor                # check installed CLIs/env keys/local servers
openfusion ask                   # markdown on TTY; JSON when piped/non-TTY
openfusion ask --format json      # force machine-readable trace
openfusion ask --format markdown  # force human-readable answer
openfusion review FILES...        # same TTY-aware output behavior
openfusion ci-gate FILES...      # strict JSON + non-zero exit on fail
openfusion serve                 # local OpenAI-compatible API
```

## Agent skill

OpenFusion includes a companion skill for agents that use [skills.sh](https://skills.sh/):

```bash
openfusion skills install                                # preview only
openfusion skills install --global --yes                 # install globally/user-level
openfusion skills install -g -y --agent claude-code      # limit to one agent
openfusion skills install -g -y --agent claude-code --skill openfusion-consensus
```

Equivalent commands:

```bash
npx skills add nachoiacovino/openfusion --global --yes
npx skills add nachoiacovino/openfusion --global --yes --agent claude-code --skill openfusion-consensus
```

## Safety

OpenFusion does not write API keys into config files. API keys set with `openfusion keys set` are stored in the OS keychain, with environment variables as an explicit fallback.

Agent CLIs can run tools or commands depending on their own configuration. OpenFusion's built-in Codex adapter uses read-only sandboxing and ephemeral sessions. For arbitrary `process` runners, choose safe flags and commands for your environment.

openfusion

openfusion Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

openfusion

openfusion Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README