642a4fa264
One branch, one PR, per the consolidation directive. Contents file-by-file below. **Supersedes #2625** (its overlapping conversions landed via U11's #2624/#2626/#2636; only the parts nobody else did are folded here). **#2630 and #2639 stay open** — both green with zero threads, per rule 3. ## Four live defects, each measured **1. Every planning card renders an actions menu.** `TaskContextMenu.tsx` still had `shouldShowActionsMenu: task.column !== "triage"` on main *after* the rest of that file was converted. Since #2515 removed the id, the condition is TRUE for every card, so the suppression stopped applying anywhere — including on cards whose menu is empty, the orphaned click target the Surface Enumeration rule exists to catch. Found **twice independently**: by reading the guard, and again by the invariance test below, which failed on main with `shouldShowActionsMenu` true on one lineage and false on another. That is the argument for an invariance property over per-site conversion — the file had already been converted "2 → 1" and the survivor was the live one. **2. Worktree upcoming-work list empty on renamed boards.** `groupByWorktree` filtered `t.column === "todo"`. On the default board the id and the role coincide so every existing test passed; renamed, it matched nothing and a whole panel read as idle. **3. Hold-lane FIFO ordering lost on renamed boards.** `sortTasksForDisplayColumn` gated priority-then-FIFO on `column === "todo"`, degrading to the generic id-ordered sort elsewhere. Cards simply appear in the wrong order, silently. **4. The AST ratchet still failed open** — fourth time in that file, third found by review. `receiverName` understood only one-level property access and bare identifiers, so `task["column"]`, `metadataColumn(entry, "to")`, ternaries, `(task!.column)` and backtick literals were dropped. **Measured on main: `in-progress` 196 → 197, `in-review` 211 → 213** — three real guards nobody counted, including `metadataColumn(entry, "to") === "in-review"` in `reliability-metrics.ts`. Now walks wrappers, resolves calls to the callee name, and emits a `<SyntaxKind>` **sentinel** for anything unnameable: counted *and* trips the classification guard, so a human judges it instead of it vanishing. ## Per-file guard counts | file | before | after | |---|---:|---:| | `app/components/TaskContextMenu.tsx` | 1 | **0** | | `app/utils/worktreeGrouping.ts` | 1 | **0** | | `app/components/taskSorting.ts` | 1 | **0** | The other dashboard files I had converted reached 0 via U11's PRs; where our work overlapped I took theirs during the rebase, including two places where theirs was **stronger** than mine — they deleted Column's unreachable quick-create arm outright (with fixtures migrated) where I had converted it, and they verified the same `isPreExecutionHoldColumn` degraded-set asymmetry I did, independently. ## Flip precondition: the moves.ts flag is scoped, not flipped `move-target-declared-census.test.ts` answers precondition 2 with measurement. 41 engine `moveTask` calls have literal targets — `todo` 27, `in-progress` 7, `done` 6, `archived` 1 — and **all four are declared by the default lineage**, so the default board is not the exposure. `triage` appears only in a comment noting `replan-target.ts` used to hardcode it. My own grep had said `todo=29`; the AST says 27, because grep counts comments. The exposure is **custom** lineages: 20 of the 41 carry no `recoveryRehome` and would reject with unknown-column post-flip; 21 are exempt via the #1411 carve-out, which makes that carve-out load-bearing. I did not flip the flag. It is six seams, not the `789`/`837` pair every summary including mine described, and seam 2 turns on *new refusals* rather than swapping equivalent implementations — a green suite says nothing about that. #2639 pins the blast radius. ## Tests - `column-role-id-invariance.test.tsx` — hold traits fixed, vary only the column id across MERGED / LEGACY / RENAMED; every decision must agree. Drives the real consumers, so a component keeping an inline comparison fails it. Includes a unanimous-and-**false** case so it can't be satisfied by a predicate hardwired to true. **This is the test that caught defect 1 on main.** - `worktreeGrouping.test.ts` — includes two cards both in a column named `staging`, one hold and one not, asserting opposite answers. That assertion is impossible under a board-wide column-id set, which is why hold resolution is keyed per task via `getEffectiveTaskWorkflowId` (#2625 review). - `taskSorting.test.ts` — discriminates on the **tiebreak**, not priority: both branches sort by priority, so my first version passed for the wrong reason. Equal-priority cards whose `createdAt` order disagrees with their id order. - `no-hardcoded-lifecycle-columns.test.ts` — 16 detector cases: 11 shapes counted, 4 legitimate ignored, one asserting the sentinel path. Revert checks, all run: menu suppression → diff names the field; worktree → `expected [] to include 'FN-50'`; sort → `FN-2, FN-9` instead of `FN-9, FN-2`; ratchet → the 3 recovered guards disappear. ## One site that should never be converted `MissionControlPanel.tsx:46` — `{ id: "triage", match: (c) => c === "triage" || c === "signal" || c === "backlog" }` is a deliberate name-similarity heuristic for the SDLC funnel; it matches synonyms and folds unknown columns into an "other" bucket so custom columns still contribute. Converting it changes what the funnel displays. Like the `live-agent-count` fallbacks, it belongs in a documented floor — **the ratchet's target is that floor, not zero.** `DocumentsView.tsx:73` is convertible but the file has no column flags at all, so a real fix means plumbing board-workflow metadata into a view that doesn't fetch it — its own unit of work. ## Verification `pnpm lint` clean. `pnpm test:gate` green (10 / 482 / 71). `tsc -p packages/dashboard/tsconfig.app.json` and `packages/core/tsconfig.json` clean. Core ratchet + seam suites 24/24. Dashboard target suites 37/38 — the one failure is the pre-existing `"Back to In Progress"` label casing, confirmed identical on the base. --- ## Added after the initial push **5. `TaskCard` lost inline editing on renamed boards; `TaskDetailModal` kept it.** Still live on main: the modal resolved field editability from traits in U10/R8, the card used a hardcoded `{triage, todo}` set with **no trait path at all** — even though `taskColumnFlags` was already in scope. On a renamed board the title was editable in the modal and the pencil was missing from the card. Body moved unchanged into `isFieldEditableColumnRole` so the two surfaces cannot drift again. The veto traits are the substance: a column can legally carry `hold` **and** a WIP or review trait, and a plain `intake || hold` check would let an operator rewrite a description while a session executes against it. Coverage gap **measured, not assumed**: mutating `canEdit` back to the hardcoded set left `TaskCard*` at the same failure count as the unmutated run — nothing caught it. The four render cases assert the real `aria-label`; that mutation now fails with `Unable to find an accessible element ... name 'Edit task'`. **6. The ratchet's target is a documented FLOOR, not zero** — and this changes the completion bar. Zero is not reachable, and chasing it means breaking working code. Two categories are permanent, now protected as positive assertions so a future sweep cannot "finish the job" by deleting them: - `MissionControlPanel.tsx`'s `FUNNEL_STAGES` is a deliberate **name-similarity** heuristic — it matches `signal`, `backlog`, `to-do`, `ready`, `shipped` and folds unrecognised columns into an "other" bucket so a custom board still contributes counts. It is not asking whether a column has the intake trait; it buckets arbitrary column *names* for display. Asserted on the **synonym list**, because the synonyms are what prove it is name matching — if they disappear the site has changed character and the exemption stops applying. - `live-agent-count.ts`'s no-flags arm is reachable (a remote store is deliberately given an empty flag map; a card in an undeclared column has no flags at all) and deleting the literal makes such a card match **no** arm, so the queued total silently under-reports a stranded card. A count with an undocumented floor invites someone to drive it to zero. **Not done, and why:** `DocumentsView.tsx:73` is convertible but that file has no column flags anywhere, so a real fix means plumbing board-workflow metadata into a view that does not fetch it — its own unit of work, not something to smuggle into a conversion. **Re-verified after these commits:** `pnpm lint` clean, `pnpm test:gate` green (10 / 482 / 71), `tsc` clean on core and `tsconfig.app.json`, core ratchet suite 26/26, `columnRoles` 10/10, `TaskCard.test.tsx` 384/386 (the 2 are pre-existing CSS assertions). `TaskDetail*` is 130 failed / 551 passed **both with and without** this change — verified by stashing, so pre-existing and unrelated. --- ## Flag resolution: preconditions 1 and 2 are now DISCHARGED. Precondition 3 is blocked, and by evidence. **Precondition 1 — the side-effect equivalence proof — done.** `moves-flag-equivalence.test.ts` runs the same journey under both flag states against live PG and diffs the persisted row. **Result: identical** — whole-row equality across 128 fields plus an equal timing shape, over `todo → in-progress → in-review → todo → in-progress`. That test was **wrong twice** before it meant anything, and both times it was passing: 1. **It proved nothing.** `experimentalFeatures` is **global-only**, and `moves.ts` reads `getSettingsFast()`, which filters global-only keys out of the project layer. My `updateSettings` write was silently discarded, `useWorkflow` was false in *both* runs, and the "proof" compared the legacy path against itself. Found by stamping the flag-ON branch and observing the test still passed. Now written via `updateGlobalSettings`, and the helper **asserts the flag took effect** before the journey runs. 2. **The journey was forward-only**, so it never reached the reopen hook's field resets (`status`, `error`, `blockedBy`, pause clearing) — a mutation there passed. Extended with a backward move and a re-entry. Mutation-verified after both fixes: stamping seam 3, and diverging the reopen hook, each fail the comparison. **Precondition 2 — done, and its answer is a blocker.** The census says the default board is safe: all 41 literal engine move targets are declared by the default lineage. But **20 of those 41 carry no `recoveryRehome`**, so on a custom lineage that does not declare `todo` / `in-progress` / `done`, seam 2 would start rejecting them with unknown-column. That is a user-facing break on custom boards, not a theoretical one, and it is not fixed by the equivalence proof — seam 2 adds *new refusals* rather than swapping implementations. **So the flip is one step away, and the step is not mine to take alone:** those 20 call sites need to resolve their target from the task's workflow (or justify `recoveryRehome`), and they live across engine lanes in `moves.ts` caller territory — U2b/MAIN. Flipping before that trades a dormant flag for broken custom boards. What remains for precondition 3 once those land: flip both readers **atomically** (`moves.ts` + `workflow-task-create-ops.ts`, since the latter computes the preflight the former consumes), delete the flag-OFF branch with its guards, and drop the settings key. --- ## CORRECTION: seam 2 is not a blocker. My earlier claim was wrong. I stated in #2639 and above that "with the flag off there is **no** target-column validation on the move path", so flipping would introduce new refusals. **That is not what happens.** Reproduced against live PG: the identical custom-lineage move rejects with the flag **OFF** as well — ``` Error: Invalid transition: 'backlog' -> 'todo'. Valid targets: building ``` Transition validation is already in force on the flag-OFF path. So for the shape in question — an engine move to a column the task's own workflow does not declare — **the move already fails today**, and seam 2 introduces no new break for it. The 20 census sites lacking `recoveryRehome` are broken on a custom lineage *now*, not broken by the flip. I found this because the discriminator I added to prove "the flag is the cause" failed. Had I written the test to my assumption it would have passed and the false claim would have shipped — the same way the equivalence test passed while proving nothing until I tried to make it fail. **Revised precondition status:** | precondition | status | |---|---| | 1 — side-effect equivalence | **discharged** — identical rows, mutation-verified both directions | | 2 — seam-2 exposure census | **discharged, and it is not a blocker** — the rejection predates the flag | | 3 — flip both readers atomically, delete the flag-OFF branch, drop the settings key | **the remaining work** | So the flip is no longer gated on fixing 20 engine call sites. What it is still gated on is precondition 3 being done atomically across `moves.ts` and `workflow-task-create-ops.ts` (the latter computes the preflight the former consumes), which is `moves.ts` caller territory. Three cases now cover seam 2: the flag-ON rejection, the flag-OFF rejection (asserting the error *message*, so a change in which guard rejects stays visible rather than reading as agreement), and the #1411 `recoveryRehome` carve-out succeeding — pinning why that carve-out is load-bearing and must not be tidied away. --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Fusion
From rough idea to production code — automatically.
🏭 A software factory, run by a multi-agent orchestrator.
Describe what you want — a team of AI agents plans, builds, reviews, and ships it for you. Fusion is your software factory: an assembly line for code that runs across tasks, agents, missions, git, files, and worktrees, with any model, local or cloud.
runfusion.ai → · Docs · GitHub · npm · Discord
English · 简体中文 · 繁體中文 · Français · Español · 한국어
Your entire dev environment. On a single pane of glass.
Describe a task in plain language. A planning agent reads your project, understands context, and writes a full PROMPT.md plan — 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.
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. Built on the great work of dustinbyrne/kb.
Quick start
Zero install, straight from npm:
npx runfusion.ai
That launches the dashboard. Subcommands forward through: npx runfusion.ai task create "fix X", npx runfusion.ai --help, etc. (Or verbosely: npx @runfusion/fusion dashboard.)
One-line installer (macOS & Linux — auto-picks Homebrew, falls back to npm):
curl -fsSL https://runfusion.ai/install.sh | sh
fusion dashboard
Homebrew (macOS & Linux):
brew install runfusion/fusion/fusion
fusion dashboard # or: fn dashboard
Fully-qualified install auto-taps and, on Homebrew 6.0+, trusts only the Fusion formula. If you already ran brew tap runfusion/fusion and short-name install fails with “untrusted tap”, run brew trust --formula runfusion/fusion/fusion then brew install fusion.
npm global:
npm install -g @runfusion/fusion
fn dashboard # or: fusion dashboard
From a clone (for development):
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. On the
server side, Fusion now persists the dashboard/daemon token in
~/.fusion/settings.json on first authenticated run and reuses it on later
starts unless you override it (--token, FUSION_DASHBOARD_TOKEN,
FUSION_DAEMON_TOKEN) or disable auth with --no-auth. See
CLI reference → fn dashboard → Authentication
for full precedence and reset/revocation options.
First-run setup
On first launch, Fusion opens the onboarding wizard with three guided steps:
- AI Setup — Use a simplified quick-start provider list (recommended providers plus any already-connected providers), then expand Advanced provider settings only if you need additional providers or setup details. You only need one provider to get started. Deprecated Google Gemini CLI / Antigravity provider entries are intentionally hidden; Google/Gemini API key, Google Generative AI, Vertex, and Cloud Code paths remain supported.
- GitHub (Optional) — Connect GitHub for issue import and PR management
- First Task — Create your first task or import from GitHub (if no project is active, onboarding first prompts you to register/select a project directory)
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.
The flow
① Describe ② Planning ③ 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)
See every step, before the merge
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.
What makes it different
| 🧠 AI planning | Describe a task in plain language. Planning agents turn it into a PROMPT.md plan with steps, file scope, and acceptance criteria. |
| 🔁 Selectable workflows | Built-ins cover coding, quick fixes, review-heavy work, stepwise execution, plugin-gated Compound Engineering, and PR lifecycle fragments. Pick a workflow per task or author custom ones in the Workflow Editor. |
| 🛡️ Planner oversight | Per-task or per-workflow oversight level (off / observe / steer / autonomous) governs how closely a planner overseer watches and intervenes — merge/PR and destructive actions always require explicit human confirmation. See Settings Reference and Dashboard Guide. |
| 🌳 Worktree isolation | Each task runs in its own branch and worktree (fusion/{task-id}). Parallel tasks. Zero conflicts. Optional worktrunk delegation via worktrunk.enabled (see WorktreeBackend abstraction). |
| 🗄️ PostgreSQL by default | Fusion uses zero-config embedded PostgreSQL for local runtime metadata. Legacy SQLite files are one-time migration inputs only; use a shared external database for multi-project and multi-node setups. (Storage) |
| ⚡ Smart merge controls | Passing every gate? Fusion squash-merges and moves on. Opt into manual approval anywhere, inherit the live global auto-merge default, or set explicit per-task auto/manual overrides. |
| 🛰️ Multi-node mesh | Laptop, Mac mini, Linux server, cloud VM, phone — all synced. Desktop, mobile, web. |
| 🧩 Any model | Anthropic, OpenAI, Ollama, Google Generative AI, Z.ai, Kimi K3, local runtimes, and user-defined custom providers. Local and cloud coexist, with workflow model/fallback lanes configurable per project. |
| 🏢 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; engineer-role agents can opt into backlog auto-claim when you want implementation help beyond executor-only pickup. |
| 🗨️ Agent chat | Direct chat, task chat that proactively narrates step progress, failures, and review outcomes, attachments, in-chat question cards, resumable streams, and experimental multi-agent Chat Rooms where mentioned members respond directly and ambient members can join up to a cap. (Chat docs) |
| 🗺️ Missions | Hierarchical planning (Mission → Milestone → Slice → Feature → Task) with autopilot and validation contracts. |
| 🔬 Research | Bounded research runs with web search, GitHub, local docs, and LLM synthesis (plus runtime builtin WebSearch/WebFetch support in planning + synthesis flows when available). Turn findings into tasks. (Docs) |
| 🧪 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. |
See it in action
The newest surfaces in Fusion, at a glance — the live board, your agent team, mission control, visual workflows, agent chat, multi-agent rooms, and inter-agent mail.
📋 The board & your agent team — live, from a real fleet
Every task, every column, every step — live. Cards carry GitHub links, step counts, review levels, and promote/move/archive actions. Switch to the Graph view to see task dependencies as an interactive node graph:
Board — kanban columns |
 Graph — dependency map |
