Skip to main content

​
libghostty C API Overview

The libghostty C API enables you to embed a fast, feature-rich terminal emulator into any application. This library provides the core terminal functionality that powers the Ghostty terminal emulator.
The libghostty API is currently used primarily by the macOS app and is not yet stabilized for general-purpose embedding. The API may change significantly between releases.

​
What is libghostty?

libghostty is a C-compatible library that provides:
  • Full terminal emulation - Standards-compliant VT100/xterm emulation
  • Native rendering - Metal on macOS, OpenGL on Linux
  • Cross-platform support - macOS, iOS, Linux
  • Modern features - Ligatures, color schemes, splits, tabs
  • High performance - Dedicated IO threads, GPU-accelerated rendering

​
Use Cases

Common use cases for embedding libghostty:
  • Native terminal apps - Build platform-native terminal emulators (like the Ghostty macOS app)
  • IDE/Editor integration - Embed terminals in code editors and IDEs
  • DevOps tools - Add terminal capabilities to development and operations tools
  • Educational software - Interactive coding environments and tutorials

​
Architecture

The libghostty API is organized around several key concepts: 
// Core types
typedef void* ghostty_app_t;        // Application instance
typedef void* ghostty_config_t;     // Configuration
typedef void* ghostty_surface_t;    // Terminal surface
typedef void* ghostty_inspector_t;  // Inspector/debugger

​
Application Flow

  1. Initialize - Call ghostty_init() to set up global state
  2. Configure - Create and configure ghostty_config_t
  3. Create App - Initialize ghostty_app_t with runtime callbacks
  4. Create Surfaces - Create one or more ghostty_surface_t for terminals
  5. Event Loop - Call ghostty_app_tick() regularly and handle callbacks
  6. Render - Call ghostty_surface_draw() when rendering is needed
  7. Cleanup - Free surfaces, app, and config on shutdown

​
Platform Support

Full support with Metal rendering:
  • SwiftUI/AppKit integration
  • Metal rendering backend
  • CoreText font discovery
  • Native menu and window chrome
ghostty_surface_config_s config = {
  .platform_tag = GHOSTTY_PLATFORM_MACOS,
  .platform = { .macos = { .nsview = myNSView } },
  .scale_factor = 2.0,
  // ...
};

​
Quick Example

Here’s a minimal example of embedding libghostty: 
#include <ghostty.h>

// Runtime callbacks
void wakeup_cb(void* userdata) {
    // Wake up event loop
}

bool action_cb(ghostty_app_t app, ghostty_target_s target, ghostty_action_s action) {
    // Handle actions from terminal
    return true;
}

int main(int argc, char** argv) {
    // Initialize global state
    if (ghostty_init(argc, (char**)argv) != GHOSTTY_SUCCESS) {
        return 1;
    }
    
    // Create configuration
    ghostty_config_t config = ghostty_config_new();
    ghostty_config_load_default_files(config);
    ghostty_config_finalize(config);
    
    // Set up runtime callbacks
    ghostty_runtime_config_s runtime = {
        .userdata = NULL,
        .wakeup_cb = wakeup_cb,
        .action_cb = action_cb,
        // ... other callbacks
    };
    
    // Create app
    ghostty_app_t app = ghostty_app_new(&runtime, config);
    
    // Create surface
    ghostty_surface_config_s surf_config = ghostty_surface_config_new();
    surf_config.platform_tag = GHOSTTY_PLATFORM_MACOS;
    // ... configure platform-specific fields
    
    ghostty_surface_t surface = ghostty_surface_new(app, &surf_config);
    
    // Event loop
    while (running) {
        ghostty_app_tick(app);
        ghostty_surface_draw(surface);
    }
    
    // Cleanup
    ghostty_surface_free(surface);
    ghostty_app_free(app);
    ghostty_config_free(config);
    
    return 0;
}

​
Next Steps

​
API Stability

The current libghostty API is not stable. Future versions of libghostty-vt will provide a stable, cross-platform terminal parsing library. The full libghostty embedding API will be stabilized in a future release. See the libghostty blog post for more details on the roadmap.