mod.json reference

Every mod folder holds a mod.json file. It names the mod, says how to start its program, and declares everything the mod may hear, draw and ask for. Syntic Code checks it strictly: an unknown key, event, slot or permission makes the whole file invalid, and the mod is listed as [broken].

Complete example

{
  "name": "review-queue",
  "version": "1.3.0",
  "description": "Pane with the pull requests waiting for your review",
  "command": ["python3", "main.py", "--max", "8"],
  "events": ["session.start", "turn.end"],
  "ui": ["pane", "status"],
  "permissions": ["session.read"]
}

Fields

No other keys are allowed.

name

• 1 to 40 characters.
• Only lowercase ASCII letters, digits and -.
• Must not start with -.
• Must be exactly the same as the mod’s folder name under ~/.syntic/mods/.

Valid: turn-clock, pr2, build-status. Not valid: Turn-Clock, -clock, my_mod, ../x.

version and description

Plain strings for people. Syntic Code does not compare versions; it does not update mods.

command

How to start the mod’s program. Either one string (the program, no arguments):

"command": "./run"

or an array of the program followed by its arguments:

"command": ["sh", "run.sh"]

Arguments are passed as given; there is no shell, so quotes, * and $VAR are not expanded. The program must not be empty.

The first entry is resolved like this:

The program is checked when you run syntic mod enable, and again each time a session starts it. It always runs with the mod folder as its working folder.

events

The events the mod may receive. Allowed values:

Duplicates are dropped. At run time a mod can narrow this list with a subscribe message, but never extend it. Details and payloads are on the Events page.

ui

The slots the mod may draw in. Allowed values:

Duplicates are dropped. Drawing into a slot not listed here is refused and counts as a bad line. See Screen areas.

permissions

The API permissions the mod asks for. Allowed values:

Duplicates are dropped. Asking is not the same as having: the user grants these when they run syntic mod enable. The hello message’s granted list says what the mod actually has. See Mod API.

Where things live

When SYNTIC_CONFIG_DIR is set to an absolute path, all of these live under that folder instead of ~/.syntic.

The state file looks like this. Do not edit it by hand; use the commands.

{
  "mods": {
    "turn-clock": { "enabled": true, "granted": ["notes"] }
  }
}

syntic mod commands

enable and disable exit with code 1 on failure. All three take effect from the next interactive session.

Environment variables

Limits at a glance