Here is the same fleet re-skinned into the Ember theme (dark graphite with an orange accent), alongside the Agents roster:
 Board — Ember |
 Agents — Tokyo Night |
Import a team and every agent shows up here — role, reports-to chain, heartbeat, and token share. Each agent card's heartbeat dropdown shows Disabled when scheduling is persisted off; choose Disabled to pause heartbeats while retaining its cadence, or select an interval to re-enable them. The Agents roster in Ember:
🛰️ Command Center — mission control for your agent fleet
One screen for everything your agents are doing. Tune live scheduler capacity, watch token spend by model in real time, and prove the value with hard numbers. The Overview tab opens with live gauges and charts:
Every tab is a different lens on the same live fleet:
 Tokens — spend by model, cached vs. input vs. output, over time. |
 Productivity — outcomes, duration percentiles, language mix. |
 Team — agent org chart and token share per agent. |
 Activity — task throughput and event timelines. |
 Signals — anomaly detection and fleet health. |
More — Tools · Ecosystem · GitHub · System · Reliability. |
Tokens · Tools · Activity · Productivity · Team · Ecosystem · GitHub · Signals · System · Reliability · Mission Control — every tab is a different lens on the same live fleet.
The same fleet, your way — Command Center (and the whole dashboard) re-skins live across 70+ color themes, including Cobalt, Clay, and Moss. Here it is in Shadcn Light, Shadcn Dark Gray, and Ember:
 Shadcn Light |
 Shadcn Dark Gray |
 Ember |
