fusion/README.md

Fusion

AI-orchestrated task board — specify, execute, and deliver tasks automatically.

Like Trello, but your tasks get specified, executed, and delivered by AI — powered by pi.

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.

Quick Start

1. Install:

   npm i -g @gsxdsm/fusion
   

2. Initialize (or just start the dashboard):

   fn dashboard
   

3. Open http://localhost:4040 — create tasks from the board or the CLI.

First-run setup: On first launch, Fusion opens the Model Onboarding wizard. It walks you through provider authentication (OAuth login or API key entry) and default model selection before automation starts. Completion is tracked via the global modelOnboardingComplete setting. You can re-trigger onboarding later by clearing this flag in Settings, or configure providers/models manually from the Settings modal.

Prerequisites

The AI engine uses pi under the hood:

1. npm i -g @mariozechner/pi-coding-agent
2. Run pi and use /login, or set ANTHROPIC_API_KEY

Fusion reuses your existing pi authentication.

Mobile

For Capacitor + PWA workflow, see MOBILE.md.

Docker

Quick start:

docker build -t fusion . && docker run -p 4040:4040 -v $(pwd):/project -e ANTHROPIC_API_KEY=... fusion

For full Docker usage (env vars, persistence volumes, and runtime options), see docs/docker.md.

Workflow

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>"]

    subgraph IP["In Progress"]
        direction TD
        NS([Begin step]) --> P[Plan]
        P[Plan] --> 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\n<i>ready to merge,\nor auto-complete</i>"]
    IR -->|direct squash merge\nor 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:#e6edf3
    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.

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

Task Creation

Create tasks from the CLI, the dashboard, or import from GitHub:

fn task create "Fix the login bug"                     # Quick entry → triage
fn task create "Bug" --attach screenshot.png --depends FN-001
fn task plan "Build a user authentication system"      # AI-guided planning
fn task import owner/repo --labels bug --limit 10      # Import GitHub issues

Dashboard creation options:

• Quick Entry — Type a description, press Enter
• Plan (💡) — AI interviews you to refine requirements before creating the task; summary view supports Break into Tasks for multi-task generation with dependencies
• Subtask (🌳) — AI suggests 2–5 subtasks with drag-and-drop reordering and dependency linking
• Actions (⋯) — Access advanced controls: dependencies, model overrides (executor/validator/planning), and manual save
• AI Title Summarization — When autoSummarizeTitles is enabled, tasks without titles get concise AI-generated names (≤60 characters)

AI Execution

Each task is implemented by an AI agent with a full Plan → Review → Execute → Review cycle:

1. Automatic spec writing — The triage agent generates a detailed PROMPT.md with steps, file scope, and acceptance criteria
2. Step-by-step execution — For each step: plan, AI code review, implement, AI code review
3. Session-per-step mode — Enable runStepsInNewSessions to isolate each step in a fresh agent session with better retry behavior
4. Parallel step execution — Configure maxParallelSteps (1–4) to run non-conflicting steps concurrently in isolated worktrees
5. Git worktree isolation — Each task runs in its own worktree (fusion/{task-id} branch)
6. Workflow steps — Configurable quality gates (pre-merge: blocks merge; post-merge: informational)

Step status is tracked in real time in the dashboard so you can see pending/in-progress/done progress as the executor advances.

fn task show FN-001                    # View task details, steps, log
fn task logs FN-001 --follow --limit 50  # Stream agent execution logs
fn task steer FN-001 "Use TypeScript"  # Guide the AI worker mid-execution

Dashboard

Real-time kanban board at localhost:4040:

