Roam Research Docs · Developer documentation

Roam Depot/Extension API

markdown version · view in Roam Research

• Extension lifecycle
  • Your extension.js must default-export an object with onload and onunload functions
  • onload({extensionAPI, extension}) runs when the extension is enabled, and again on every app load while it stays enabled
    • extensionAPI — the API documented on this page, scoped to your extension; it is only passed here, not available on window
    • extension.version (string) — the installed version of your extension
    • onload may return a cleanup function — it is called at unload, right before onunload
    • an async onload works too — Roam awaits a returned Promise (logging any error), and if it resolves to a function, that function is the cleanup
  • onunload() runs when the extension is disabled, uninstalled, updated, or reloaded
  • If your extension ships an extension.css, it is injected automatically on load and removed on unload
  • What Roam cleans up automatically on unload (no code needed in onunload):
    • commands added via extensionAPI.ui.commandPalette and extensionAPI.ui.slashCommand
    • AI tools added via extensionAPI.ai #experimental
    • the settings panel
    • your extension.css
    • everything else — DOM elements, event listeners, intervals — is your responsibility in onunload
  • Example::

    • export default {
        onload: ({ extensionAPI, extension }) => {
          console.log("loading version", extension.version);
          extensionAPI.ui.commandPalette.addCommand({
            label: "My Extension: Say hi",
            callback: () => console.log("hi")});
          // optionally return a cleanup function;
          // it runs at unload, right before onunload
        },
        onunload: () => {
          // undo anything not covered by automatic cleanup
          // (DOM nodes, event listeners, intervals, ...)
        }
      };

