These are the docs of plugin API 1.7, as Textus 1.4.3 had them. API 1.8 is the newest.

Writing a plugin

A Textus plugin is a folder: a manifest, textus-plugin.json, and its JavaScript. Its code runs in a sandboxed frame that reaches nothing of the app or your files except through textus, the plugin API, and every call is checked against the permissions the user granted. What a plugin shows it shows in lists and dialogs Textus draws, or in webviews - frames of its own HTML - as VS Code's extensions do.

This page goes from a first plugin to a published one:

  1. Getting started - a plugin that runs, in five minutes.
  2. The guide - the manifest, permissions, and the API by what you want to do.
  3. The reference - every call, generated from textus.d.ts, the one source of truth for the API.
  4. Publishing - your plugin in its own repository, and listed in Textus.

No plugin comes with Textus. The official ones live in CatVinci-Studio/textus-plugins and are the best examples: Tasks is a sidebar list over the folder, the PDF Viewer a file editor, Zotero a hover card and a completion, Vim a way of typing.

Getting started

  1. Start from an example in textus-plugins' examples/: hello (a command and a sidebar list), page (a sidebar page of its own), code-block or ai-tool. In a clone of that repository, node packages/create-textus-plugin/index.mjs my-plugin --from page --id jane.my-plugin copies one with your id; node packages/textus-plugin/cli.mjs check my-plugin says what Textus would refuse or ignore in it. packages/textus-plugin also has the API's types and a stand-in Textus for unit tests (test.mjs); see Testing.
  2. In Textus, Settings › Extensions › Plugins, the More (…) menu › Load a plugin folder…, and choose the folder. It is listed under Installed, marked development; turn it on.
  3. Change host.js and save: a folder you loaded is read again as it changes. Its page in Settings shows what it logged (ctx.log).

Or ask Textus AI: "a plugin that …" in Create mode writes one you can install from the reply and change in the next message.

A script: a plugin in one file

For something small, skip the folder and the manifest: put a .js file in the scripts folder (the same More menu › Open Scripts Folder, in the global config folder), with what a manifest would say in a comment at its top:

// ==TextusScript==
// @name        Word Count
// @description Counts the words of the document in front.
// @permission  editor.read
// @command     count Count Words
// ==/TextusScript==
exports.activate = function () {
  textus.commands.register("local.word-count.count", async function () {
    const text = (await textus.editor.getText()) ?? "";
    textus.ui.notice(`${text.split(/\s+/).filter(Boolean).length} words`);
  });
};

Its id is local.<file name> unless @id gives one; `@command <name>

<title>` adds `<id>.<name>`; `@permission` and `@command` can repeat. A script is listed under **Made by you**, starts off, asks for its permissions like any plugin, runs once Textus has started, and is read again when it changes. Uninstalling it moves the file to the Trash.

The manifest

{
  "id": "jane.word-count", // publisher.name, lowercase and dashes
  "name": "%name%", // a %key% is looked up in l10n
  "version": "0.1.0",
  "publisher": "jane",
  "author": "Jane Doe", // on its card; the publisher where there is none
  "description": "%description%",
  "icon": "icon.svg",
  "license": "MIT",
  "repository": "https://github.com/jane/textus-word-count",
  "engines": { "textus": ">=1.3.0-beta.2" }, // the plugin API 1.0
  "main": "host.js", // or ["shared.js", "host.js"], run in order
  "platforms": ["desktop", "ios"], // where it runs; the catalog needs it
  "activationEvents": [], // when to start before it is used (below)
  "permissions": ["editor.read"],
  // "background": "jobs.js", // scheduled jobs' code (On a schedule)
  // "requires": [{ "setting": "runInBackground", "reason": "%why%" }],
  "contributes": {
    "commands": [{ "command": "jane.word-count.count", "title": "%count%" }],
    "keybindings": [{ "command": "jane.word-count.count", "key": "mod+alt+w" }],
    "menus": {
      "editor/context": [
        { "command": "jane.word-count.count", "when": "editorHasSelection" },
      ],
      "app/plugins": [{ "command": "jane.word-count.count" }],
    },
  },
  "l10n": {
    "en": { "name": "Word Count", "description": "…", "count": "Count Words" },
    "zh": { "name": "字数", "description": "…", "count": "统计字数" },
  },
}