• Board view — Drag-and-drop cards between columns, real-time search, column visibility toggle
• List view — Group by column or size, inline title editing, duplicate tasks
• Agents view — Agent list + detail panels with runtime config, heartbeat controls, metrics, and run history
• Mailbox — Inter-agent/user messaging UI for inbox/outbox and direct coordination
• Interactive terminal — Full PTY-based terminal with xterm.js, multiple tabs, mobile-aware with virtual keyboard handling that re-fits the terminal view above the on-screen keyboard on real devices (Chrome Android and iOS Safari)
• Git manager — View commits/diffs, manage branches, worktree associations, push/pull, inline edit controls for remote name and URL
• Mission manager — Hierarchical mission/milestone/slice/feature planning with progress tracking and autopilot controls
• Activity log — Task lifecycle events, settings changes, filter by type, auto-refresh
• Files browser — Browse project root or task worktrees, edit files with syntax highlighting
• Theme system — Dark/Light/System modes, 17 color themes (Ocean, Forest, Nord, Dracula, and more)
• Usage dialog — Real-time AI provider subscription usage with progress bars and reset timers
• Spec editor — Edit PROMPT.md directly, request AI revision, or rebuild/regenerate specs
• Planning Mode (multi-task) — After AI planning, choose Create Task or Break into Tasks to generate dependency-linked subtasks
• Model onboarding wizard — Guided provider/model setup from the dashboard, re-openable from Settings

GitHub Integration

fn task import owner/repo                  # Import all open issues
fn task import owner/repo --interactive    # Interactive issue selection
fn task pr-create FN-001 --title "Fix" --base main

• Real-time PR/issue badges — Live status updates via WebSocket
• PR creation — Create PRs from the CLI or dashboard, linked to tasks automatically
• PR comment monitoring — Adaptive polling detects actionable review feedback, adds steering comments
• Auto-completion modes — Direct squash merge (default) or PR-first with auto-merge when checks pass
• Follow-up tasks — When a PR is closed/merged with unaddressed feedback, a follow-up task is created in Triage

Merge & Review

When a task reaches In Review, Fusion handles merge with rich metadata:

• Merge commit SHA, files changed, insertions/deletions, timestamps
• Smart conflict resolution: lock files ("ours"), generated files ("theirs"), whitespace conflicts
• 3-attempt retry logic with escalating strategies (AI resolve → auto-resolve patterns → git merge -X theirs)
• Changes tab — View file-level diffs from the merge commit, even after worktree cleanup. Done tasks without a recorded commit SHA show a safe summary fallback instead of inflated repository-wide diffs.

Multi-Project Support

Fusion supports managing multiple projects from a single installation. Register projects, switch between them with a global --project flag, and monitor all activity from a unified dashboard.

Project Management

fn project add my-app /path/to/app       # Register a project
fn project list                           # List all projects
fn project show my-app                    # Show project details and health
fn project set-default my-app             # Set default project
fn project detect                         # Detect project from current directory
fn project remove my-app [--force]        # Unregister a project

The --project Flag

All task commands accept --project (or -P) to target a specific project:

fn task create "Fix login bug" --project my-app
fn task list --project my-app
fn task show FN-001 --project my-app
fn settings set maxConcurrent 4 --project my-app
fn git status --project my-app
fn backup --create --project my-app

Project Resolution

When you run a command without --project, Fusion resolves the project in this order:

1. Explicit --project flag
2. Default project (set via fn project set-default)
3. CWD auto-detection (walks up looking for .fusion/fusion.db)

Architecture

• Central database at ~/.pi/fusion/fusion-central.db — project registry, unified activity feed, global concurrency
• Per-project databases at .fusion/fusion.db — SQLite with WAL mode for concurrent access
• Global concurrency management — System-wide agent slot limits across projects
• Isolation modes — in-process (default, low overhead) or child-process (strong isolation with crash containment)

Auto-migration is seamless: existing single-project users are automatically migrated on first run. Rollback is safe — delete the central database and per-project data remains intact.

Task Management

Commands

Dashboard:

fn dashboard                              # Start the web UI (default port 4040)
fn dashboard --interactive                # Start with interactive port selection
fn dashboard --paused                     # Start with automation paused
fn dashboard --dev                        # Start web UI only (no AI engine)
fn desktop                                # Launch Electron desktop app with embedded dashboard server
fn desktop --dev                          # Launch desktop app against Vite dev renderer (hot-reload)
fn desktop --paused                       # Launch desktop app with automation paused

Task Operations:

