ghostty_vte_flutter

Flutter terminal UI widgets powered by Ghostty's VT engine. Drop-in GhosttyTerminalView and GhosttyTerminalController for embedding a terminal in any Flutter app — on desktop, mobile, and the web.

Features

This package re-exports all of ghostty_vte, so you only need a single import.

Platform support

Installation

dependencies:
  ghostty_vte_flutter: ^0.0.1

No separate ghostty_vte dependency is needed — it's re-exported automatically.

Quick start

import 'package:flutter/material.dart';
import 'package:ghostty_vte_flutter/ghostty_vte_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await initializeGhosttyVteWeb(); // no-op on native, loads wasm on web
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});
  @override
  Widget build(BuildContext context) => const MaterialApp(home: TerminalPage());
}

class TerminalPage extends StatefulWidget {
  const TerminalPage({super.key});
  @override
  State<TerminalPage> createState() => _TerminalPageState();
}

class _TerminalPageState extends State<TerminalPage> {
  final _ctrl = GhosttyTerminalController();

  @override
  void initState() {
    super.initState();
    _ctrl.start();
  }

  @override
  void dispose() {
    _ctrl.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Terminal')),
      body: GhosttyTerminalView(controller: _ctrl, autofocus: true),
    );
  }
}

Widgets & controllers

GhosttyTerminalView

A CustomPaint widget that renders terminal output and routes keyboard events through the Ghostty key encoder.

GhosttyTerminalView(
  controller: myController,
  autofocus: true,
  backgroundColor: const Color(0xFF0A0F14),
  foregroundColor: const Color(0xFFE6EDF3),
  fontSize: 14,
  lineHeight: 1.35,
  fontFamily: 'JetBrainsMono Nerd Font',
  cellWidthScale: 1.0,
  padding: const EdgeInsets.all(12),
)

GhosttyTerminalView now paints grapheme clusters instead of UTF-16 code units and exposes font-metric controls so shells with Nerd Font glyphs or heavier prompt redraw behavior can be tuned without forking the widget.

GhosttyTerminalController

A ChangeNotifier managing a terminal session.

• Native: prefers a shared PTY session through GhosttyTerminalPtySession with fallback to Process.start when PTY startup is disabled or fails.
• Web: same API surface — feed output through appendDebugOutput() and read input via write() / sendKey() to connect a remote backend.

final controller = GhosttyTerminalController(
  maxLines: 2000,
  defaultShell: '/bin/bash',
);

await controller.start(
  environment: ghosttyTerminalShellEnvironment(
    platformEnvironment: ghosttyTerminalPlatformEnvironment(),
    overrides: const {'TERM': 'xterm-256color'},
  ),
);
controller.write('ls -la\n', sanitizePaste: true);

controller.sendKey(
  key: GhosttyKey.GHOSTTY_KEY_C,
  mods: GhosttyModsMask.ctrl,
  utf8Text: 'c',
  unshiftedCodepoint: 0x63,
);

print(controller.title);     // window title from OSC
print(controller.lines);     // buffered output lines
print(controller.isRunning); // subprocess alive?

await controller.stop();
controller.dispose();

ghosttyTerminalShellEnvironment(...) is the shared helper for building a usable native shell environment. It preserves the caller's base environment, sets TERM, fills HOME-derived XDG_* paths, and ensures a UTF-8 locale when the input environment omitted one.

ghosttyTerminalShellLaunches(...) is the shared preset resolver. It returns normalized launch plans for GhosttyTerminalShellProfile.auto, GhosttyTerminalShellProfile.cleanBash, GhosttyTerminalShellProfile.cleanZsh, and GhosttyTerminalShellProfile.userShell.

final controller = GhosttyTerminalController();
final launch = await controller.startShellProfile(
  profile: GhosttyTerminalShellProfile.cleanBash,
  platformEnvironment: ghosttyTerminalPlatformEnvironment(),
);

print(controller.activeShellLaunch?.commandLine);
print(controller.activeShellLaunch?.environment?['TERM']);

Web setup

1. Build the wasm module:

   cd pkgs/vte/ghostty_vte
   dart run tool/build_wasm.dart
   

   This produces ghostty-vt.wasm in the Flutter assets directory.

2. Initialise before runApp:

   await initializeGhosttyVteWeb();
   

   This is a no-op on native platforms.

3. Build for web:

   flutter build web --wasm
   

Native setup

No manual steps needed. The ghostty_vte build hook runs automatically during flutter run and flutter build, producing the correct native library for your target. Just make sure Zig and the Ghostty source are available — see the ghostty_vte README for details.

Or download prebuilt libraries to skip the Zig requirement entirely.

Related packages

License

MIT — see LICENSE.