When it starts

A plugin costs nothing until it is needed. Textus reads its manifest and puts its commands, menus and tabs in place; its code starts the first time one of them is used - its command run, its tab opened, its code block in sight, a textus:// link for it. activationEvents starts it earlier:

Event Starts it
onStartupFinished once the window is idle (for a status item, a background watch)
onEditor once a document is open, when the window is idle (decorations)
onHover when the pointer first rests on a link (a plugin of hover cards)

What a plugin draws loads lazily too: lists, webviews and code blocks are made when they are first shown.

What contributes takes

Key What it adds
commands Commands: { command, title }; with runs: { command: "textus.…", args } one runs a Textus command with those arguments, no code needed.
keybindings A shortcut for a command, as Settings writes them (mod+alt+w). Textus's own shortcuts win a clash; the user can change or clear it in Settings › Shortcuts.
menus editor/context (the editor's right-click menu), editor/slash (offered when a word starts with /), file/context (a file's in the sidebar), tab/context (a tab's), view/title (buttons at the top of a sidebar view, with an icon), floating/context (a floating view's right-click menu, first in it; when: "view == …" picks the view), app/plugins (the Plugins menu), app/tray (background mode's icon).
sidebarTabs { id, title, type: "list" | "webview", icon }: a sidebar tab. A list is drawn by Textus from views.registerList; a webview is the plugin's page. The icon is an SVG drawn in the text colour.
views { id, title, type }: the same, opened in a tab of its own (textus.layout.openView).
customEditors { viewType, displayName, filenamePatterns: ["*.pdf"], frontMatter: ["kanban-plugin"], priority }: a file type opened in the plugin's tab instead of as a document. frontMatter (from 1.3.10) claims Markdown documents whose front matter has one of the keys; filenamePatterns may then be left out.
documentTypes { extensions: ["qmd"], keep: { blockStarts: [":::"], braces: true, jsx: false } }: a file type opened as a document in Textus's own editor. keep names what of its syntax is shown as source and saved exactly as written: paragraphs starting with one of blockStarts (with the blocks after while a bracket is open), {…} with braces, JSX tags with jsx. Turned off, the plugin's files open read-only as text. Textus's own types (md, markdown, mdx, txt, text) can't be taken. From 1.4.3.
codeBlocks { language, title, frame, size }: fenced blocks in that language drawn by the plugin (views.registerCodeBlock), in a box like a figure, or on the page with frame: "none". With size: "interface" the block draws at the interface's text size instead of the document's and its zoom, for an overview (a table, a board) that shows more as the column widens. Textus's own languages (mermaid, math…) can't be taken.
suggestFor ["wikilinks"]: what a document can hold that the plugin works with. An official one is suggested, once, for a document that holds it while no installed plugin does.
completions { id, where: "math" | "text" | "any", pattern, title }: completions as you type when what is before the caret matches pattern (editor.registerCompletion), grouped under title in the / panel. Needs editor.read.
aiTools { name, description, parameters }: tools Textus AI can call (ai.registerTool); parameters is a JSON schema.
embeds { id, targets: ["note", "heading", "block"] }: ![[…]] embeds of those kinds drawn read-only from the Markdown views.registerEmbed(id) gives. Needs files.read (or files.write).
hovers ["document", "link", "citation"]: the hover cards the plugin gives (editor.registerHover). One plugin answers each kind: the first turned on.
links { pattern, command }: web links Ctrl/Cmd+clicked in a document whose URL matches pattern run command with the URL.
statusItems { id, text, tooltip?, command? }: statuses in the window bar shown while the plugin is on, before its code starts; its ui.statusItem(id, …) takes one over.
settings Rows on the plugin's page in Settings, drawn as Textus's own: { key, type, default, title, description?, group?, when? }. See Settings of every kind.
settingsPage { title }: a page of the plugin's own under its settings, a webview.
floatingViews { id, title, width, height, place }: a small transparent page that floats over the desktop or in Textus's window (place: "either", "desktop", "window"), shown with layout.openFloating. It opens in the window unless place is "desktop". Its page is looked at, not clicked: the user drags it anywhere, resizes it in proportion from its top corner (0.6× to 1.4×, so lay the page out to its viewport) and folds, closes or moves it from its right-click menu. side in its state says which half it sits in. From 1.3.6.
agents { id, name, command, args, env, setup, provider }: an AI agent on the user's computer that speaks the Agent Client Protocol on stdio (Claude Agent, Codex, Gemini CLI…), offered in Textus AI's model menu under Agents. Textus starts command itself, found on the PATH a terminal would have; {pluginDir} in args and env is the plugin's folder; setup says how to install it and sign in, shown when it can't start; provider names whose models it runs ("anthropic", "openai"), what ai.onDidChangeState tells other plugins while it works. Needs agents; desktop only. From 1.3.13.

A menu item's when is a small expression over the moment it is shown: documentOpen, folderOpen, editorHasSelection, fileExtension == .pdf, resourceFilename == notes.md, resourcePath, view == jane.tasks.list, isMac, resourceIsFolder (a file menu item opened on a folder, from 1.4.1), and from 1.6 the plugin's own keys set with textus.commands.setContext("jane.focus.on", true); joined with &&, || and !.

Permissions

A plugin asks for these in permissions; the user grants them when turning it on, or leaves it off, and can take each back later.

Permission Lets the plugin
editor.read read the document in front: its text, selection, blocks and outline; also completions
editor.write change it at once, each change one undo step
editor.propose suggest changes to it, shown as Textus AI's are, accepted or rejected by the user
editor.input take the editor's keys and move, select and edit with them (Vim, Emacs)
files.read list, find and read files in the open folder, and what Textus knows of them (metadata)
files.write create, change, rename and trash files in the open folder (reading them comes with it)
clipboard read and write the clipboard
project.data keep its own data in the open folder, in .textus/plugins/<id>/
ai.tools give Textus AI tools to call
notifications show system notifications, at once or on a schedule (API 1.1)
background run its background code on a schedule, also with every window closed (API 1.1)
agents run the AI agents it names in contributes.agents (programs on this computer; 1.3.13)
appearance change Textus's colours: a palette over the theme, the frame a gradient (API 1.6)
git.commit commit files of the open folder with the user's git (1.4.3; reading Git history is files.read)
network:<host> fetch from that host over HTTPS (*.example.com, host:port, * for the open web)
hidden:<path> read that hidden file of the open folder, named from its top: hidden:.vitepress/config.ts (1.4.3)

Ask for what the plugin's purpose explains, and no more: each permission is shown to the user, and a listing in Textus asks why for the broad ones. Files are reached only inside the open folder, never the app's own; plain HTTP goes only to this computer (network:localhost:23119). Files and folders whose names start with "." are shut to plugins but for .textus, Obsidian's shared settings, .gitignore, .git/HEAD and those a plugin names with hidden:, read only; .git, .env, .ssh, keys and other plugins' storage can't be named.

The code

host.js runs as a CommonJS module with textus in scope. Put /// <reference path="textus.d.ts" /> at its top (copy textus.d.ts beside it) and your editor completes every call.

exports.activate = function (ctx) {
  ctx.subscriptions.push(
    textus.commands.register("jane.word-count.count", async () => {
      const selection = await textus.editor.getSelection();
      if (!selection?.text) return textus.ui.message(textus.l10n.t("nothing"));
      const words = selection.text.split(/\s+/).filter(Boolean).length;
      await textus.ui.notice(textus.l10n.t("words", words));
    }),
  );
};

The rest of this section goes by what you want to do. The reference has every call and type.

Commands and dialogs - commands, ui

commands.register(id, run) for a command of the manifest's; commands.execute(id, ...args) runs a command - Textus's own (textus.save, textus.closeTab with { save: true }), yours, or one another plugin lists in its manifest, with the permission commands:<that plugin's id>. textus.offerPlugin with { id } suggests an official plugin that works well with yours - the user decides, and it resolves whether that plugin is on (best from something the user does; never await it in activate, which has 10 seconds). ui draws Textus's own dialogs: message, notice (a note that goes by itself), confirm, input, pick (one or several of a list), form (a few fields at once), withProgress (a bar with Cancel) and statusItem (a short status in the window bar that runs a command when clicked; one declared in contributes.statusItems shows without starting the plugin).

The document in front - editor

What a plugin shows - views

Tabs and panes - layout

open(path or location, { where }) opens a file - where: "beside" in the pane beside the one in front, splitting the window if it isn't - openView(id), showSidebarTab(id) (opens the sidebar on a tab: a plugin's sidebar tab id, tree or outline; from 1.3.10), openWebPage(url), openUntitled(text) and openExternal(url). tabs(), activeTab() and split() say what is open; onDidChangeActiveTab and onDidChangeLayout follow it.

