root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): refresh with landing-page marketing and reel videos

Browse Source 
Rebuild the README with the runfusion.ai hero energy (tagline, badges,
feature grid, embedded reel/mesh/company videos) while retaining the
full technical reference — quick start, workflow diagram, model lanes,
automations/routines APIs, CLI examples, and dev commands. Drops the
Releases section (not ready yet).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
gsxdsm
2026-04-22 17:36:48 -07:00
parent e079704211
commit 72869891ba
1 changed files with 187 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

273
README.md
View File

@@ -1,78 +1,97 @@
<div align="center">
<img src="https://runfusion.ai/hermes-logo.svg?v=2" alt="Fusion" width="120" />
# Fusion
AI-orchestrated task board — specify, execute, and deliver tasks automatically.
### From rough idea to production code — automatically.
MIT licensed.
**Multi-node agent orchestrator** — tasks, agents, missions, git, files, and worktrees, with any model, local or cloud.
Like Trello, but your tasks get specified, executed, and delivered by AI — powered by [pi](https://github.com/badlogic/pi-mono).
[**runfusion.ai →**](https://runfusion.ai) · [Docs](./docs/README.md) · [GitHub](https://github.com/Runfusion/Fusion) · [npm](https://www.npmjs.com/package/@gsxdsm/fusion)
![Fusion dashboard board](demo/screenshot.png)
[![License: MIT](https://img.shields.io/badge/license-MIT-3fb950.svg)](./LICENSE)
[![npm](https://img.shields.io/npm/v/@gsxdsm/fusion.svg?color=58a6ff)](https://www.npmjs.com/package/@gsxdsm/fusion)
![Status](https://img.shields.io/badge/status-early%20preview-d29922.svg)
![Shipping](https://img.shields.io/badge/shipping-weekly-bc8cff.svg)
_Fusion dashboard board view_
<br />
Fusion is built on the great work of [dustinbyrne/kb](https://github.com/dustinbyrne/kb).
<video src="https://runfusion.ai/fusion-reel.mp4" poster="https://runfusion.ai/fusion-dashboard.png" autoplay muted loop playsinline width="900"></video>
**Fusion** turns rough ideas into production code. Describe a task, and an AI agent writes the spec, plans the implementation, writes the code in an isolated git worktree, and merges it — with automatic code review at every step. Manage a single project or coordinate across multiple repositories from one dashboard.
<sub>▶ [Watch the reel on runfusion.ai](https://runfusion.ai/fusion-reel.mp4)</sub>
## Documentation
<br />
For detailed guides, see the [Documentation Index](./docs/README.md).
<a href="https://runfusion.ai">
<img src="https://runfusion.ai/fusion-dashboard.png" alt="Fusion dashboard: Triage, Todo, In Progress, In Review, Done kanban columns with active task cards" width="900" />
</a>
| Guide | What it covers |
|---|---|
| [Getting Started](./docs/getting-started.md) | Installation and onboarding |
| [Dashboard Guide](./docs/dashboard-guide.md) | Board/list views, terminal, git manager |
| [Task Management](./docs/task-management.md) | Task lifecycle and CLI commands |
| [Settings Reference](./docs/settings-reference.md) | Configuration options |
| [Architecture](./docs/architecture.md) | System internals |
| [Agents](./docs/agents.md) | Agent management, spawning, heartbeat |
| [Workflow Steps](./docs/workflow-steps.md) | Quality gates, templates, phases |
| [Missions](./docs/missions.md) | Mission hierarchy, planning, autopilot |
| [Multi-Project](./docs/multi-project.md) | Central registry, isolation modes |
</div>
For Docker deployment, see [docs/docker.md](./docs/docker.md).
---
## Quick Start
## Your entire dev environment. On a single pane of glass.
Start the local dashboard:
Describe a task in plain language. A triage agent reads your project, understands context, and writes a full `PROMPT.md` spec — steps, file scope, acceptance criteria. Then Fusion plans, reviews, executes, and reviews again, in an isolated git worktree, with a human approval gate wherever you want one.
```bash
pnpm dev dashboard
One board. Controlled from anywhere. Laptop, Mac mini, Linux server, cloud VM, phone — all connected.
> Like Trello, but your tasks get specified, executed, and delivered by AI — powered by [pi](https://github.com/badlogic/pi-mono). Built on the great work of [dustinbyrne/kb](https://github.com/dustinbyrne/kb).
---
## The flow
```
① Describe ② Triage ③ The board ④ Isolated worktree
───────────── ───────────── ───────────── ─────────────────────
"Add dark mode → Agent writes → Plan → Review → → fusion/FN-123 branch
toggle to PROMPT.md Execute → Review concurrent, zero
settings panel" (steps, scope, (per step, until file conflicts
acceptance) done)
```
Then click the `Open:` URL printed in the terminal. It embeds a bearer token
(`http://localhost:4040/?token=fn_...`) that the browser captures to
`localStorage` on first visit and reuses automatically thereafter. See
[CLI reference → fn dashboard → Authentication](./docs/cli-reference.md#fn-dashboard)
for how to pin a stable token via `FUSION_DASHBOARD_TOKEN` or opt out with
`--no-auth`.
### See every step, before the merge
### First-run Setup
<div align="center">
<img src="https://runfusion.ai/screenshot-task-detail.png" alt="Fusion task detail: workflow steps visible on an in-progress task with diffs and file changes" width="820" />
</div>
On first launch, Fusion automatically opens the **onboarding wizard** with three guided steps:
Every task shows its plan, its reviews, its diffs, and its file changes in real time. Jump into an active task and nudge direction, tighten constraints, pause, or re-prompt.
1. **AI Setup** — Connect an AI provider and choose a default model
2. **GitHub (Optional)** — Connect GitHub for issue import and PR management
3. **First Task** — Create your first task or import from GitHub
---
The wizard is **dismissible and non-blocking** — click **Skip for now** to dismiss it and use the dashboard immediately. You can also re-trigger onboarding later from **Settings → Authentication → Reopen onboarding guide**.
## What makes it different
### Mobile
| | |
|---|---|
| 🧠 **AI specification** | Describe a task in plain language. Triage agents turn it into a `PROMPT.md` spec with steps, file scope, and acceptance criteria. |
| 🔁 **Workflow gates** | Plan → Review → Execute → Review on every step. Pre-merge gates block bad code; post-merge gates run informational checks. |
| 🌳 **Worktree isolation** | Each task runs in its own branch and worktree (`fusion/{task-id}`). Parallel tasks. Zero conflicts. |
| ⚡ **Smart merge** | Passing every gate? Fusion squash-merges and moves on. Opt into manual approval anywhere. |
| 🛰️ **Multi-node mesh** | Laptop, Mac mini, Linux server, cloud VM, phone — all synced. Desktop, mobile, web. |
| 🧩 **Any model** | Anthropic, OpenAI, Ollama — or anything pi-compatible. Local and cloud coexist. |
| 🏢 **Agent companies** | Import pre-built teams — 440+ agents across 16 companies — and run them autonomously for weeks. |
| 📬 **Inter-agent messaging** | Built-in mailbox between agents. Delegate, clarify, coordinate. |
| 🗺️ **Missions** | Hierarchical planning (Mission → Milestone → Slice → Feature → Task) with autopilot and validation contracts. |
| 🧪 **Self-improvement** | Agents reflect on their own output and update their prompts as they learn your codebase. |
| 🔓 **Open source. MIT.** | No vendor lock-in. Run it on your own hardware. Shipping weekly. |
For Capacitor + PWA workflow, see [MOBILE.md](./MOBILE.md).
---
## Workflow
## How it works
```mermaid
graph TD
H((You)) -->|rough idea| T["Triage\n<i>auto-specification</i>"]
T --> TD["Todo\n<i>scheduled for execution</i>"]
TD --> IP["In Progress\n<i>for each step:\nplan, review, execute, review </i>"]
H((You)) -->|rough idea| T["Triage<br/><i>auto-specification</i>"]
T --> TD["Todo<br/><i>scheduled for execution</i>"]
TD --> IP["In Progress<br/><i>for each step:<br/>plan, review, execute, review</i>"]
subgraph IP["In Progress"]
direction TD
NS([Begin step]) --> P[Plan]
P[Plan] --> R1{Review}
P --> R1{Review}
R1 -->|revise| P
R1 -->|approve| E[Execute]
E --> R2{Review}
@@ -81,8 +100,8 @@ graph TD
R2 -->|rethink| P
end
R2 -->|done| IR["In Review\n<i>ready to merge,\nor auto-complete</i>"]
IR -->|direct squash merge\nor merged PR| D["Done"]
R2 -->|done| IR["In Review<br/><i>ready to merge,<br/>or auto-complete</i>"]
IR -->|direct squash merge<br/>or merged PR| D["Done"]
style H fill:#161b22,stroke:#8b949e,color:#e6edf3
style T fill:#2d2006,stroke:#d29922,color:#d29922
@@ -97,11 +116,95 @@ graph TD
style D fill:#1a1a1a,stroke:#8b949e,color:#8b949e
```
Tasks with dependencies are processed sequentially. Independent tasks run in parallel.
Tasks with dependencies are processed sequentially. Independent tasks run in parallel. Optionally require manual approval before tasks move from Triage to Todo (`requirePlanApproval` setting).
In **Triage**, an AI agent reads your project, understands context, and writes a full `PROMPT.md` specification — steps, file scope, acceptance criteria. Optionally require manual approval before tasks move to **Todo** (`requirePlanApproval` setting).
---
## Core Features
## Runs everywhere. One board.
<div align="center">
<video src="https://runfusion.ai/fusion-mesh.mp4" poster="https://runfusion.ai/fusion-dashboard.png" autoplay muted loop playsinline width="820"></video>
<sub>▶ [Watch the mesh reel](https://runfusion.ai/fusion-mesh.mp4)</sub>
</div>
Laptop, Mac mini, Linux server, cloud VM, phone — every node is a peer. Your task state, agents, logs, and diffs stay synchronized across the mesh. Desktop (macOS Intel/Apple Silicon, Windows 10/11, Linux), mobile (iOS/iPadOS, Android), or any browser.
---
## Run an agent company
<div align="center">
<video src="https://runfusion.ai/fusion-company-reel.mp4" poster="https://runfusion.ai/screenshot-task-detail.png" autoplay muted loop playsinline width="820"></video>
<sub>▶ [Watch the company reel](https://runfusion.ai/fusion-company-reel.mp4)</sub>
</div>
Import a team. Run it autonomously for weeks. **440+ agents across 16 companies**, wired for missions, mailboxes, and inter-agent delegation.
```bash
npx companies.sh add paperclipai/companies/gstack
```
---
## Quick start
```bash
pnpm dev dashboard
```
Then click the `Open:` URL printed in the terminal. It embeds a bearer token
(`http://localhost:4040/?token=fn_...`) that the browser captures to
`localStorage` on first visit and reuses automatically thereafter. See
[CLI reference → fn dashboard → Authentication](./docs/cli-reference.md#fn-dashboard)
for how to pin a stable token via `FUSION_DASHBOARD_TOKEN` or opt out with
`--no-auth`.
Or install globally from npm:
```bash
npm install -g @gsxdsm/fusion
```
### First-run setup
On first launch, Fusion opens the **onboarding wizard** with three guided steps:
1. **AI Setup** — Connect an AI provider and choose a default model
2. **GitHub (Optional)** — Connect GitHub for issue import and PR management
3. **First Task** — Create your first task or import from GitHub
The wizard is **dismissible and non-blocking** — click **Skip for now** to use the dashboard immediately. Re-trigger it later from **Settings → Authentication → Reopen onboarding guide**.
### Mobile
For Capacitor + PWA workflow, see [MOBILE.md](./MOBILE.md).
---
## Documentation
| Guide | What it covers |
|---|---|
| [Getting Started](./docs/getting-started.md) | Installation and onboarding |
| [Dashboard Guide](./docs/dashboard-guide.md) | Board/list views, terminal, git manager |
| [Task Management](./docs/task-management.md) | Task lifecycle and CLI commands |
| [Settings Reference](./docs/settings-reference.md) | Configuration options |
| [Architecture](./docs/architecture.md) | System internals |
| [Agents](./docs/agents.md) | Agent management, spawning, heartbeat |
| [Workflow Steps](./docs/workflow-steps.md) | Quality gates, templates, phases |
| [Missions](./docs/missions.md) | Mission hierarchy, planning, autopilot |
| [Multi-Project](./docs/multi-project.md) | Central registry, isolation modes |
| [Docker](./docs/docker.md) | Container deployment |
---
## Core features
- **AI Specification** — Triage agent generates detailed `PROMPT.md` with steps, file scope, and acceptance criteria
- **Step-by-step Execution** — Plan → Review → Execute → Review cycle for each task step
@@ -109,11 +212,11 @@ In **Triage**, an AI agent reads your project, understands context, and writes a
- **Workflow Steps** — Configurable quality gates (pre-merge: blocks merge; post-merge: informational)
- **GitHub Integration** — Import issues, create PRs, real-time PR/issue badges
- **Dashboard** — Real-time kanban board, agent management, terminal, git manager, mission planner
- **Missions** — Hierarchical planning (Mission → Milestone → Slice → Feature → Task) with autopilot, validation contracts, fix-feature retries, and blocked-handoff semantics for systematic feature delivery.
- **Missions** — Hierarchical planning (Mission → Milestone → Slice → Feature → Task) with autopilot, validation contracts, fix-feature retries, and blocked-handoff semantics
- **Multi-Project** — Manage multiple projects from a single installation with project isolation
- **Inter-Agent Messaging** — Built-in messaging for coordination between agents and users
### Provider Authentication
### Provider authentication
Fusion supports OAuth-based authentication for AI providers configured via **Settings → Authentication**. When the dashboard is accessed via a non-localhost host (remote node, LAN host/IP, or reverse proxy), provider login URLs are automatically rewritten to route OAuth callbacks through a bridge endpoint (`/api/auth/openai-codex/callback`), ensuring the redirect reaches the active browser session.
@@ -121,11 +224,9 @@ Fusion supports OAuth-based authentication for AI providers configured via **Set
- **Other providers** — Authenticate via API key entry in Settings
- **pi authentication** — Handled separately via the `pi` CLI (`/login`) or `ANTHROPIC_API_KEY` environment variable
### Model System
### Model system
Fusion uses a dual-scope model hierarchy with five independent lanes. Global settings define baseline defaults, and project settings provide per-project overrides.
**Lanes:**
Fusion uses a dual-scope model hierarchy with five independent lanes. Global settings define baseline defaults; project settings provide per-project overrides.
| Lane | Purpose | Global Baseline Keys | Project Override Keys |
|------|---------|---------------------|----------------------|
@@ -141,18 +242,18 @@ Fusion uses a dual-scope model hierarchy with five independent lanes. Global set
For full settings documentation, see [Settings Reference](./docs/settings-reference.md).
### Scheduled Tasks / Automations
### Scheduled tasks / automations
Fusion supports scheduled task automation via the `/api/automations` endpoints. Automations can run shell commands or multi-step workflows on a configurable schedule.
#### Scheduling Scope
#### Scheduling scope
Automations and routines can run in two scopes:
- **Global** — Runs across all projects. Use this for cross-project maintenance, backups, or unified reporting.
- **Project** — Runs only within a specific project. Use this for project-specific CI, testing, or deployment tasks.
When you create a schedule without choosing a scope, Fusion defaults to **project scope** with the `default` project ID for backward compatibility. This ensures existing setups keep working exactly as before.
When you create a schedule without choosing a scope, Fusion defaults to **project scope** with the `default` project ID for backward compatibility.
To explicitly target a scope:
- In the dashboard **Scheduled Tasks** modal, use the **Global / Project** toggle.
@@ -170,8 +271,6 @@ To explicitly target a scope:
#### Automations
**Dashboard UI:** The Scheduled Tasks modal in the dashboard provides a Global/Project scope toggle in the header. When a project is active, the scope defaults to "Project"; otherwise it defaults to "Global". Schedules display a scope badge indicating their scope (global vs project). Project-scoped entries require an active project context.
| Endpoint | Method | Description |
|---------|--------|-------------|
| `/api/automations` | GET | List all automations (filtered by scope if specified) |
@@ -187,8 +286,6 @@ To explicitly target a scope:
Routines are AI agent tasks triggered by cron schedules, webhooks, or manual execution. Routines share the same global/project scope model as automations.
**Dashboard UI:** The Scheduled Tasks modal in the dashboard provides a Global/Project scope toggle in the header. When a project is active, the scope defaults to "Project"; otherwise it defaults to "Global". Routines display a scope badge indicating their scope (global vs project). Project-scoped entries require an active project context.
| Endpoint | Method | Description |
|---------|--------|-------------|
| `/api/routines` | GET | List all routines (filtered by scope if specified) |
@@ -201,29 +298,33 @@ Routines are AI agent tasks triggered by cron schedules, webhooks, or manual exe
| `/api/routines/:id/runs` | GET | Get execution history |
| `/api/routines/:id/webhook` | POST | Webhook trigger (signature verification supported) |
### Quick Examples
---
## CLI quick examples
```bash
fn task create "Fix the login bug" # Quick entry → triage
fn task plan "Build auth system" # AI-guided planning
fn task import owner/repo --labels bug # Import GitHub issues
fn task show FN-001 # View task details
fn task logs FN-001 --follow # Stream execution logs
fn task steer FN-001 "Use TypeScript" # Guide the agent mid-execution
fn task import owner/repo --labels bug # Import GitHub issues
fn task show FN-001 # View task details
fn task logs FN-001 --follow # Stream execution logs
fn task steer FN-001 "Use TypeScript" # Guide the agent mid-execution
fn project add my-app /path/to/app # Register a project
fn project list # List all projects
fn project add my-app /path/to/app # Register a project
fn project list # List all projects
fn settings set maxConcurrent 4 # Configure settings
fn settings export # Export configuration
fn settings set maxConcurrent 4 # Configure settings
fn settings export # Export configuration
fn mission create "Auth System" "Build auth" # Create mission
fn mission activate-slice <slice-id> # Activate a slice
fn mission create "Auth System" "Build auth" # Create mission
fn mission activate-slice <slice-id> # Activate a slice
fn skills search react # Search skills.sh
fn skills install firebase/agent-skills # Install agent skills
fn skills search react # Search skills.sh
fn skills install firebase/agent-skills # Install agent skills
```
---
## Packages
| Package | Description |
@@ -234,6 +335,8 @@ fn skills install firebase/agent-skills # Install agent skills
| `@fusion/tui` | Terminal UI — Ink-based CLI components |
| `@gsxdsm/fusion` | CLI + pi extension — published to npm |
---
## Development
```bash
@@ -246,7 +349,7 @@ pnpm typecheck # Type-check all packages
pnpm test # Run all tests
```
### Building a Standalone Executable
### Build a standalone executable
Build a single self-contained `fn` binary using [Bun](https://bun.sh/):
@@ -255,16 +358,14 @@ pnpm build:exe # Build for current platform
pnpm build:exe:all # Cross-compile for all platforms
```
## Releases
Packages are published to npm automatically via GitHub Actions and [changesets](https://github.com/changesets/changesets).
```bash
npm install -g @gsxdsm/fusion
```
See [RELEASING.md](./RELEASING.md) for the full workflow.
---
## License
ISC
MIT — open source, no vendor lock-in. See [LICENSE](./LICENSE).
<div align="center">
**[runfusion.ai →](https://runfusion.ai)**
</div>