Development Mode

During development, you don’t need to build a .forkbit archive every time you change your plugin. ForkBit can load plugins directly from a local directory — even in the released DMG version.

Setting up dev mode

1. Open ForkBit and go to Settings → Plugins

2. Scroll down to the Development section

3. Click “Add Path…” and select your plugin directory (the folder containing plugin.json)

4. ForkBit validates that the directory has a valid manifest

Your plugin now appears in the Add Plugin dialog with a (dev) label next to its name. Add it to any project like a normal plugin.

Note

Changes to your plugin code take effect after restarting the plugin or the app. There is no hot-reload — you need to restart to pick up code changes.

Recommended project setup

Create a dedicated directory with its own virtual environment:

mkdir my-plugin && cd my-plugin
python3 -m venv .venv
source .venv/bin/activate
pip install forkbit-sdk

Scaffold the plugin:

forkbit plugin init --id com.mycompany.myplugin --name "My Plugin" --non-interactive .

Your directory should look like this:

my-plugin/
  .venv/              — virtual environment with forkbit-sdk
  plugin.json         — manifest
  main.py             — your plugin code
  settings.json       — settings schema

Now register the path in ForkBit (Settings → Plugins → Development → Add Path), and you can iterate without building.

Multiple files

Plugins can have multiple Python files. The entry point in plugin.json is the file that contains your BasePlugin subclass, but you can import from sibling modules freely:

my-plugin/
  plugin.json
  main.py             — entry point (BasePlugin subclass)
  workers.py           — background threads
  widgets.py           — custom widgets

# main.py
from workers import MyWorker
from widgets import MyCard

These imports work because the plugin directory is added to sys.path at load time.

Accessing app internals

Dev plugins run in-process and can import from the app’s modules:

# Access the app's theme system
from ui.theme import icon, ToggleSwitch, XL, L, S

# Access the app's shared widget kits
from core.translation_kit import TranslatableField, LocalePicker
from core.price_kit import CurrencyInput, PriceTable

These imports are available because the app adds its own root to sys.path. They work in both dev mode and when the plugin is built as a .forkbit file.

Warning

Imports from ui.* and core.* are app internals and may change between ForkBit versions. Only forkbit_sdk is a stable public API.

When to build

Use dev mode for development and testing. Build a .forkbit file when you’re ready to distribute:

forkbit plugin validate .
forkbit plugin build .          # current platform only
forkbit plugin release .        # all platforms

See Building & Distributing for details on building and distributing.