# 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](https://github.com/badlogic/pi-mono).

![Fusion dashboard](demo/screenshot.png)

**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:**
   ```bash
   npm i -g @gsxdsm/fusion
   ```

2. **Initialize (or just start the dashboard):**
   ```bash
   fn dashboard
   ```

3. **Open** [http://localhost:4040](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](https://github.com/badlogic/pi-mono) 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](./MOBILE.md).

## Docker

Quick start:

```bash
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](./docs/docker.md).

## Workflow

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

    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:

```bash
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.

```bash
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

```bash
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

```bash
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:

```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:

```bash
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)

```bash
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

```bash
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 |

```json
{
  "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:
```json
{
  "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:**
```json
{
  "settings": {
    "smartConflictResolution": true
  }
}
```
Automatically resolves lock files ("ours"), generated files ("theirs"), and trivial whitespace conflicts during merge.

**Stuck Task Detection:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "settings": {
    "autoBackupEnabled": true,
    "autoBackupSchedule": "0 2 * * *",
    "autoBackupRetention": 7
  }
}
```
Automatic SQLite database backups with configurable schedule, retention, and directory.

**Worktree Naming & Recycling:**
```json
{
  "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

```bash
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](https://bun.sh/):

```bash
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](https://github.com/changesets/changesets).

```bash
npm install -g @gsxdsm/fusion
```

See [RELEASING.md](./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