fn task create "Fix the login bug"         # Create a new task (goes to triage)
fn task plan "Build auth system"          # Create task via AI-guided planning
fn task list                              # List all tasks
fn task show FN-001                       # Show task details, steps, log
fn task logs FN-001 [--follow] [--limit 50] [--type tool]
fn task move FN-001 todo                   # Move a task to a column
fn task merge FN-001                     # Merge an in-review task
fn task duplicate FN-001                 # Duplicate a task (copy to triage)
fn task refine FN-001 --feedback "Add tests"  # Create refinement task
fn task archive FN-001                   # Archive a done task
fn task unarchive FN-001                 # Restore an archived task
fn task delete FN-001 [--force]          # Delete a task
fn task retry FN-001                     # Retry a failed task
fn task comment FN-001 "Looks good"      # Add a general task comment
fn task comments FN-001                  # List task comments
fn task steer FN-001 "Use TypeScript"    # Add steering comment
fn task pause FN-001                     # Pause automation for task
fn task unpause FN-001                   # Resume automation for task

Mission Management:

fn mission create "Title" "Description"    # Create a new mission
fn mission list                             # List all missions
fn mission show <id>                        # Show mission with hierarchy
fn mission delete <id> [--force]            # Delete mission (cascades to children)
fn mission activate-slice <slice-id>        # Manually activate a pending slice

Agent Management & Messaging:

fn agent stop <id>                          # Stop a running agent
fn agent start <id>                         # Start/resume a stopped agent
fn agent import <file> [--dry-run] [--skip-existing]
                                            # Import agents from a companies.sh manifest
fn agent mailbox <id>                       # View one agent's mailbox

fn message inbox                            # List inbox messages
fn message outbox                           # List sent messages
fn message send <agent-id> <msg>            # Send a message to an agent
fn message read <id>                        # Read a specific message
fn message delete <id>                      # Delete a message

Git Commands:

fn git status                             # Show branch, commit, dirty state
fn git fetch [remote]                     # Fetch from remote
fn git pull [--yes]                       # Pull current branch
fn git push [--yes]                       # Push current branch

Settings:

fn settings                               # Show current configuration
fn settings set maxConcurrent 4          # Update a setting
fn settings export --scope both           # Export settings to JSON
fn settings import fusion-settings.json --yes  # Import settings

Backup & Restore:

fn backup --create                         # Create a database backup immediately
fn backup --list                           # List all backups with sizes
fn backup --restore backup-file.db        # Restore database from backup
fn backup --cleanup                        # Remove old backups exceeding retention

Task Comments vs Steering Comments

Fusion supports two distinct kinds of discussion on a task:

• Task comments — General collaboration notes for humans. Add from the dashboard or CLI with fn task comment <id> "message".
• Steering comments — Execution guidance aimed at the AI worker. Use for actionable direction like "change this approach." Also populated automatically from actionable PR review feedback.

Refinement Tasks

fn task refine creates a follow-up task in Triage that depends on the original. The title follows the format Refinement: {source label} for easy identification.

Spec Editing, Revision, and Rebuild

From the dashboard task detail modal:

• Edit spec — Update PROMPT.md directly
• AI revision — Submit feedback and ask AI to revise the current specification
• Respecify/Rebuild — Regenerate the specification and move the task back to triage for a fresh spec/review cycle

Use rebuild when requirements changed significantly or the spec drifted from current project reality.

Archive

Completed tasks can be archived to keep the board focused:

fn task archive FN-001        # Archive a done task
fn task unarchive FN-001      # Restore an archived task to done

Archive cleanup removes task directories while preserving compact metadata in .fusion/archive.jsonl. Restored tasks keep all metadata but lose attachments and agent logs. Archived tasks appear in a collapsed "Archived" column in the dashboard.

Model System

Fusion provides flexible AI model configuration with support for model presets, per-task overrides, and a hierarchical settings system.

Model Presets

Model presets let teams standardize AI model choices. Each preset contains:

• ID — stable slug for storage (e.g., budget, normal, complex)
• Name — human-friendly label
• Executor model — provider/model pair for task execution
• Validator model — provider/model pair for code/spec review

Presets can be auto-selected by task size:

• Small (S) → Budget preset
• Medium (M) → Normal preset
• Large (L) → Complex preset

Per-Task Model Overrides

Override global models for specific tasks:

• Executor Model — AI model that implements the task
• Validator Model — AI model that reviews code and plans

