flg #

Flutter Generator - A powerful CLI tool for generating Flutter projects with Clean Architecture, feature-first organization, and your choice of modern state management.

Inspired by Angular CLI, flg eliminates boilerplate and enforces architectural consistency across your Flutter projects.

Features #

Quick Start #

Installation #

# From pub.dev (recommended)
dart pub global activate flg

# Or from source
git clone https://github.com/saulram/flg.git
cd flg
dart pub global activate --source path .

Create a New Project #

# Interactive mode (recommended for first-time users)
flg init my_app

# Non-interactive with defaults
flg init my_app -s

# With specific options
flg init my_app --state riverpod --router go_router --org com.mycompany

Set Up an Existing Project #

cd my_existing_flutter_app
flg setup

Generate Components #

# Generate a feature
flg g f auth

# Generate a screen
flg g s login -f auth

# Generate a widget
flg g w user_avatar -f auth

# Generate CRUD use cases
flg g u user -f user --crud

# Generate a repository
flg g r user -f user

Commands #

flg init <project_name> #

Creates a new Flutter project with Clean Architecture.

flg setup #

Configures flg in an existing Flutter project.

flg generate <component> (alias: g) #

Generates code components within a flg project.

Examples

# Feature with custom entity
flg g f product --entity product_item

# Stateful widget
flg g w product_form -f product -t stateful

# Form widget
flg g w checkout_form -f checkout -t form

# Single use case
flg g u authenticate -f auth -a create

# All CRUD use cases at once
flg g u product -f product --crud

flg task (alias: t) #

Manage git worktrees for AI agent workflows. Perfect for running multiple Claude Code, Cursor, or other AI agents in parallel on separate tasks.

flg task add <name>

Examples

# Create tasks for parallel AI agents
flg task add auth-feature --agent
flg task add fix-payment --type fix --agent
flg task add refactor-api --type ref --agent

# Check status of all tasks
flg task status

# List active worktrees
flg task list

# Remove when done
flg task remove auth-feature

Output Example

✓ Created task: feat-auth
  → Path: /Users/dev/my_app-tasks/feat-auth
  → Branch: feat/auth

✓ Running flutter pub get...
✓ Created .claude/TASK.md

Ready for AI Agent:
/Users/dev/my_app-tasks/feat-auth

Worktrees are created in ../[project-name]-tasks/ as sibling directories to your main project.

Project Structure #

After running flg init my_app, you get:

my_app/
├── lib/
│   ├── main.dart
│   ├── core/
│   │   ├── error/
│   │   │   ├── exceptions.dart
│   │   │   └── failures.dart
│   │   ├── usecases/
│   │   │   └── usecase.dart
│   │   ├── router/
│   │   │   └── app_router.dart
│   │   ├── network/
│   │   └── utils/
│   └── features/
│       └── home/
│           ├── domain/
│           │   ├── entities/
│           │   │   └── home_entity.dart
│           │   ├── repositories/
│           │   │   └── home_repository.dart
│           │   └── usecases/
│           ├── data/
│           │   ├── models/
│           │   │   └── home_model.dart
│           │   ├── repositories/
│           │   │   └── home_repository_impl.dart
│           │   └── datasources/
│           │       └── home_remote_datasource.dart
│           └── presentation/
│               ├── screens/
│               │   └── home_screen.dart
│               ├── widgets/
│               │   └── home_card.dart
│               └── providers/
│                   ├── home_provider.dart
│                   ├── home_provider.g.dart
│                   ├── home_state.dart
│                   └── home_state.freezed.dart
├── test/
│   ├── unit/
│   ├── integration/
│   └── fixtures/
├── pubspec.yaml
└── flg.json

State Management #

Riverpod (Default) #

Uses modern riverpod_annotation with code generation:

import 'package:riverpod_annotation/riverpod_annotation.dart';

part 'home_provider.g.dart';

@riverpod
class Home extends _$Home {
  @override
  HomeState build() => const HomeState();