• Reference
  • extensionAPI.settings
    • Description::
      • Persistent key-value storage scoped to your extension — keys cannot collide with other extensions
      • values are saved with the graph and sync across the user's devices
      • setting keys must be non-empty strings and cannot contain ".", "#", "$", "[", or "]"
    • extensionAPI.settings.canSet (boolean) — false when the extension was installed "for everyone" by the graph admin and the current user is not an admin; then set only logs a warning and changes nothing
    • extensionAPI.settings.get
      • Description::
        • Returns the saved value for a setting key
      • Parameters::
        • key (string, required) — the setting to read
      • Return::
        • the saved value, or null if never set
      • Example::

        • extensionAPI.settings.get("api-key")
          // => "sk-abc123"

    • extensionAPI.settings.set
      • Description::
        • Saves a value for a key
      • Parameters::
        • key (string, required) — non-empty, cannot contain ".", "#", "$", "[", or "]"
        • value (required) — any JSON-serializable value
      • Return::
        • Promise resolving to null
        • rejects if key is invalid; if the user cannot write settings (canSet is false), it only logs a warning
      • Example::

        • await extensionAPI.settings.set("threshold", 5)
          // => null

    • extensionAPI.settings.getAll
      • Description::
        • Returns all of the extension's saved settings
      • Return::
        • an object of key → value, or null if nothing has been saved yet
      • Example::

        • extensionAPI.settings.getAll()
          // =>
          // {"api-key": "sk-abc123",
          //  "threshold": 5,
          //  "sync-enabled": true}

    • extensionAPI.settings.panel.create
      • Description::
        • Creates a settings tab for your extension in the Settings dialog
        • calling it again replaces the panel
        • switch, input, and select rows save their state automatically under the row's id — read it back with extensionAPI.settings.get; button and reactComponent rows save nothing themselves
      • Parameters::
        • config (map, required)
          • tabTitle (string) — the title of your extension's tab in Settings
          • settings (array of maps) — one entry per settings row:
            • id (string, required) — the storage key for the row; non-empty, cannot contain ".", "#", "$", "[", or "]"
            • name (string | React element) — the row's title
            • description (string | React element, optional) — shown under the name
            • className (string, optional) — extra CSS class on the row
            • action (map, required) — the control, one of:
              • {type: "switch", onChange} — a toggle; saved on change; onChange (optional) receives the DOM event
              • {type: "input", placeholder, onChange} — a text field; saved on blur; onChange (optional) fires on each keystroke with the event
              • {type: "select", items, onChange} — a dropdown; items is an array of strings; saved on selection; onChange (optional) receives the selected item
              • {type: "button", content, onClick, class} — a button; content is the label, onClick (optional) the click handler, class (optional) replaces the default button styling
              • {type: "reactComponent", component} — renders your React component; manage state yourself with extensionAPI.settings.set/get
      • Return::
        • Promise resolving to null
        • rejects if any setting id is invalid
      • Example::

        • await extensionAPI.settings.panel.create({
            tabTitle: "My Extension",
            settings: [
              {id:          "sync-enabled",
               name:        "Sync",
               description: "Sync data automatically",
               action:      {type:     "switch",
                             onChange: (evt) => console.log("switch:", evt.target.checked)}},
              {id:     "api-key",
               name:   "API key",
               action: {type:        "input",
                        placeholder: "paste your key",
                        onChange:    (evt) => console.log("typing:", evt.target.value)}},
              {id:     "mode",
               name:   "Mode",
               action: {type:     "select",
                        items:    ["fast", "thorough"],
                        onChange: (item) => console.log("selected:", item)}},
              {id:     "reset",
               name:   "Reset",
               action: {type:    "button",
                        content: "Reset all data",
                        onClick: () => console.log("clicked")}}
            ]
          })
          // => null

  • extensionAPI.ui
    • extensionAPI.ui.commandPalette.addCommand
      • Description::
        • Add a command to the Command Palette (cmd-p) — same as roamAlphaAPI.ui.commandPalette.addCommand, but tied to your extension:
          • commands are grouped under your extension (for example in the Hotkeys window)
          • the label is namespaced by your extension, so it cannot collide with other extensions' commands
        • Calling again with the same label updates the existing command
      • Parameters::
        • label (string, required) — text shown in the Command Palette
        • callback (function, required) — called with no arguments when the user runs the command
        • disable-hotkey (boolean, optional) — don't allow a hotkey for this command
        • default-hotkey (string | array of strings, optional) — most commands should NOT set this; without it, users can still assign their own hotkey in Settings → Hotkeys
          • a hotkey string looks like "defmod-shift-h" — at least one modifier (shift, ctrl, alt, super, or defmod — the OS default modifier) plus a key; an array of strings (max 5) defines a multi-step hotkey
      • Return::
        • Promise resolving to null
      • Example::

        • await extensionAPI.ui.commandPalette.addCommand({
            label: "My Extension: Do the thing",
            callback: () => console.log("doing the thing")})
          // => null

    • extensionAPI.ui.commandPalette.removeCommand
      • Description::
        • Remove a command your extension added — same as roamAlphaAPI.ui.commandPalette.removeCommand
      • Parameters::
        • label (string, required) — the label the command was added with
      • Return::
        • Promise resolving to null
      • Example::

        • await extensionAPI.ui.commandPalette.removeCommand(
            {label: "My Extension: Do the thing"})
          // => null

    • extensionAPI.ui.slashCommand.addCommand
      • Description::
        • Add a command to the / slash menu — same as roamAlphaAPI.ui.slashCommand.addCommand, but tied to your extension:
          • the label is namespaced by your extension, so it cannot collide with other extensions' commands
        • Calling again with the same label updates the existing command
      • Parameters::
        • label (string, required) — text shown in the slash menu
        • callback (function, required)
          • called with a context object when the user selects the command

            • {"block-uid": "YnatnbZzF",
               "window-id": "BBG4fFwolaVlT5FZQdzAI7P40aB3-body-outline-04-15-2021",
               indexes: [1, 10]}

          • return a string to insert at the cursor, or null to handle insertion yourself (the typed search string is not removed)
        • display-conditional (function, optional) — called with the context object (without indexes); return true to show the command
      • Return::
        • null
      • Example::

        • extensionAPI.ui.slashCommand.addCommand({
            label: "Insert Greeting",
            callback: (context) => "Hello from my extension! 👋"})
          // => null

    • extensionAPI.ui.slashCommand.removeCommand
      • Description::
        • Remove a slash command your extension added — same as roamAlphaAPI.ui.slashCommand.removeCommand
      • Parameters::
        • label (string, required) — the label the command was added with
      • Return::
        • null
      • Example::

        • extensionAPI.ui.slashCommand.removeCommand(
            {label: "Insert Greeting"})
          // => null

  • extensionAPI.ai
    • extensionAPI.ai.addTool #experimental
      • Description::
        • Register an AI tool — same as roamAlphaAPI.ai.addTool #experimental, but tied to your extension:
          • Agents see it namespaced — its callable id is "<extension-id>/<name>" and it is advertised with your extension's display name.
          • Removed automatically on unload — no cleanup code needed.
          • The 25-tool cap applies per extension.
        • Calling again with the same name updates the existing tool instead of adding a second one.
        • Throws synchronously on invalid input.
      • Parameters::
        • name (string, required) — the tool's name; up to 64 characters from A-Za-z0-9_-
        • description (string, required) — tells the agent what the tool does and when to use it; up to 2000 characters
        • handler (function, required)
          • Called with two arguments — the agent's args as a plain object, and a context object (below); returns a JSON-serializable value or a Promise resolving to one
          • The return value is what the agent reads. We do add some more metadata such as the graph name and queried time. Shape it for reading (a small object or a plain sentence).
          • Throwing (or rejecting) fails the agent's call with the error message, attributed to this tool.
          • context.tokenUserUid (string) — uid of the AI user the call came from; absent when the tool is invoked directly from JS
            • Pass it as the write APIs' user-uid argument (e.g. block: {..., "user-uid": context.tokenUserUid}) to attribute writes to the AI — including writes made after the handler's first await.
          • context.asTokenUser(fn) — runs fn with the graph writes it issues attributed to the calling AI, with the AI's token scopes in effect
            • The callback must issue its writes synchronously — never pass an async function; await the returned value outside instead.
            • Otherwise, graph writes made after the handler's first await are attributed to the logged-in user, not the AI.
        • scope (string, optional, default "edit") — "read" | "append" | "edit"
          • The access an agent's connection needs to call this tool
          • Declare the least scope the tool needs; a read-only AI connection can only call "read" tools.
        • inputSchema (object, optional)
          • draft-07 JSON Schema describing handler's args
          • $schema, if present, must be the draft-07 URI — schemas are always validated as draft-07.
          • type, if present, must be "object" — a tool's args are always a plain object.
          • Validated against the JSON Schema meta-schema at registration; invalid schemas throw.
          • When present, agents' args are validated against it before handler runs; when absent, args reach the handler unvalidated.
          • Must serialize to at most 4000 characters.
      • Return::
        • null
      • Example::

        • extensionAPI.ai.addTool({
            name: "word-count",
            description: "Counts words in a block's text.",
            scope: "read",
            inputSchema: {
              type: "object",
              properties: {uid: {type: "string", description: "The block's uid"}},
              required: ["uid"]
            },
            handler: ({uid}) => {
              const s = window.roamAlphaAPI.pull("[:block/string]", [":block/uid", uid])[":block/string"] || "";
              return {words: s.trim() ? s.trim().split(/\s+/).length : 0};
            }
          }) // => null

    • extensionAPI.ai.removeTool #experimental
      • Description::
        • Remove a tool your extension added — same as roamAlphaAPI.ai.removeTool #experimental
      • Parameters::
        • name (string, required) — the name the tool was added with
      • Return::
        • null
      • Example::

        • extensionAPI.ai.removeTool({name: "word-count"}) // => null