Basic Usage

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• doc/faq.md
• doc/design.md
• manifest_template.json
• CONTRIBUTING.md

Ghostbird is a Thunderbird add-on that enables you to compose emails using your favorite external text editor. It achieves this by implementing the GhostText protocol, which facilitates real-time text synchronization between Thunderbird's compose window and a text editor running a GhostText server plugin.

The core functionality involves establishing a WebSocket connection to a GhostText server, which listens on port 4001 by default. Ghostbird relays messages between the Thunderbird compose window and the server, allowing you to leverage the full power of your preferred editor for writing emails.

Sources: README.md:10-16, doc/faq.md:3-7, CONTRIBUTING.md:11-13

Requirements

Before using Ghostbird, ensure you have the following set up:

• Thunderbird: Version 128 or newer (latest ESR is the main target).
• Text Editor with GhostText Server: A text editor with a compatible GhostText server add-on installed and running. Supported editors include:
  • Vim / Neovim
  • VS Code / VSCodium
  • Sublime Text
  • Emacs
  • Acme
  • Helix
  • Any editor via wrappers like GhostText-Any.

Sources: README.md:18-31, doc/faq.md:13-14

Installation

You can install the Ghostbird add-on in two primary ways.

Install within Thunderbird (Recommended)

1. In Thunderbird, navigate to the Add-ons Manager.
2. Search for "Ghostbird".
3. Click the + Add to Thunderbird button to install.

Sources: README.md:41-44

Download and Install Manually

1. Download the latest .xpi file from the Thunderbird add-on website (AMO) or GitHub Releases.
2. In Thunderbird, go to the Add-ons Manager.
3. Drag and drop the downloaded .xpi file into the manager window.
4. Alternatively, click the gear icon (⚙️) and select Install Add-on From File... to select the .xpi file.

Sources: README.md:46-55

Core Workflow

The basic process for using Ghostbird involves initiating a connection from Thunderbird to your text editor.

1. Launch your text editor and start its GhostText server (e.g., by running :GhostTextStart in Vim).
2. In a Thunderbird mail compose window, click the gray Ghostbird button on the toolbar. The default keyboard shortcut is Ctrl+Shift+H.
3. The button's color indicates the connection status.
4. Once the connection is successful (blue button), your email's content will appear in your text editor. You can now write and edit the email there.
5. To end the session, close the file in your text editor or use the "stop" command in Thunderbird.

Sources: README.md:59-67, manifest_template.json:44-47

Button States

The Ghostbird icon in the compose window toolbar changes color to reflect the connection status.

State	Description
	Disconnected: Ghostbird is inactive. Click to initiate a connection.
	Connected: A successful WebSocket connection is established with the GhostText server. Text is synchronized with your editor.
	Connection Failed: Ghostbird could not connect to the server. Ensure the GhostText server is running in your editor on the correct port.

Sources: README.md:61-63

How It Works

Ghostbird acts as a bridge between Thunderbird's compose window and an external text editor's GhostText server.

This diagram illustrates the high-level data flow between the components.

Session Lifecycle

The following sequence diagram details the interactions that occur when a user initiates a Ghostbird session.

Commands and Shortcuts

Ghostbird defines several commands that can be triggered via keyboard shortcuts. You can customize these in Thunderbird's settings.

Command	Default Shortcut	Description
start_ghostbird	Ctrl+Shift+H	Starts the Ghostbird session, connecting to the GhostText server.
stop_ghostbird	(none)	Stops the current Ghostbird session.
toggle_ghostbird	(none)	Toggles the Ghostbird session on or off.
open_options	(none)	Opens the Ghostbird add-on options page.

Sources: manifest_template.json:43-58

Troubleshooting

Connection Issues

If the Ghostbird button turns red, it indicates a connection failure. The most common cause is that the GhostText server is not running in your text editor.

• Verify that you have started the GhostText server in your editor.
• Check that no other application is using the GhostText port (default: 4001).
• Consult the troubleshooting page for the original GhostText for more detailed guidance.

Sources: README.md:63, doc/faq.md:25-26

HTML vs. Plain Text Mode

Ghostbird edits the content of the compose window as-is. The editing mode (HTML or Plain Text) is determined by your Thunderbird account settings and cannot be changed mid-composition.

To set your preferred format:

1. Go to Account Settings > Composition & Addressing.
2. Check or uncheck the Compose messages in HTML format checkbox.
3. This setting applies to new messages created after the change.

Sources: doc/faq.md:31-48