Fusion Documentation
Fusion is an AI-orchestrated task board that turns ideas into reviewed, merged code using a structured workflow: planning → todo → in-progress → in-review → done.
Quick Start
Start the local dashboard with pnpm dev dashboard, then create your first task from the board or CLI.
For a full walkthrough (installation, onboarding, first task, and daily workflow basics):
Documentation Index
Getting Started
| Guide | Description |
|---|---|
| Getting Started | Installation, first-run, first task, and daily workflow basics |
| Dashboard Guide | Board/list views, terminal, git manager, files, planning, and UI tools |
| CLI Reference | Complete fn command reference with subcommands, flags, and examples |
| Remote Access | Operator runbook for Tailscale/Cloudflare setup, tokenized login links, security caveats, and troubleshooting |
| Native Shell Connection Guide | Canonical mobile/desktop shell onboarding, profile management, QR/manual setup, and remote handoff behavior |
Task & Project Management
| Guide | Description |
|---|---|
| Task Management | Task creation modes, lifecycle, prompt specs, comments, archiving, and GitHub integration |
| Todo View | Canonical guide for the experimental Todo View, including enablement, usage, API routes, and storage |
| Missions | Mission hierarchy, planning flow, activation, progress tracking, and autopilot behavior |
| Research | Research runs, provider setup, dashboard/CLI usage, findings, exports, and task integration |
| Research View UX Spec | Canonical layout and capability-state messaging spec for the Research dashboard view (FN-4138, informs FN-4134/FN-4135) |
| Workflow Steps | Reusable quality gates, templates, pre/post-merge phases, and workflow execution results |
| Task Evaluations | Eval scoring contract, evidence persistence, score categories, and evaluation pipeline |
| Multi-Project | Central registry architecture, project management, isolation modes, and migration paths |
Configuration & Agents
| Guide | Description |
|---|---|
| Settings Reference | Global and project settings, defaults, API endpoints, and model selection hierarchy |
| Agents | Agent management, presets, prompts, heartbeat behavior, spawning, and mailbox workflows |
Architecture & Development
| Guide | Description |
|---|---|
| Architecture | System architecture, package layout, storage model, and engine execution flow |
| Dashboard Real-Time | Canonical event-stream architecture contract (shared /api/events bus + dedicated stream boundaries), with project/node scoping, reconnect/cleanup behavior, and realtime pitfalls |
| Storage | Storage architecture, migration, archive system, and SQLite schema |
| DAG Architecture Deliverables | Milestone A DAG architecture documents plus Milestone B prototype scaffold docs (schema migration plan, DagCoordinator design, implementation checklist) |
| Dev Server Module Audit | Analysis of parallel dashboard dev-server module families, production wiring, and consolidation guidance |
| Beads and Dolt Evaluation for Fusion Node Sync | Evaluation of Beads and Dolt for node sync, with a recommendation for Fusion-native sync design |
| Shared Mesh Replication Protocol | Canonical multi-leader replication/write-coordination contract (versioning, quorum, leases/fencing, queue/replay, reconciliation, and degraded-read semantics) |
| Multi-Project Sequencing and Dependency Analysis | Sequencing guidance for FN-3448/FN-3449/FN-3503/FN-3182, including identity boundaries and recommended board dependency edges |
| Contributing | Local development setup, testing, release flow, and contributor conventions |
| Docker | Container builds, deployment, and persistence configuration |
| Code Signing | macOS and Windows code signing configuration for release binaries |
| Sandbox Backends | Pluggable sandbox backends for executor command isolation (bubblewrap, spawn-based) |
| Mobile | Capacitor/PWA mobile development setup and workflow |
Plugins
| Guide | Description |
|---|---|
| Plugin Management | End-user guide for discovering, installing, enabling, configuring, updating, uninstalling, and troubleshooting Fusion plugins |
| Plugin Authoring | Developer guide for building Fusion plugins (manifest, SDK hooks, routes, UI/runtime contributions) |
| Even Realities Glasses Plugin | Task-focused Even Realities glasses bridge with quick capture, polling notifications, and agent actions |
| Reports Plugin | Reports plugin rendering, export, standalone HTML generation, and section configuration |
| Even Realities Plugin API | Even Realities plugin API endpoint reference and test coverage matrix |
| Memory Plugin Contract | Pluggable memory backend architecture, interface contract, and migration strategy |
Audit Reports
| Report | Description |
|---|---|
| UX Audit Report | Comprehensive UX audit with prioritized recommendations for dashboard improvements |
| Codebase Improvement Audit | Evidence-based technical debt and reliability gap audit with prioritized recommendations |
| Gap Analysis | System completeness analysis comparing Fusion to Paperclip feature set |
| Agent Sandbox Research | Research on agent isolation, capability enforcement, and sandboxing approaches |
| Even Realities Integration Research (FN-3737) | Research summary and recommended integration topology for Even Realities glasses + Fusion |
| Agent Gap Analysis | Gap analysis for agent Paperclip integration |
| pi-autoresearch Analysis for Fusion Port | Upstream architecture/license analysis and Fusion integration mapping for autoresearch capabilities |
| pi-autoresearch Audit vs Fusion Research | Audit comparing Fusion's research subsystem against upstream pi-autoresearch capabilities and parity gaps (FN-4136) |
| Research Hardening Preflight Baseline | Verified research subsystem baseline, lifecycle contracts, and hardening pressure points |
| Test Audit Report | Test coverage and effectiveness audit with recommendations |
| Skipped Test Inventory | Current intentional test-skip inventory and reconciliation status for older skip follow-ups |
| Dev Server Module Boundary Audit | Boundary/ownership audit for parallel dev-server-* vs devserver-* dashboard modules and FN-2212 prioritization guidance |
| spawn_agent Approval Evaluation (FN-3973) | Decision to keep fn_spawn_agent under generic action-gate governance rather than durable agent provisioning policy |
| Task Lineage Reconciliation Notes | Historical task-ID reuse patterns, confidence semantics for commit attribution, and reconciliation methodology (FN-3953, FN-3998) |
| Dashboard Load Performance | SQLite index analysis and optimization for dashboard boot path queries |
| CLI Printing Press Plugin Design | Architecture design for the CLI printing press bundled plugin (FN-3762) |
| CLI Printing Press Research | Upstream cli-printing-press analysis and Fusion integration mapping (FN-3761) |
| Research vs Experiment Session Naming Decision | Naming decision record: hybrid approach retaining research_* for cited-search/synthesis and adding experiment_session_* for upstream parity (FN-4223) |
| Experiment Executor Design | Experiment executor architecture: lifecycle, run state machine, and worktree isolation model |
| Experiment Finalize Flow | Experiment finalize contract: branch grouping, dry-run planning, and session completion semantics |
| Experiment Session Model | Experiment session data model: state transitions, iteration tracking, and persisted run state |
| Experiment Session MVP Spec | MVP specification for the experiment session feature: scope, invariants, and delivery milestones |
| Sandbox Options Research (FN-4635) | Pluggable sandbox options research: threat model, backend evaluation, and spawn-based isolation design |
External Resources
- GitHub repository: https://github.com/Runfusion/Fusion
- npm package: https://www.npmjs.com/package/@runfusion/fusion
- pi agent framework: https://github.com/badlogic/pi-mono
Suggested Reading Paths
- New user: Getting Started → Dashboard Guide → Task Management
- Power user / automation owner: Settings Reference → Workflow Steps → Agents
- Maintainer / contributor: Architecture → Multi-Project → Contributing