Set overrides in the dashboard via task detail → Model tab, or choose Custom during task creation.

Settings Hierarchy

Global settings (~/.pi/fusion/settings.json):

• defaultProvider / defaultModelId — Default AI models
• planningProvider / planningModelId — Task specification models
• validatorProvider / validatorModelId — Review models
• themeMode, colorTheme — UI preferences
• ntfyEnabled, ntfyTopic — Push notifications

Project settings (.fusion/config.json):

• modelPresets — Custom preset definitions
• autoSelectPresetBySize — Size-to-preset mappings
• All workflow and automation settings

Project settings override global settings. Configure in the dashboard under Settings > Model.

Agent Log Model Display

The dashboard Agent Log subview shows which AI models were used for each task (Executor, Validator, Planning/Triage). When no model can be resolved, the header shows "Using default".

Agents Management

Fusion includes a dedicated Agents view in the dashboard for operating autonomous workers:

• Agent list with status and assignment
• Detail panel with runtime configuration and custom instructions
• Health/heartbeat status, recent activity, and run history
• Metrics panels for throughput and reliability trends

Agent Presets and Prompt Templates

Built-in prompt templates are available for common roles:

• default-executor, default-triage, default-reviewer, default-merger
• senior-engineer, strict-reviewer, concise-triage

Assign templates per role with the agentPrompts project setting, and add custom templates for team-specific behavior. You can also set per-agent custom instructions in the dashboard.

Agent Controls (CLI)

fn agent stop <id>
fn agent start <id>
fn agent import <file> [--dry-run] [--skip-existing]
fn agent mailbox <id>

Per-Agent Heartbeat Configuration

Each agent can override heartbeat behavior through runtimeConfig:

• enabled
• heartbeatIntervalMs
• heartbeatTimeoutMs
• maxConcurrentRuns

Configure this in the agent detail panel (Heartbeat Settings). These values control timer triggers, unresponsive detection, and concurrent run limits per agent.

Inter-Agent Messaging

Fusion provides built-in messaging for coordination between users and agents.

• Dashboard mailbox UI — Inbox/outbox view and conversation management
• CLI messaging — Send and manage direct messages from terminal workflows

fn message send <agent-id> <msg>
fn message inbox
fn message outbox
fn message read <id>
fn message delete <id>

Use messaging for handoffs ("review this next"), clarifications, and explicit coordination between specialized agents.

Missions

The Missions system provides a hierarchical planning structure for large-scale projects:

Mission ("Build Auth System")
├── Milestone 1: "Database Schema"
│   ├── Slice 1: "User Tables"
│   │   ├── Feature 1: "User model" → Task FN-101
│   │   └── Feature 2: "Session table" → Task FN-102
│   └── Slice 2: "Token Storage"
│       └── Feature 3: "Refresh tokens" → Task FN-103
├── Milestone 2: "API Endpoints"
│   └── Slice 3: "Login/Logout"
│       ├── Feature 4: "Login endpoint" → Task FN-104
│       └── Feature 5: "Logout endpoint" → Task FN-105
└── Milestone 3: "UI Integration"
    └── Slice 4: "React Components"
        └── Feature 6: "Login form" → Task FN-106

Hierarchy: Mission → Milestone → Slice → Feature → Task

Status flows automatically: when features are linked to tasks and completed, slice status updates. When all slices in a milestone are complete, the milestone becomes complete. When all milestones are done, the mission is complete.

Mission Autopilot

Enable autopilot to let Fusion progress a mission with less manual intervention.

• autopilotEnabled — Primary control to enable active monitoring and progression orchestration for a mission
• autoAdvance — Legacy compatibility field (deprecated); autopilot uses autopilotEnabled as the canonical control

When autopilot is enabled, the runtime tracks task completions and advances mission state through:

inactive → watching → activating → completing

Recovery behavior: When autopilot is enabled and re-engaged (via /resume, PATCH /autopilot, or POST /autopilot/start), the system automatically calls recoverStaleMission to reconcile any inconsistent state (defined features without tasks, stale feature status, etc.) and progress if possible.

Autopilot API endpoints:

• GET /api/missions/:missionId/autopilot
• PATCH /api/missions/:missionId/autopilot ({ enabled: boolean })
• POST /api/missions/:missionId/autopilot/start
• POST /api/missions/:missionId/autopilot/stop

Workflow Steps

Workflow steps are reusable quality gates that run at configurable lifecycle phases. Each step can run as prompt (AI agent review) or script (deterministic command), and at pre-merge (blocks merge) or post-merge (informational) phase.

Execution Phases

Phase	When it runs	Failure behavior
Pre-merge (default)	After task implementation, before in-review	Blocks merge — task stays in in-review
Post-merge	After successful merge to main	Logged only — does not block or rollback

Execution Modes

Mode	How it works	Use for
Prompt	Read-only AI agent reviews changes	Code review, security audits, documentation checks
Script	Runs a named script from settings.scripts	Test suites, linting, type checking

{
  "scripts": {
    "test": "pnpm test",
    "lint": "pnpm lint",
    "typecheck": "pnpm tsc --noEmit"
  }
}

Prompt-mode steps support model overrides — pin a specific AI model per quality gate. Script-mode steps run with a 2-minute timeout.

Built-in Templates

Template	Category	Description
Documentation Review	Quality	Verify all public APIs have documentation
QA Check	Quality	Run tests, check for bugs
Security Audit	Security	Check for vulnerabilities and anti-patterns
Performance Review	Quality	Check for performance anti-patterns
Accessibility Check	Quality	Verify WCAG 2.1 compliance

Click Add on any template in the Workflow Step Manager to create a customizable step.

Default On for New Tasks

Workflow steps can be marked as "Default on for new tasks" in the Workflow Step Manager. When enabled:

• The step is automatically pre-selected in the task creation form
• A gold "Default on" badge appears on the step card in the manager
• Users can still deselect the step — this only controls the initial default state

Behavior during task creation:

Scenario	What happens
User creates task, doesn't modify workflow steps	Auto-selected defaults are applied; backend sends the selected steps
User deselects all auto-selected steps	Empty array is sent to backend — no workflow steps run
User adds additional steps	All selected steps (auto + manual) are included
User re-opens task creation modal	Defaults are re-applied for the new session

Edit mode never auto-injects workflow steps — existing task selections are preserved.

Using Workflow Steps

1. When creating or editing a task, check the workflow steps you want
2. Reorder with ▲/▼ buttons when two or more are selected
3. Pre-merge steps must all pass before the task moves to in-review
4. Post-merge steps run automatically after merge — results appear in the Workflow tab
5. View results in the task detail modal's Workflow tab

Architecture

Storage

Fusion uses a hybrid storage architecture: structured metadata in SQLite with WAL mode for concurrent access, and large files (specs, logs, attachments) on the filesystem.

.fusion/
├── fusion.db                # SQLite database (tasks, config, activity log, agents)
├── config.json              # Project config + settings (synced to SQLite)
├── memory.md                # Project memory — durable learnings across task runs
└── tasks/
    └── FN-001/
        ├── task.json.bak    # Legacy backup (after migration)
        ├── PROMPT.md        # Task specification
        └── attachments/     # File attachments

AI Engine

The AI engine starts automatically with the dashboard. Three components run:

• TriageProcessor — Watches triage column. Spawns an AI agent that reads the project, understands context, and writes a full PROMPT.md specification. When the reviewer flags a task as oversized (8+ steps, 3+ packages, multiple independent deliverables), the triage agent proactively splits it into 2–5 child tasks using task_create and closes the parent. Moves approved single tasks to todo.

• Scheduler — Watches todo column. Resolves dependency graphs. Moves tasks to in-progress when deps are satisfied and concurrency allows (default: 2 concurrent). When groupOverlappingFiles is enabled, tasks whose file scopes overlap are serialized to prevent merge conflicts.

• TaskExecutor — Listens for tasks entering in-progress. Creates a git worktree, spawns an AI agent with full coding tools scoped to the worktree, and executes the specification. If the task has enabled pre-merge workflow steps, runs them sequentially before moving to in-review.

Each AI agent session gets:

• Custom system prompt for its role
• Tools scoped to the correct directory
• In-memory sessions with auto-compaction for long conversations
• Your existing pi auth (API keys from ~/.pi/agent/auth.json)