The folder - files, metadata

Data, secrets and settings

Settings of every kind

type Drawn as default Also
boolean a switch true / false
string a field a string multiline: true
number a number field a number min, max
enum a menu one of its options' value options: [{ value, label }]
color a colour picker "#rrggbb"
list a box of lines, one per item a list of strings
button a button none command it runs

group puts a heading over a setting and the ones after it, until another group is named. when shows a setting only while another one is so: "legend" (on, or a list with anything in it), "!legend", "style == dark", "style != dark".

On a schedule - schedule, notify, app (API 1.1)

A plugin can ask Textus to do something later - remind the user, sync - without keeping code running. Textus keeps the job (it survives a restart) and fires it on time while it runs: with a window open, or with none in background mode (Settings › General › Keep running in the background; on macOS also until Textus is quit). The first time a plugin sets a job with background mode off, Textus says so and offers to turn it on.

// Every morning at nine, a notification that opens the journal.
await textus.schedule.set("morning", {
  daily: "09:00", // or at: "2026-11-02T09:00", or every: "1h" (15m at least)
  catchUp: "once", // a time missed while Textus wasn't running: once, or "skip"
  notify: {
    title: "Morning pages",
    body: "Three pages before anything else.",
    open: { path: "journal.md", line: 0 }, // needs files.read
  },
});
await textus.schedule.list(); // [{ id: "morning", daily: "09:00", nextDue, ... }]
await textus.schedule.clear("morning");
await textus.notify.show({ title: "Exported", body: "notes.pdf" }); // now