  Future<void> loadAll() async {
    state = state.copyWith(isLoading: true);
    final result = await _repository.getAll();
    result.fold(
      (failure) => state = state.copyWith(
        isLoading: false,
        errorMessage: failure.message,
      ),
      (items) => state = state.copyWith(
        isLoading: false,
        homes: items,
      ),
    );
  }
}

This generates a provider named homeProvider (not homeNotifierProvider).

State classes use Freezed with sealed class:

@freezed
sealed class HomeState with _$HomeState {
  const factory HomeState({
    @Default([]) List<HomeEntity> homes,
    HomeEntity? selectedHome,
    @Default(false) bool isLoading,
    String? errorMessage,
  }) = _HomeState;

  const HomeState._();

  bool get hasError => errorMessage != null;
  bool get isEmpty => homes.isEmpty;
}

Bloc #

Full Bloc pattern with events and states:

class HomeBloc extends Bloc<HomeEvent, HomeState> {
  HomeBloc(this._repository) : super(const HomeInitial()) {
    on<LoadHomesEvent>(_onLoadHomes);
  }

  final HomeRepository _repository;

  Future<void> _onLoadHomes(LoadHomesEvent event, Emitter<HomeState> emit) async {
    emit(const HomeLoading());
    final result = await _repository.getAll();
    result.fold(
      (failure) => emit(HomeError(failure.message)),
      (homes) => emit(HomeLoaded(homes)),
    );
  }
}

Provider #

Simple ChangeNotifier pattern:

class HomeProvider extends ChangeNotifier {
  final HomeRepository _repository;

  List<HomeEntity> _homes = [];
  bool _isLoading = false;
  String? _error;

  Future<void> loadAll() async {
    _isLoading = true;
    notifyListeners();

    final result = await _repository.getAll();
    result.fold(
      (failure) => _error = failure.message,
      (homes) => _homes = homes,
    );

    _isLoading = false;
    notifyListeners();
  }
}

Configuration #

The flg.json file stores project configuration:

{
  "projectName": "my_app",
  "org": "com.example",
  "stateManagement": "riverpod",
  "router": "go_router",
  "useFreezed": true,
  "useDioClient": true,
  "platforms": ["android", "ios"],
  "features": ["home"],
  "generateTests": true,
  "l10n": false
}

This file is automatically created during init or setup and is used by generate commands to maintain consistency.

Architecture Overview #

flg generates code following Clean Architecture principles:

┌─────────────────────────────────────────────────────────┐
│                    Presentation Layer                    │
│  ┌─────────┐  ┌──────────────┐  ┌───────────────────┐  │
│  │ Screens │  │   Widgets    │  │ Providers/Blocs   │  │
│  └─────────┘  └──────────────┘  └───────────────────┘  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                      Domain Layer                        │
│  ┌──────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │ Entities │  │ Repository Intf. │  │   UseCases   │  │
│  └──────────┘  └──────────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                       Data Layer                         │
│  ┌────────┐  ┌───────────────────┐  ┌───────────────┐  │
│  │ Models │  │ Repository Impl.  │  │  DataSources  │  │
│  └────────┘  └───────────────────┘  └───────────────┘  │
└─────────────────────────────────────────────────────────┘

Key Patterns #

• Entities: Pure Dart classes representing business objects
• Repositories: Abstract interfaces in domain, implementations in data
• Use Cases: Single-responsibility classes for business logic
• Models: Data classes with JSON serialization (Freezed-based)
• DataSources: Handle external data (API, database, cache)

Known Limitations #

Current Limitations #

1. No test file generation: Test scaffolding is not yet implemented. The test/ directory structure is created but test files are not generated.

2. No migration support: Upgrading configuration after setup or init requires manual intervention.

3. Single datasource per feature: Currently generates only remote datasources. Local caching datasources require manual implementation.

4. No DI container setup: Dependency injection setup (get_it, injectable) is not included. Repository injection in notifiers requires manual wiring.

Planned Features #

• ❌ Test file generation with mocking
• ❌ get_it / injectable integration
• ❌ Local datasource templates (Hive, SQLite)
• ❌ Migration command for config updates
• ❌ Custom template support

Troubleshooting #

build_runner fails #

If code generation fails after project creation:

# For Flutter projects
flutter pub run build_runner build --delete-conflicting-outputs

# Watch mode for development
flutter pub run build_runner watch --delete-conflicting-outputs

Riverpod provider not found #

Ensure you've run build_runner after adding new providers. The .g.dart files must be generated.

Import errors #

flg uses absolute package imports (package:my_app/...). If you rename your project, update the name field in pubspec.yaml and regenerate imports.

Requirements #

• Dart SDK: ^3.0.0
• Flutter (for generated projects): ^3.0.0

AI Assistant Integration #

flg integrates with AI coding assistants through the Model Context Protocol (MCP), enabling AI assistants to create Flutter projects and generate code directly.

Key Feature: When MCP is configured, asking your AI assistant to "create a Flutter project" will automatically use flg init instead of flutter create, giving you Clean Architecture from the start.

Supported AI Assistants #

MCP Configuration #

MCP servers can be configured globally (available in all projects) or per-project (only in specific projects).

Option 1: Global Configuration (Recommended)

Global configuration makes flg available in all your projects. Requires flg to be installed globally:

dart pub global activate flg

Claude Code:

# Using Claude CLI (easiest)
claude mcp add --scope user flg -- flg_mcp

Or manually edit ~/.claude/settings.json:

{
  "mcpServers": {
    "flg": {
      "command": "flg_mcp"
    }
  }
}

Gemini CLI:

# Using Gemini CLI (easiest)
gemini mcp add --scope user flg -- flg_mcp

Or manually edit ~/.gemini/settings.json:

{
  "mcpServers": {
    "flg": {
      "command": "flg_mcp"
    }
  }
}

Note: If flg_mcp is not found, ensure Dart's pub cache bin is in your PATH:

export PATH="$PATH:$HOME/.pub-cache/bin"

Option 2: Per-Project Configuration

Per-project configuration limits flg to specific projects. You can either use the global flg_mcp command or reference flg as a dev dependency.

Using global flg_mcp (simpler):

# Claude Code
claude mcp add --scope project flg -- flg_mcp

# Gemini CLI
gemini mcp add --scope project flg -- flg_mcp

Using flg as a dev dependency:

First add flg to your project:

dart pub add --dev flg

Then configure MCP:

Claude Code - Create .mcp.json in your project root:

{
  "mcpServers": {
    "flg": {
      "command": "dart",
      "args": ["run", "flg:flg_mcp"]
    }
  }
}

Gemini CLI - Create .gemini/settings.json in your project root:

{
  "mcpServers": {
    "flg": {
      "command": "dart",
      "args": ["run", "flg:flg_mcp"]
    }
  }
}

Configuration Precedence

When both global and per-project configurations exist:

• Per-project settings take precedence over global settings
• This allows you to override or disable specific MCP servers per project

Available MCP Tools #

Once configured, your AI assistant can use these tools:

Each tool accepts a path parameter to specify the Flutter project directory (defaults to current directory).

Usage Examples #

Once MCP is configured, you can interact naturally with your AI assistant:

User: Create a new Flutter app called "todo_app" with Bloc

AI: [Uses flg_init to create the project with Clean Architecture and Bloc]

User: Generate an auth feature for my app

AI: [Uses flg_generate_feature to create the complete auth module]

User: Add a login screen to the auth feature

AI: [Uses flg_generate_screen to create login_screen.dart]

Verifying MCP Configuration #

Claude Code:

# List all configured MCP servers
claude mcp list

# Test the flg server
claude mcp run flg flg_info

Gemini CLI:

# List configured servers
gemini mcp list

# Check MCP server status
/mcp

Claude Code Skill (Alternative) #

In addition to MCP, flg provides a Claude Code skill for quick command reference. When working in a project with flg, the /flg skill is available. The skill documentation is in .claude/skills/flg/SKILL.md.

Contributing #

Contributions are welcome! Please see the GitHub repository for:

• Issue Tracker
• Pull Requests

License #

MIT License - see LICENSE file for details.

Credits #

Created by Saul Ramirez

Inspired by:

• Angular CLI
• Very Good CLI
• Clean Architecture by Robert C. Martin