Mods

A mod is a small program that runs next to your interactive session and adds a piece of interface: a short item in the footer, a band of one or two rows above the prompt, or a little titled box beside the conversation. Mods can react to session events, post a short note, and read a summary of the session if you let them.

Think of a turn timer in the footer, a build-status band, or a pane listing your open pull requests.

A mod cannot run Syntic Code’s tools, send anything to the model, or change permissions. Mods do not start in -p runs.

Mods and plugins

If you want to change what the agent does, look at plugins or hooks. If you want to see something extra while you work, a mod is the lighter tool.

Install and switch on

Mods live only in your own config folder: ~/.syntic/mods/<name>/. Copy a mod’s folder there, then:

syntic mod list              # what is installed, on or off, and what each may do
syntic mod enable turn-clock # switch on and grant what its manifest asks for
syntic mod disable turn-clock

A mod is off until you enable it. enable lists the permissions it asks for and grants exactly those. If an update asks for more, syntic mod list tells you, and the extra stays off until you enable it again. Changes apply from the next session.

A project can never install or switch on a mod, so cloning a repository cannot add one. SYNTIC_DISABLE_MODS=1 keeps every mod off for a run.

How mods run

A mod is a folder with a mod.json and a program:

{
  "name": "turn-clock",
  "version": "0.1.0",
  "description": "Shows how long each turn took",
  "command": ["sh", "run.sh"],
  "events": ["turn.start", "turn.end"],
  "ui": ["status", "pane"],
  "permissions": ["notes"]
}

Each interactive session starts every enabled mod once, in its own folder, with a minimal environment. Syntic Code and the mod then exchange one JSON object per line: the session sends hello, events and bye; the mod sends draw, subscribe and call. Syntic Code never waits for a mod. If one falls behind, its events are dropped; if it exits or misbehaves, it is stopped, its display is cleared and one line in the conversation says so.

Learn more