Error Recovery

The engine automatically recovers from transient failures using bounded exponential backoff:

• Recoverable failures — Transient errors trigger retry with increasing delay (60s → 120s → 240s, capped at 5 minutes). Up to 3 retries before permanent failure.
• Stale worktree/branch references — Automatic pruning, branch deletion, and force-ref cleanup.
• Stuck task detection — When taskStuckTimeoutMs is set, tasks with no agent activity are terminated and re-queued. Detects both dead sessions (no heartbeats) and loops (active but no step progress). Loop recovery attempts compact-and-resume before kill/requeue.
• Context-limit recovery — When an LLM returns context-window overflow, the executor compacts the session and resumes with a fresh prompt.

Project Memory

When memoryEnabled is true (the default), Fusion maintains a project memory file at .fusion/memory.md that accumulates durable learnings across task runs. This file is automatically created with a standard scaffold when:

1. A project is initialized with memory enabled (the default)
2. Memory is toggled from false to true via settings

The memory file is never overwritten — if it already exists (even with custom content), the bootstrap is a no-op.

What goes in memory:

• Architecture patterns and module boundaries
• Project-specific coding conventions and naming standards
• Known pitfalls and things to avoid
• Important context about dependencies, deployment, or constraints

How agents use it:

• Triage agent — Reads memory before writing specifications, incorporating documented patterns and constraints
• Executor agent — Reads memory at the start of execution, then appends new durable learnings before calling task_done()

The memory path is always the project-root .fusion/memory.md, never a worktree-local path. Agents running in worktrees access the file at its project-root location.

To disable project memory:

{
  "memoryEnabled": false
}

Packages

Package	Description
@fusion/core	Domain model — tasks, board columns, SQLite store
@fusion/dashboard	Web UI — Express server + kanban board with SSE
@fusion/engine	AI engine — triage, execution, scheduling, workflow steps
@fusion/tui	Terminal UI — Ink-based CLI components
@gsxdsm/fusion	CLI + pi extension — published to npm

Configuration Reference

Fusion uses a two-tier settings hierarchy:

• Global settings (~/.pi/fusion/settings.json) — User preferences across all projects
• Project settings (.fusion/config.json) — Project-specific workflow settings

Project settings override global settings. Configure in the dashboard under Settings.

Settings Table

Setting	Scope	Default	Description
defaultProvider	Global	-	Default AI model provider
defaultModelId	Global	-	Default AI model ID
planningProvider	Global	-	Model provider for task specification
planningModelId	Global	-	Model ID for task specification
validatorProvider	Global	-	Model provider for code/spec review
validatorModelId	Global	-	Model ID for review
defaultThinkingLevel	Global	-	Default thinking effort level
themeMode	Global	dark	UI theme: dark/light/system
colorTheme	Global	default	Color theme name
ntfyEnabled	Global	false	Enable push notifications
ntfyTopic	Global	-	ntfy.sh topic for notifications
ntfyDashboardHost	Global	-	Dashboard URL for notification deep links
modelOnboardingComplete	Global	false	Tracks completion of first-run model onboarding wizard
maxConcurrent	Project	2	Concurrent task execution limit
autoMerge	Project	true	Auto-merge completed tasks
smartConflictResolution	Project	true	Auto-resolve lock/generated files
requirePlanApproval	Project	false	Manual approval for AI specs
taskStuckTimeoutMs	Project	-	Stuck task detection timeout (ms)
runStepsInNewSessions	Project	false	Run each task step in its own agent session
maxParallelSteps	Project	2	Max concurrent steps when per-step sessions are enabled
worktreeNaming	Project	random	Worktree naming: random/task-id/task-title
recycleWorktrees	Project	false	Pool and reuse worktrees for efficiency
groupOverlappingFiles	Project	false	Serialize tasks with shared file scopes
agentPrompts	Project	-	Role-based prompt templates and assignments
autoSummarizeTitles	Project	false	Auto-generate titles for untitled tasks
autoBackupEnabled	Project	false	Enable automatic database backups
autoBackupSchedule	Project	0 2 * * *	Cron expression for backup schedule
autoBackupRetention	Project	7	Number of backups to retain (1–100)
prCompletionMode	Project	direct	Completion: direct/pr-first

