Writing a module

A module is one block you can drop into your bento. It is a folder on your machine.

blockodile ships with three built-in modules (Terminal, Shell command and the first-run Welcome guide); everything else is a folder.

Where modules live

~/.config/blockodile/modules/
  btop/
    module.json
  hello/
    module.json
    index.html

One folder per module. The folder name is the module id. blockodile watches the folder, so a new module or an edit shows up in about a second, no restart needed.

Two kinds

Command modules

Any CLI or TUI in a fresh login shell. No API to learn.

Web modules

One HTML file in a sandboxed iframe, plus the blockodile SDK.

module.json

The manifest every folder needs: id, name, kind, size.

SDK

window.blockodile: files, shell, cwd, agent status.

Zip the folder and share it; the user unzips it into ~/.config/blockodile/modules/. That is the whole install. To list it in the library, open a PR to blockodile-modules adding modules/<id>/, with description and author in module.json: the card is built from them.

Checklist before publishing

id equals the folder name
kind is command or web
web: single HTML file, no relative assets
w/h set so the block looks right on first add
found the module in the command palette (⌘K → Add <name>)