The Problem

Flutter development assumes you’re using an IDE. If you prefer terminal-based workflows or AI coding tools like Claude Code, you lose automatic hot reload. Manually pressing ‘r’ after every change breaks flow.

The Solution

Flutter has built-in support for triggering hot reload via Unix signals:

  • SIGUSR1 - hot reload (for Dart code changes)
  • SIGUSR2 - hot restart (for asset or dependency changes)

The approach:

  1. Watch Flutter project files for changes
  2. Send the appropriate signal when files are modified
  3. Get seamless IDE-free development

Implementation

Shell script wrapper

Manages both Flutter and the file watcher:

# run_with_auto_reload.sh
PID_FILE="/tmp/flutter-app-$$.pid"
trap 'kill "$FLUTTER_PID" "$WATCHER_PID" 2>/dev/null; rm -f "$PID_FILE"' INT TERM EXIT

dart tools/auto_reload_watcher.dart --wait --pid-file="$PID_FILE" &
WATCHER_PID=$!

flutter run --debug --hot --pid-file="$PID_FILE"

File watcher

Monitors file system changes and sends signals:

// auto_reload_watcher.dart
Directory('lib').watch(recursive: true).listen((event) {
  if (event.path.endsWith('.dart')) {
    Process.runSync('kill', ['-SIGUSR1', pid]); // Hot reload
  }
});

File('pubspec.yaml').parent.watch().listen((event) {
  if (event.path.contains('pubspec')) {
    Process.runSync('kill', ['-SIGUSR2', pid]); // Hot restart
  }
});

How it works

  • Flutter writes its PID to a file when run with --pid-file
  • Dart’s Directory.watch() monitors for file changes
  • When changes are detected, send Unix signals to trigger reload
  • .dart files trigger hot reload (fast, preserves state)
  • pubspec.yaml triggers hot restart (slower, resets state)

Usage

Basic

./tools/run_with_auto_reload.sh

With specific device

./tools/run_with_auto_reload.sh chrome
./tools/run_with_auto_reload.sh 00008130-000E354424C1401C  # iPhone

Multi-device development

I run three terminal panes (iOS, Android, web), each with the auto-reload script for a different target. All devices hot reload instantly when I save. Cross-platform testing becomes significantly more efficient.

What Works

Benefits

  • Works with any editor that saves files
  • Preserves manual reload commands (r, R, q)
  • Lightweight: no IDE overhead
  • Uses native OS file system events (inotify, FSEvents)
  • Minimal CPU usage when idle

Edge cases handled

  • PID file synchronization: watcher waits for Flutter to write PID
  • Process cleanup: trap ensures cleanup on termination
  • Multi-device support: run multiple instances simultaneously

What This Doesn’t Solve

This approach has limits:

  • Unix/macOS only (Windows needs different signal handling)
  • Requires Flutter to support --pid-file flag
  • No GUI for configuration or status
  • Doesn’t handle asset changes beyond pubspec.yaml
  • No smart detection (reloads even for comment-only changes)

For full IDE features (debugging, profiling, device management), use VS Code or Android Studio. This tool optimizes for terminal workflows and AI coding assistants, not comprehensive development environments.

Source Code

Available on GitHub at github.com/paddo/flutter-auto-reload

Related Posts