fusion/docs/getting-started.md

Getting Started

← Docs index

This guide gets Fusion running, explains first-run setup, and walks through your first task from creation to completion.

Prerequisites

Fusion uses the pi agent runtime for AI sessions.

1. Install pi:

npm i -g @mariozechner/pi-coding-agent

2. Authenticate pi (for example with /login) or configure provider API keys.

pi

Install Fusion

Install the published CLI package globally:

npm i -g @gsxdsm/fusion

Then verify install:

fn --help

First Run and Onboarding

Start the dashboard:

fn dashboard

On first launch, Fusion automatically opens the onboarding wizard. It guides you through three steps:

1. AI Setup — Connect an AI provider and choose a default model. Authenticate via OAuth login (for supported providers like OpenAI Codex) or enter an API key directly.

2. GitHub (Optional) — Connect GitHub to import issues and manage pull requests. This step is optional — you can continue without GitHub.

3. First Task — Get started by creating your first task or importing from GitHub.

The onboarding wizard is dismissible and non-blocking. If you skip setup, you can complete it later — and you can always update your AI provider authentication anytime via Settings → Authentication in the dashboard:

• Click Skip for now to dismiss the wizard — the dashboard remains fully usable
• After dismissing, a Continue Setup banner appears at the top of the dashboard, letting you resume from where you left off
• Re-open onboarding anytime from Settings → Authentication → Reopen onboarding guide

When reopening onboarding, the wizard pre-populates your previously saved AI provider and default model, so you can quickly review or update your setup.

Onboarding completion is tracked by modelOnboardingComplete in global settings.

Start the Dashboard

Common startup options:

fn dashboard                       # default port 4040
fn dashboard --port 5050           # custom port
fn dashboard -p 5050               # short form for --port
fn dashboard --interactive         # choose port interactively
fn dashboard --paused              # start with automation paused
fn dashboard --dev                 # run UI only (no engine)

Open: http://localhost:4040 (or your custom port).

Other launch modes:

fn serve --port 5050 --host 0.0.0.0   # headless node (API + engine, no web UI)
fn daemon --port 5050                  # daemon mode with token auth support
fn desktop                             # launch Electron desktop app

Create Your First Task

You can create tasks from the board or CLI.

Option A: Quick Entry (Board)

1. Type a short request in the quick entry input.
2. Press Enter.
3. Task appears in Triage and the triage agent generates PROMPT.md.

Option B: Plan Mode (Board)

Use the 💡 button to open AI planning mode:

• Fusion asks clarifying questions
• Produces a structured summary
• Lets you create one task or break into multiple dependency-linked tasks

Option C: Subtask Breakdown (Board)

Use the 🌳 button to:

• Generate 2–5 subtasks
• Reorder by drag-and-drop
• Add dependency links before creating tasks

Option D: Expanded Controls (Board)

Expand the quick entry panel (▼) to access additional controls:

• Refine (✨) — Improve the description with AI
• Deps (🔗) — Link existing tasks as dependencies
• Attach — Add image attachments
• Models (🧠) — Set per-task model overrides
• Agent — Assign an agent to the task
• Save — Create the task manually

Option E: CLI

fn task create "Fix flaky login test"
fn task plan "Implement role-based access control"

Understand the Task Lifecycle

Fusion uses six columns:

1. Triage — raw idea; AI writes spec
2. Todo — specified and queued
3. In Progress — executor implements in a dedicated worktree
4. In Review — implementation complete, awaiting merge/finalization
5. Done — merged and complete
6. Archived — retained for history, optionally cleaned up from filesystem

Daily CLI Commands

fn task list
fn task show FN-001
fn task logs FN-001 --follow --limit 50
fn task steer FN-001 "Prefer existing utility functions"
fn task pause FN-001
fn task unpause FN-001

Dashboard Orientation (Annotated)

Suggested way to read the screen:

• Top bar: global actions (settings, activity, mission/agent tools)
• Columns: task lifecycle stages
• Task cards: status, metadata, PR/issue badges
• Quick entry: fastest way to create a new task

Next: Architecture for internals, or Task Management for deeper task workflows.