Plugin Manifest

Every Ghosty plugin must include a plugin.yaml file at the root of its project. This manifest declares the plugin's identity, capabilities, required permissions, and view configuration. The Ghosty runtime reads this file at install time to determine how the plugin should be loaded and displayed.

Minimal example

The smallest valid manifest looks like this:

name: hello-world
version: 1.0.0
display_name: Hello World
description: A simple greeting plugin.
author: your-username
 
views:
  widget:
    entry: src/widget.ts
    default_size: small

This declares a plugin named hello-world that provides a single dashboard widget rendered from src/widget.ts.

Full reference

Below is the complete list of manifest fields. Required fields are marked with an asterisk (*).

Top-level fields

permissions

The permissions block declares which platform capabilities the plugin needs. Each permission must be explicitly requested; the user is prompted to grant access at install time.

permissions:
  - storage.read
  - storage.write
  - notifications.show
  - network.fetch

See the Permissions page for the full list of available permissions and their risk levels.

views

The views block declares the UI surfaces your plugin provides. A plugin can have a widget view, a fullscreen view, or both.

views.widget

views:
  widget:
    entry: src/widget.ts
    default_size: medium
    min_size: small
    max_size: large
    resizable: true
    refresh_interval: 300  # refresh every 5 minutes

views.fullscreen

views:
  fullscreen:
    entry: src/fullscreen.ts
    title: My Plugin
    show_back_button: true
    settings_entry: src/settings.ts

ai_context

Optional block that provides additional context to the Ghosty AI assistant about what your plugin does. This helps the assistant recommend your plugin to users in natural language conversations.

ai_context:
  summary: A task manager that helps users organise their daily to-do list.
  capabilities:
    - Create, edit, and delete tasks
    - Set due dates and reminders
    - Track completion streaks
  trigger_phrases:
    - show my tasks
    - add a to-do
    - what's on my list today

sandbox

Advanced configuration for the plugin sandbox. Most plugins do not need to change these defaults.

Validation

The Playground validates your manifest in real-time as you edit. Paste or type your plugin.yaml content into the manifest panel and the Playground will immediately highlight any errors.

Common validation errors:

• name contains invalid characters -- only lowercase letters, numbers, and hyphens are allowed.
• version is not semver -- use the MAJOR.MINOR.PATCH format.
• Unknown permission -- check the Permissions page for valid keys.
• Missing entry in view -- every declared view must have an entry field pointing to an existing file.
• Icon is not 512x512 -- the icon must be exactly 512 by 512 pixels in PNG format.

Complete example

name: weather-widget
version: 2.1.0
display_name: Weather Widget
description: Real-time weather conditions and 5-day forecast for any city.
author: ghosty-team
homepage: https://github.com/ghosty-team/weather-widget
license: MIT
icon: assets/icon.png
min_ghosty_version: 1.2.0
tags:
  - weather
  - productivity
  - dashboard
 
permissions:
  - storage.read
  - storage.write
  - network.fetch
  - notifications.show
 
views:
  widget:
    entry: src/widget.ts
    default_size: medium
    resizable: true
    refresh_interval: 600
  fullscreen:
    entry: src/fullscreen.ts
    title: Weather Details
    settings_entry: src/settings.ts
 
ai_context:
  summary: Shows current weather and forecasts for the user's saved locations.
  capabilities:
    - Display current temperature and conditions
    - Show a 5-day forecast
    - Support multiple saved locations
  trigger_phrases:
    - what's the weather
    - show me the forecast
    - is it going to rain