A dozen light themes & a dozen dark themes (click to expand)
🔁 Selectable workflows, authored visually
A task's journey from idea to merge is a workflow — and it's yours to choose and shape. Pick a built-in (Coding, Quick fix, Review-heavy, Stepwise, PR lifecycle, Compound engineering, and more), inspect its graph, then duplicate and customize columns, gates, model lanes, and review policy in the visual Workflow Editor. No engine fork required.
Here's the Stepwise coding graph — plan, execute, and review every step before the next — explored node-by-node in Shadcn Light, Dark Gray, and Ember:
 Shadcn Light |
 Shadcn Dark Gray |
 Ember |
🗨️ Agent chat — talk to your agents, mid-flight
Direct chat and per-task chat with any agent, on any model. Ask why a task failed, steer an approach, drop attachments, answer in-chat question cards, and resume streams where you left off — full markdown and code rendering throughout.
 Shadcn Light |
 Shadcn Dark Gray |
👥 Multi-agent chat rooms
Put multiple agents in a room and let them coordinate. Mention a member and it responds directly; ambient members can join the conversation up to a cap. Here the CEO, Product Manager, and CTO agents align on task ownership in #leads — no human in the loop. (Chat docs)
 Shadcn Light |
 Shadcn Dark Gray |
 Ember |
📬 Agent mail — an inbox between your agents
A built-in mailbox for delegation, clarification, and hand-offs. Agents file triage summaries, request approvals, and coordinate work across the fleet — with Inbox, Outbox, Agents, and Approvals views, so you can audit every exchange.
 Shadcn Light |
 Shadcn Dark Gray |
 Ember |
📱 Fusion is an AI factory in your pocket
The full board, Command Center, missions, agents, and chat travel with you — native iOS and Android apps (Capacitor) plus an installable PWA. Start a run on your laptop, steer it from your phone.
 |
 |
 |
 |
 |
 |
See MOBILE.md for the Capacitor + PWA workflow.
How it works
graph TD
H((You)) -->|rough idea| T["Planning<br/><i>auto-planning</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 --> R1{Review}
R1 -->|revise| P
R1 -->|approve| E[Execute]
E --> R2{Review}
R2 -->|revise| E
R2 -->|next step| NS
R2 -->|rethink| P
end
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
style TD fill:#0d2044,stroke:#58a6ff,color:#58a6ff
style IP fill:#1a0d2e,stroke:#bc8cff,color:#bc8cff
style P fill:#1a0d2e,stroke:#bc8cff,color:#e6edf3
style R1 fill:#1a0d2e,stroke:#bc8cff,color:#e6edf3
style E fill:#1a0d2e,stroke:#bc8cff,color:#e6edf3
style R2 fill:#1a0d2e,stroke:#bc8cff,color:#e6edf3
style NS fill:#1a0d2e,stroke:#bc8cff,color:#bc8cff
style IR fill:#0d2d16,stroke:#3fb950,color:#3fb950
style D fill:#1a1a1a,stroke:#8b949e,color:#8b949e
Tasks with dependencies are processed sequentially. Independent tasks run in parallel. Optionally require manual approval before tasks move from Planning to Todo (requirePlanApproval setting).
Workflow overview
Fusion workflows define how a task moves from idea to delivery. The default coding path is still the familiar Plan/Triage → Execute → Workflow steps → Review → Merge loop, but the policy now lives in a selectable workflow rather than being only hard-coded engine behavior.
- Select per task: choose a workflow from the dashboard task/board workflow controls, or assign one through
fn_workflow_select/workflow_idwhen creating tasks. - Built-in catalog: Coding (
builtin:coding), Quick fix (builtin:quick-fix), Review-heavy (builtin:review-heavy), Compound engineering (builtin:compound-engineering, plugin-gated), Stepwise coding (builtin:stepwise-coding), and the PR lifecycle (builtin:pr-workflow, a reusable PR graph fragment). - Customize safely: inspect built-ins, duplicate them, or author custom workflows in the visual Workflow Editor. Workflow-specific settings cover model lanes, review/approval policy, step execution knobs, task fields, and columns.
Read Workflow Steps for runtime semantics, built-in workflow behavior, and workflow-step templates; read Workflow Editor for the dashboard authoring guide.
Planner oversight
Each workflow (and optionally each task) can set a planner oversight level — off, observe, steer, or autonomous (default) — controlling how closely a planner overseer watches and intervenes in that task's execution. Even at autonomous, merge/PR progression and any destructive or external-service side effect always require an explicit, recorded human confirmation before they run. Notification verbosity is controlled separately. Set the default in the Workflow Editor → Values tab, or override per task from the New Task dialog / Task Detail edit form. Read Settings Reference for the full setting semantics and Dashboard Guide for the UI controls.
Multi-node. One board. Every platform.
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. The same Fusion ships as:
- 🖥️ Desktop app — Electron for macOS (Intel + Apple Silicon), Windows 10/11, and Linux
- 📱 Mobile app — Capacitor for iOS/iPadOS and Android (MOBILE.md)
- 🌐 Web dashboard — any modern browser, served from the
fn dashboarddaemon - 🔌 CLI —
fnbinary + extension for terminal-first workflows
Start the daemon on any node, connect your other devices, and the board follows you everywhere.
Run an agent company
Import a team. Run it autonomously for weeks. 440+ agents across 16 companies, wired for missions, mailboxes, and inter-agent delegation.
npx companies.sh add paperclipai/companies/gstack
Compatible with the tools you already use.
Fusion integrates with the tools you love. Hermes, Paperclip, and OpenClaw all ship as first-class plugins — route any workspace to whichever runtime fits the task. And any Paperclip agent-company imports with a single command.
Hermes experimental
Nous Research
The open-source autonomous agent from Nous Research. Install the Hermes plugin and run agents through Hermes for long-running, context-growing work — route any Fusion workspace to it.
OpenClaw experimental
OpenClaw runtime support is available as an experimental plugin (fusion-plugin-openclaw-runtime) for runtime discovery/configuration parity. Configure agents with runtimeConfig.runtimeHint: "openclaw" after installing the plugin.
Paperclip experimental
paperclip.ing
The human control plane for AI labor. Install the Paperclip plugin to run agents through Paperclip inside Fusion.
Fusion also natively supports the companies.sh agent-company standard: import a prebuilt team — 440+ agents across 16 companies — and let them coordinate over Fusion's mailbox, missions, and workflow gates for weeks of autonomous work. Same company format, same agents, same skills as Paperclip.
npx companies.sh add paperclipai/companies/gstack
Hermes, Paperclip, and OpenClaw are experimental runtime plugins — APIs and wire formats may shift between minor releases.
Documentation
| Guide | What it covers |
|---|---|
| Getting Started | Installation, onboarding, first task, and workflow-selection basics |
| Dashboard Guide | Board/list views, chat, workflow editor, git manager, settings, and UI tools |
| Task Management | Task lifecycle, prompt specs, comments, archiving, and GitHub integration |
| CLI Reference | Full fn command and daemon reference |
| Settings Reference | Global/project settings, model hierarchy, workflow settings, and custom providers |
| Workflow Steps | Workflow runtime, built-in workflows, gates, templates, and phases |
| Workflow Editor | Visual authoring, importing/exporting, custom fields/columns/settings, and mobile editor |
| Research | Bounded research runs, findings, exports, and task integration |
| Agents | Agent management, spawning, heartbeat, and mailbox workflows |
| Missions | Mission hierarchy, planning, autopilot, and validation contracts |
| Plugin Management | Discovering, installing, enabling, configuring, and troubleshooting plugins |
| Plugin Authoring | Building plugins with lifecycle hooks, routes, tools, runtimes, and dashboard surfaces |
| Remote Access | Tokenized remote dashboard access, Tailscale/Cloudflare setup, and troubleshooting |
| Multi-Project | Central registry, isolation modes, and migration paths |
| Storage | PostgreSQL runtime storage, migration compatibility, and file-backed payloads |
| Docker | Container deployment |
Core features
- AI Planning — Planning agent generates detailed
PROMPT.mdwith steps, file scope, and acceptance criteria - Step-by-step Execution — Plan → Review → Execute → Review cycle for each task step, with graph-mode workflows able to model per-step parse/execute/review/rework explicitly
- Git Worktree Isolation — Each task runs in its own worktree (
fusion/{task-id}branch) - Selectable workflows — Pick Coding, Quick fix, Review-heavy, Stepwise coding, plugin-gated Compound Engineering, custom workflows, or PR lifecycle fragments where appropriate (overview; Workflow Steps)
- Visual Workflow Editor — Inspect read-only built-ins, duplicate/customize workflows, and edit graph nodes, columns, task fields, typed settings, and per-project values (Workflow Editor)
- Workflow Steps — Configurable quality gates (pre-merge: blocks merge; post-merge: informational), plus workflow-declared optional steps such as opt-in Browser Verification
- Workflow-native policy — Fast-mode planning (
leanPlanning/autoApproveSpec), typed triage thresholds, review/approval, step execution, and model/fallback lanes are workflow settings, not hard-coded engine constants (Settings Reference; workflow settings) - Planner oversight — Workflow-native
plannerOversightLevel(off/observe/steer/autonomous), with an optional per-task override and a separate notification-verbosity setting; merge/PR progression and destructive actions always require explicit human confirmation, even atautonomous(overview; Settings Reference) - GitHub + PR lifecycle — Import issues with optional translation and screenshot attachments, skip previously imported issues even after edits or repository casing changes, create PRs, display real-time PR/issue badges, and use workflow-mode PR lifecycle graph fragments where enabled
- Dashboard — Real-time kanban/list/graph views, a project Overview with local codebase token estimate and on-disk size, agent management, terminal, git manager, mission planner, chat, workflow editor, custom provider setup, and one-click update action
- Missions — Hierarchical planning (Mission → Milestone → Slice → Feature → Task) with autopilot, validation contracts, fix-feature retries, mission-goal linking, and blocked-handoff semantics
- Multi-Project — Manage multiple projects from a single installation with project isolation
- Custom Providers — Add OpenAI-compatible, OpenAI Responses, Anthropic-compatible, or Google Generative AI providers; saved models appear in Project Models and workflow model dropdowns (Dashboard Guide; settings shape)
- Smart merge controls — Global auto-merge stays live for default tasks, while explicit per-task overrides can force auto/manual behavior (Settings Reference)
- Inter-Agent Messaging — Built-in messaging for coordination between agents and users; engineer-role agents can opt into backlog auto-claim for implementation tasks (Settings Reference)
- Agent Chat + Chat Rooms — Direct/task chat supports attachments, resumable streams, question response cards, and renameable conversations; experimental rooms route mentioned members as direct responders with optional ambient replies (Dashboard Guide → Chat View)
Provider authentication
Fusion supports OAuth-based authentication for AI providers configured via Settings → Authentication. For most OAuth providers, when the dashboard is accessed via a non-localhost host (remote node, LAN host/IP, or reverse proxy), provider login URLs are rewritten to route OAuth callbacks through a bridge endpoint (/api/auth/oauth-callback) so redirects reach the active browser session.
- Anthropic (Claude) — Uses a pasted authorization-code flow in Settings/onboarding: sign in, then paste the final redirect URL (or code) back into Fusion to complete login
- OpenAI Codex — Uses the same pasted authorization-code flow with secure state validation
- Factory AI — via Droid CLI (optional) — requires local Droid CLI install +
droid auth login; detection follows the effective runtime binary path (defaultdroid, or plugindroidBinaryPathwhen configured), then enable in Settings → Authentication and restart Fusion - llama.cpp — via HTTP server (optional) — configure your llama.cpp server URL (default
http://127.0.0.1:8080) and optional API key, then enable in Settings → Authentication - Other providers — Authenticate via API key entry in Settings (including Google/Gemini API key, Google Generative AI, Vertex, and Cloud Code aliases)
- Custom providers — Add user-defined OpenAI-compatible, OpenAI Responses, Anthropic-compatible, or Google Generative AI endpoints from Settings → Authentication → Custom Providers; saved model IDs become selectable in project and workflow model lanes (Dashboard Guide)
Model system
Fusion uses a dual-scope model hierarchy with independent lanes. Global settings define baseline defaults; project settings provide per-project overrides.
| Lane | Purpose | Global Baseline Keys | Project Override Keys |
|---|---|---|---|
| Executor | Task execution agent | executionGlobalProvider + executionGlobalModelId |
executionProvider + executionModelId |
| Planning | Task planning agent | planningGlobalProvider + planningGlobalModelId |
planningProvider + planningModelId |
| Validator | Plan/code reviewer | validatorGlobalProvider + validatorGlobalModelId |
validatorProvider + validatorModelId |
| Merger | Merge conflict / clean-room merge agent | mergerGlobalProvider + mergerGlobalModelId |
mergerProvider + mergerModelId |
| Title Summarization | Auto-title generation | titleSummarizerGlobalProvider + titleSummarizerGlobalModelId |
titleSummarizerProvider + titleSummarizerModelId |
| Workflow Step Refinement | AI prompt refinement | (uses defaultProvider/defaultModelId) |
(uses modelProvider/modelId on WorkflowStep) |
Workflow lanes: The default workflow exposes Plan/Triage, Executor, Reviewer, and fallback model lanes in Settings → Project Models, and advanced workflow settings can declare additional typed model/policy values (Settings Reference).
Per-Task Overrides: Quick Add and Inline Create let tasks override the planning, executor, validator, and merger lanes; planning, validator, and merger selections also support task-specific thinking levels. (modelProvider/modelId, validatorModelProvider/validatorModelId, planningModelProvider/planningModelId, and merger model/thinking overrides.)
Precedence: Per-task → Project override → Global lane → defaultProvider/defaultModelId → Automatic resolution.
For full settings documentation, see Settings Reference.
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
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.
To explicitly target a scope:
- In the dashboard Scheduled Tasks modal, use the Global / Project toggle.
- Via the API, pass
?scope=globalor?scope=project&projectId=<id>on automation/routine endpoints.
Scope resolution rules:
scope=globalalways resolves to the global automation/routine lane, independent of the active project.scope=projectrequires aprojectId. If omitted, it falls back to"default".- CRUD, run, toggle, and webhook operations are strictly scope-isolated: a global schedule cannot be mutated from a project-scoped request, and vice versa.
Operational guidance for multi-project setups:
- Prefer global schedules for shared infrastructure (e.g., nightly backups, memory insight extraction).
- Prefer project schedules for per-repository automation (e.g., per-project test runners, deployment hooks).
- Global and project lanes are polled independently by the engine, so due runs in one lane do not block the other.
Automations
| Endpoint | Method | Description |
|---|---|---|
/api/automations |
GET | List all automations (filtered by scope if specified) |
/api/automations |
POST | Create automation (scope defaults to project) |
/api/automations/:id |
GET | Get automation by ID |
/api/automations/:id |
PATCH | Update automation |
/api/automations/:id |
DELETE | Delete automation |
/api/automations/:id/run |
POST | Trigger manual run |
/api/automations/:id/toggle |
POST | Toggle enabled/disabled |
/api/automations/:id/steps/reorder |
POST | Reorder automation steps |
Routines
Routines are AI agent tasks triggered by cron schedules, webhooks, or manual execution. Routines share the same global/project scope model as automations.
| Endpoint | Method | Description |
|---|---|---|
/api/routines |
GET | List all routines (filtered by scope if specified) |
/api/routines |
POST | Create routine (scope defaults to project) |
/api/routines/:id |
GET | Get routine by ID |
/api/routines/:id |
PATCH | Update routine |
/api/routines/:id |
DELETE | Delete routine |
/api/routines/:id/run |
POST | Manual trigger |
/api/routines/:id/trigger |
POST | Canonical manual trigger |
/api/routines/:id/runs |
GET | Get execution history |
/api/routines/:id/webhook |
POST | Webhook trigger (signature verification supported) |
CLI quick examples
fn task create "Fix the login bug" # Quick entry → planning
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 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 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
Packages
| Package | Description |
|---|---|
@fusion/core |
Domain model — tasks, board columns, PostgreSQL stores |
@fusion/dashboard |
Web UI — Express server + kanban board with SSE |
@fusion/engine |
AI engine — planning, execution, scheduling, workflow steps |
@runfusion/fusion |
CLI + extension — published to npm |
Development
pnpm install # Install dependencies
pnpm local # Start local dashboard/API + AI engine on a non-4040 port
pnpm local --no-engine # Start local dashboard/API only
pnpm build # Build default workspace packages (excludes desktop/mobile)
pnpm build:all # Build all packages (including desktop/mobile)
pnpm dev dashboard # Run dashboard + AI engine
pnpm dev:ui # Dashboard only (no AI engine)
pnpm lint # Lint all packages
pnpm typecheck # Type-check all packages
pnpm test # Run all tests
Build a standalone executable
Build a single self-contained fn binary using Bun:
pnpm build:exe # Build for current platform
pnpm build:exe:all # Cross-compile for all platforms
License
MIT — open source, no vendor lock-in. See LICENSE.