PluginsModsScreen areas

Screen areas

A mod draws into fixed places in the interactive screen called slots. There are three: a short item in the footer, a band just above the prompt, and a small titled box at the right of the conversation. A mod may only draw into the slots its mod.json lists in ui.

Syntic Code owns the layout. A mod never positions text, picks colors or moves the cursor. It sends plain text, and Syntic Code cleans it, cuts it to size and places it.

The three slots

SlotWhereLimitsGood for
statusThe footer line, after the session summary1 line, 40 charactersA short state: a timer, a branch, a count
bandThe last rows of the conversation area, right above the prompt2 rows, 200 characters eachA one-line alert or a status you want close to where you type
paneA box down the right side of the conversation area12 rows of 60 characters, title up to 30 charactersA short list: recent turns, open reviews, build steps

Footer (status)

Each mod’s footer item appears after the built-in session summary, separated by a dim dot. Items from several mods appear side by side, ordered by mod name. The text is drawn in a muted color so it does not compete with the summary.

{"type":"draw","slot":"status","text":"build green"}

If you send lines instead of text, only the first line is used.

Band (band)

A band takes rows from the bottom of the conversation area, so it sits directly above the prompt. Each row starts with a small colored bar. Send one string with a newline, or a lines array:

{"type":"draw","slot":"band","lines":["deploy to staging running","step 3 of 5"]}

Rows past the second are dropped. Bands from all mods share the space, and Syntic Code always keeps at least six rows for the conversation. In a short terminal, some band rows may not be shown.

Side pane (pane)

A pane is a bordered box with a bold title. Panes stack from the top of a column on the right side of the conversation area.

{"type":"draw","slot":"pane","title":"Open reviews","lines":["#412 fix login","#409 docs: hooks","#401 bump deps"]}
  • Without title, the mod’s name is used.
  • The column is only shown when the conversation area is at least 90 columns wide. In a narrower terminal, panes are hidden (the mod keeps running and can still draw elsewhere).
  • The column is as wide as the widest pane line plus a little padding, never less than 16 columns and never more than a third of the area.
  • If several mods draw panes, they stack in mod-name order. A pane that would get fewer than three rows of height is not drawn.

Draw, update and clear

Every draw replaces what that mod last drew in that slot. There is no partial update; send the whole content each time.

To clear a slot, send a draw with no text and no lines, or with empty text:

{"type":"draw","slot":"band"}

When a mod stops, exits or is stopped, everything it drew is cleared at once.

What happens to your text

Every string a mod sends is cleaned before it is stored:

StepEffect
Control characters removedNewlines inside a row, carriage returns and the escape character are dropped. An escape sequence like \u001b[31m loses its escape byte, so the rest shows as plain text.
Text-direction overrides removedCharacters that reverse or isolate text direction are dropped, so text cannot be disguised.
Tabs become spacesEach tab turns into one space.
Trailing spaces trimmedWhitespace at the end of a row is removed.
Cut to sizeText longer than the slot’s limit is cut and ends with an ellipsis (…).

Limits count characters, not bytes, so non-Latin text and symbols get the same room as ASCII.

Because colors and escape codes are stripped, a mod cannot recolor the screen, hide text or fake a permission prompt. Use words and symbols, not styling, to make your item stand out.

Drawing into a slot you did not declare

If a mod sends draw for a slot that is not in its manifest’s ui list, or for a slot name that does not exist, nothing is drawn and the line counts as a bad line. More than 20 bad lines and the mod is stopped for the session. Add the slot to ui in mod.json if you need it. Adding a slot does not need a new grant, but it only takes effect from the next session.

Design tips

  • Keep the footer item tiny. 40 characters is the cap, but shorter is better. The footer is shared with the session summary and other mods.
  • Use the band sparingly. It takes rows from the conversation. Clear it when there is nothing to say.
  • Make panes optional. Many people work in terminals under 90 columns. Make sure the mod is still useful when its pane is hidden.
  • Do not redraw on a fast timer. There is no frame limit, but each draw replaces state the screen reads every frame. Draw when something changes.

Next steps

Make a modEvents