Colours - appearance (API 1.6)

A plugin with the appearance permission lays a palette over whichever theme is on: the page (--doc-bg, --doc-text, --doc-accent, --doc-mark…), the interface (--ui-bg, --ui-text, --ui-accent), the tones, and the frame round the pages, which may be a gradient (--ui-frame-paint). Borders, hovers and the rest follow from these. Text is kept readable, the user's Custom CSS still wins, and turning the plugin off puts the theme back. A whole palette, light and dark apart:

exports.activate = async function (ctx) {
  ctx.subscriptions.push(
    await textus.appearance.setColors(
      {
        "--ui-frame-paint": "linear-gradient(170deg, #6ec5e6, #f6cde1)",
        "--doc-accent": "#0b7fa3",
        "--doc-mark": "#ef8fbb",
      },
      { scheme: "light" },
    ),
    await textus.appearance.setColors(
      {
        "--ui-frame-paint": "linear-gradient(170deg, #0f3346, #3b2440)",
        "--doc-accent": "#5fd0ec",
        "--doc-mark": "#f3a3c7",
      },
      { scheme: "dark" },
    ),
  );
};

appearance.colors() reads the colours as the window shows them now, and appearance.onDidChange tells of another theme, scheme or plugin's colours - for a palette that depends on the theme underneath. Set engines.textus to ">=1.4.2".

Git history - textus.git (API 1.7)

On the desktop, with git installed and the folder in a repository, git.status() gives the branch and the changed files, git.log(path) a file's commits through renames, and git.show(hash, path) the file as a commit had it; these need files.read. git.commit(message, paths) commits those files' changes only, through the user's own git (hooks, signing), and needs git.commit. Hidden files stay out, and nothing pushes, pulls or switches branches. Elsewhere status() is null. Set engines.textus to ">=1.4.3".

The rest

What a plugin can't do

Change how the editor itself works (its schema, its rendering), read another plugin's data, run native code (an agent in contributes.agents is a program Textus starts and talks to, not code in the plugin), or reach the network or files beyond what it was granted. A plugin that stops answering, or throws more than ten errors a minute, is turned off and the user is told.

On iPhone and iPad

Plugins run on iOS as on the desktop, from the same catalog, with the same API; textus.env.platform is "ios". Android runs the plugins made for iOS ("platforms" with "ios"), with textus.env.platform "android". What differs is room and what the system allows:

More

This page is guide.md in the Textus repository.