Skip to content

Mod API reference

Start with JavaScript mods to create a working panel.

Replace a built-in

Use its existing ID to inherit its host and defaults:

[mods.agents]
entry = "./mods/my-agents/main.js"
title = "My Agents"

Bundled IDs include sessions, agents, pane-status, resource-monitor, status-line, pane-strip, tab-menu, command-line, pane-header, and touch-controls. See crates/client-config/defaults/mods.toml for defaults. A built-in override must preserve its host contract.

Choose a host

host Presentation Notes
panel Dockable or floating window place, sides, size, title
bar Titleless top/bottom strip Cannot float or fold
pane One strip per pane Receives {window, pane}; presses pass through
embedded Existing native presenter's content Preserve its props and hit IDs; arbitrary new mounting points are unsupported

New IDs need both entry and host. IDs use letters, digits, _, and -.

Setting Effect
enabled = false Disable the mod
open Initial visibility; saved state wins
place, sides Initial and allowed dock sides; none floats
after Order after another mod on the same side
props Script options; host context overrides conflicting keys

Panels save their placement and folded state. Click the title to fold or unfold; drag it to move or dock. Desktop floating panels use native windows; Android embeds them.

Elements and interaction

Need API
Layout and content div, h_flex, v_flex, svg, image
Styling gap, px, h, rounded, bg, text_color, hover
Interaction id, tooltip, on_click, on_mouse_down, on_mouse_move
Scrolling overflow_y_scrollbar(); modes always, hover, scrolling
Animation .spin(900), .frames(["⠋", "⠙"], 90)

SVG icons inherit text color; use image(path) for original-color artwork. Text input, keyboard focus, popovers, retained child views, and text selection are not available.

Runtime state

Never retain cx across callbacks. Use cx.timer.every(ms, callback) and cx.timer.cancel(id) for timers. localStorage persists per mod copy; shared and setShared exchange state between mods.

App data and actions

Read sessions(), agents(), panes(), focused(), resources(), session(), effects(), window(), or live(key) from graffitty. pane() is available only in a pane host. Data belongs to the hosting window.

Call run(action, args) with the same PascalCase actions used by menus and bindings:

run("OpenPanel", { name: "builds" });
run("ToggleEffect", { effect: "camera.tilt" });

The generated declarations list data types and supported actions. They are written on startup to ~/.local/share/graffitty/mods/graffitty.d.ts, or the platform equivalent. Point your editor's jsconfig.json at that file.

Unavailable APIs

exec, hc, file access, and watchFolder reject calls. Overlay and notification helpers are not routed yet.

Backgrounds

[mods.agents]
background_opacity = 0.8
background_blur = true
background_blur_radius = 12

Leave the root background unpainted to show the panel surface. Opacity is 0–1; blur radius is 0–64 logical pixels. Embedded panels cannot blur other embedded windows. Native floating blur also depends on the user's window settings and compositor support.

The UI model uses Apache-2.0 work from herdr-app and gpui-kit; see their notices under licenses/.