Key Settings Explained

Smart Conflict Resolution:

{
  "settings": {
    "smartConflictResolution": true
  }
}

Automatically resolves lock files ("ours"), generated files ("theirs"), and trivial whitespace conflicts during merge.

Stuck Task Detection:

{
  "settings": {
    "taskStuckTimeoutMs": 600000
  }
}

Terminates and retries tasks with no agent activity for 10 minutes. Detects dead sessions and loops separately, with compact-and-resume recovery for loops.

Push Notifications:

{
  "settings": {
    "ntfyEnabled": true,
    "ntfyTopic": "my-kb-notifications"
  }
}

Get notified when tasks complete, merge, or fail. Includes dashboard deep links when ntfyDashboardHost is set.

Plan Approval:

{
  "settings": {
    "requirePlanApproval": true
  }
}

AI-generated specifications require manual approval before moving to Todo. Tasks show "Awaiting Approval" status with amber highlighting.

Comment-Aware Triage & Spec Review:

User comments on triage tasks are automatically consumed during specification generation and spec review:

• During triage: The AI triage agent sees all user comments as explicit feedback context, ensuring the specification addresses every user concern.
• During spec review: The reviewer explicitly verifies that every user comment is addressed in the PROMPT.md. Missing comment coverage results in a REVISE verdict.
• Stale approval invalidation: If a new user comment arrives after the spec was approved, the approval is automatically invalidated. The task returns to triage with needs-respecify status, triggering re-specification and re-review before the task can advance to execution. This prevents stale specs from reaching the execution phase when users provide late feedback.

Auto-Backup:

{
  "settings": {
    "autoBackupEnabled": true,
    "autoBackupSchedule": "0 2 * * *",
    "autoBackupRetention": 7
  }
}

Automatic SQLite database backups with configurable schedule, retention, and directory.

Worktree Naming & Recycling:

{
  "settings": {
    "worktreeNaming": "task-id",
    "recycleWorktrees": true
  }
}

• worktreeNaming: Control directory names — random (human-friendly like swift-falcon), task-id (e.g., fn-042), or task-title (slugified title)
• recycleWorktrees: Pool and reuse worktree directories for efficiency instead of creating new ones per task

Scheduled Tasks

Automate recurring workflows with multi-step scheduled tasks:

Preset	Cron	Description
every15Minutes	*/15 * * * *	Every 15 minutes
hourly	0 * * * *	Every hour
daily	0 0 * * *	Daily at midnight
weekdays	0 0 * * 1-5	Weekdays at midnight
weekly	0 0 * * 0	Weekly on Sunday
custom	—	Define your own cron

Each schedule contains multiple steps executed sequentially. Steps can be commands (with timeout and continueOnFailure options) or AI prompts. Step creation works in all browser environments, including non-secure contexts (HTTP) where crypto.randomUUID() is unavailable, via deterministic fallback ID generation. Access via the Scheduled Tasks button in the dashboard header.

Development

pnpm install
pnpm dev:ui                     # Dashboard only; builds and typechecks first
pnpm dev dashboard              # Board + AI engine
pnpm dev task list              # CLI commands
pnpm --filter @fusion/desktop dev   # Desktop hot-reload workflow (renderer + Electron)
pnpm build:desktop              # Production desktop build pipeline
pnpm typecheck                  # Type-check all packages (no build required)
pnpm test                       # Run all tests

Building 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

Target	Output
bun-linux-x64	fusion-linux-x64
bun-linux-arm64	fusion-linux-arm64
bun-darwin-x64	fusion-darwin-x64
bun-darwin-arm64	fusion-darwin-arm64
bun-windows-x64	fusion-windows-x64.exe

Override the dashboard asset path via FUSION_CLIENT_DIR environment variable. Prerequisites: Bun ≥ 1.0.

Releases

Packages are published to npm automatically via GitHub Actions and changesets.

npm install -g @gsxdsm/fusion

See RELEASING.md for the full workflow. In short: add a changeset with pnpm changeset, merge to main, then merge the auto-generated "Version Packages" PR.

License

ISC