Runfusion/Fusion: A Multi-Agent Software Factory That Plans, Builds, and Merges in Isolated Worktrees

What Fusion Actually Does

Fusion is a multi-agent orchestrator that takes a plain-language task description and runs it through a pipeline: planning, review, execution, and review again. The README describes it as a software factory, an assembly line for code that spans tasks, agents, missions, git, files, and worktrees. The target user is a developer or team that wants to delegate coding work to AI but keep control over the process. It is not a code completion tool or a chat assistant. It is a project-level system that reads your repository, writes a plan, executes steps, and produces a merge-ready branch. The emphasis on isolated worktrees and human approval gates shows a bias toward safety over speed, which is a deliberate trade-off worth noting.

The Planning-to-Merge Flow

The core mechanism is visible in the README's flow diagram. First, you describe a task, like 'Add dark mode toggle to settings panel.' A planning agent reads the project and writes a PROMPT.md file containing steps, file scope, and acceptance criteria. Then Fusion plans, reviews, executes, and reviews again, all inside an isolated git worktree. Each task gets its own branch and worktree, named fusion/{task-id}, so parallel tasks do not conflict. The dashboard shows the plan, reviews, diffs, and file changes in real time. You can nudge direction, tighten constraints, pause, or re-prompt an active task. The workflow is not fully autonomous by default. There is a per-task or per-workflow oversight level: off, observe, steer, or autonomous. Merge and destructive actions always require explicit human confirmation. That is a meaningful constraint: even in autonomous mode, the final merge is gated.

Installation and First Run

The quick start is genuinely zero-install via npx. Running npx runfusion.ai launches the dashboard. Subcommands forward through the same entry point, for example npx runfusion.ai task create 'fix X'. There is also a one-line installer for macOS and Linux that auto-picks Homebrew or falls back to npm: curl -fsSL https://runfusion.ai/install.sh | sh. After that, fusion dashboard starts the UI. Homebrew users can run brew install runfusion/fusion/fusion. The npm global install gives you the fn command as an alias. From a clone, you run pnpm dev dashboard. On first launch, an onboarding wizard appears with three steps: AI setup, optional GitHub connection, and first task creation. The wizard is dismissible, so you can skip it and use the dashboard immediately. The dashboard URL embeds a bearer token, which the browser stores in localStorage. The server persists the token in ~/.fusion/settings.json after first authenticated run, unless you override it with --token, FUSION_DASHBOARD_TOKEN, or FUSION_DAEMON_TOKEN, or disable auth with --no-auth.

Storage: PostgreSQL by Default, SQLite as a Migration Input

A notable design decision is storage. The README states Fusion uses zero-config embedded PostgreSQL for local runtime metadata. Legacy SQLite files are one-time migration inputs only. That is a shift from the common SQLite default seen in many local-first tools. The rationale is likely multi-project and multi-node support: the README says to use a shared external database for those setups. This means a single-node local install gets a bundled PostgreSQL instance, which adds operational weight compared to a file-based database. For a tool that prides itself on zero install via npx, requiring a running PostgreSQL process, even embedded, is a hidden dependency. The benefit is a smoother path to scaling across nodes, but for a quick local experiment, it is heavier than expected. The docs referenced, storage.md and multi-project.md, presumably detail the migration path, but the README does not show the exact commands.

Worktree Isolation and the Worktrunk Option

Worktree isolation is a central feature. Each task runs in its own git worktree and branch, which allows parallel tasks without file conflicts. This is a concrete mechanism, not a marketing claim. The README also mentions an optional worktrunk delegation via the worktrunk.enabled setting, referencing a WorktreeBackend abstraction. That suggests the isolation logic is pluggable, not hardcoded to git worktrees. The benefit is clear: multiple agents can work on different features simultaneously without stepping on each other. The cost is disk usage and git overhead, since each worktree is a full checkout. For large repositories, that could be significant. The README does not discuss cleanup or pruning of old worktrees, which is a gap. If you run many tasks, you will accumulate branches and worktrees unless there is an automated removal mechanism, which is not documented in the supplied material.

Selectable Workflows and Oversight Levels

Fusion is not a single pipeline. The README lists built-in workflows for coding, quick fixes, review-heavy work, stepwise execution, plugin-gated Compound Engineering, and PR lifecycle fragments. You pick a workflow per task or author custom ones in the Workflow Editor. That flexibility is useful but also adds complexity. The oversight level is a separate setting: off, observe, steer, or autonomous. The README says merge and destructive actions always require explicit human confirmation. That means even at the autonomous level, the agent cannot merge without a human click. This is a safety feature, but it also means you cannot fully automate a release pipeline. If your goal is a hands-off bot that ships code overnight, this is the wrong tool. The distinction between workflows and oversight levels is not fully explained in the README, so you will need the settings-reference.md and workflow-editor.md docs to understand the interaction.

Limitations and Wrong-Tool Cases

The most obvious limitation is the beta status. The latest releases are v0.77.0-beta.9 and v0.77.0-beta.10, both from late August 2026. Beta software means APIs and storage formats can change. The README's comment about SQLite being a one-time migration input suggests breaking changes have already happened. Another limitation is the dependency on a running dashboard and daemon. The token persistence and auth setup imply a background process, not a one-shot CLI. If you want a simple script that runs a single agent and exits, Fusion is overkill. It is also not suited for tasks that require deep interactive debugging, since the agent works from a plan and reviews, not a live shell. The README does not mention support for non-coding tasks like DevOps or data migration. The emphasis is squarely on code changes. Finally, the onboarding wizard hides deprecated Gemini CLI and Antigravity providers, which means legacy users may find their setup path removed.

Alternatives and How They Differ

The README credits dustinbyrne/kb as foundational work, so that is a direct predecessor. The key difference is that Fusion adds a multi-agent orchestrator, a dashboard, worktree isolation, and PostgreSQL storage on top of kb's core. Another alternative is a single-agent CLI like GitHub Copilot CLI or Aider, which work on a single file or diff basis. Those tools do not plan across a project or manage parallel worktrees. They are simpler and lighter, but they lack the planning and review stages that Fusion enforces. A more comparable alternative is a CI-driven automation tool like GitHub Actions with a custom agent, but that requires you to build the planning and review logic yourself. Fusion gives you that logic out of the box, but you trade that for a heavier runtime and a learning curve. The choice depends on whether you want an assembly line or a power tool.

Editorial conclusion

Adopt Fusion if you want a self-hosted, model-agnostic orchestrator that plans, executes, and reviews coding tasks in isolated git worktrees with human approval gates. Skip it if you need a fully autonomous agent with no oversight or if you prefer a single-agent CLI for simple automations. Before adopting, verify the current release notes for v0.77.0-beta.9 and beta.10, check the docs for multi-project and multi-node setup with a shared external database, and confirm your model provider works with the planning and execution workflows. The project is MIT-licensed and under active beta development, so pin a specific version and test the approval gate behavior before relying on it for production merges.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes