evoflux

<div align="center">
  <img src="web/public/brand-assets/evoflux-app-icon.png" width="88" height="88" alt="EvoFlux logo" />

  # EvoFlux

  **A complete, self-hosted agent harness — not a chatbot wrapper around an LLM.**

  Multi-agent teams, a real code knowledge graph, persistent wiki memory, any LLM you choose, and a native desktop app — all running on your machine.

  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
  [![Python 3.12+](https://img.shields.io/badge/python-3.12+-3776AB?logo=python&logoColor=white)](pyproject.toml)
  [![React 19](https://img.shields.io/badge/React-19-149ECA?logo=react&logoColor=white)](web/package.json)
  [![Tauri v2](https://img.shields.io/badge/Desktop-Tauri%20v2-FFC131?logo=tauri&logoColor=white)](desktop/)
  [![FastAPI](https://img.shields.io/badge/API-FastAPI-009688?logo=fastapi&logoColor=white)](app/)
  [![BYOM](https://img.shields.io/badge/BYOM-12%20providers-6E56CF)](#bring-your-own-model)

  [Quick Start](#quick-start) · [The Harness](#evoflux-as-an-agent-harness) · [Forge & Coding](#one-app-two-modes-forge-and-coding) · [Architecture](#architecture) · [Comparison](#how-evoflux-compares)

</div>

> **Note — from 30 June 2026 onwards:** All fixes, optimizations, and new features shipped to EvoFlux are developed and delivered using **EvoFlux Coding mode**. The agents build, review, and ship themselves.

---

## What is EvoFlux?

A **harness**, in the vocabulary the AI-agent field settled on through 2025–2026, is everything that sits between a language model and the real world: the code, configuration, and execution logic that decides what the model can see, what it's allowed to touch, how it recovers from its own mistakes, and whether anyone can tell what it actually did. The model generates text; the harness is what turns that text into safe, useful, repeatable action. It's also the reason the same underlying model performs differently in different products — harness quality has been shown to move a coding agent from the bottom of a benchmark leaderboard to the top five without touching the model at all.

EvoFlux is a harness built to that standard, shipped as software you run yourself: a FastAPI backend orchestrating role-based multi-agent teams that spawn members on demand from a shared mailbox rather than run them as always-on background loops, a tree-sitter-powered code knowledge graph, a memory engine that consolidates conversations into a long-term wiki, and a React 19 UI wrapped in a real Tauri desktop shell — Apache-2.0, with any LLM provider a config away.

## EvoFlux as an agent harness

Every capability below maps to a subsystem that ships today, not a roadmap slide.

![The five layers of the EvoFlux agent harness — tool orchestration, guardrails, context and memory, verification loops, and observability — sitting between any LLM provider and your local machine](documents/images/harness-anatomy.png)

## One app, two modes: Forge and Coding

Most agent products assume every conversation is about a codebase. EvoFlux doesn't: it splits into two modes at the top level, each with its own workspace model and its own agent roster.

| | **Forge** | **Coding** |
|---|---|---|
| Workspace | A fresh, disposable sandbox created per session — no project required | Your actual repo (or a multi-repo project) on disk, opened by path |
| Built for | One-off tasks: research, writing, prototyping a script, running a command, working with a document | Sustained work in a codebase you keep coming back to |
| Default team | `lead` + `consultant` + `executor` + `explorer` + `debate` | `lead` + `architect` + `coder` + `explorer` + `debate` |
| Extra tooling | — | Git (diff, commit, branch, merge, rebase, worktrees), the code knowledge graph, multi-repo project focus, a live file tree |
| Session lifetime | Ephemeral — gone when the session ends | Persistent — reopen the same workspace weeks later |

Both modes share the same lead-and-mailbox core, the same streaming UI, the same permission model. Ask Forge to "explain this codebase" or "fix a bug" and it will — the distinction isn't what kind of task, it's whether the work needs a permanent, git-aware workspace or a scratch space that disappears when you're done.

---

## Architecture

![EvoFlux system architecture — desktop app and browser client surfaces connect over HTTP and Server-Sent Events to a FastAPI backend housing the team manager, code graph, dream engine, permissions, scheduler, and MCP client, all persisting to SQLite or PostgreSQL, a markdown wiki, and any of twelve LLM providers](documents/images/system-architecture.png)

### How a multi-agent turn actually runs

There's no single "do everything" prompt. The lead decides when a task benefits from parallel work and spawns member instances that run concurrently, each dropping results into a shared mailbox the lead reads back from — the same event stream powers the UI's live Split and Monitor views.

![Sequence diagram of

... (truncated)