Building plugins

A boost is a small folder Yab keeps for you. When it only restyles a site it is a Look. Give it code and it becomes a plugin. Yab works out which kind from the files, and the card you press Keep on says what that kind may do:

• Look: CSS only. “Change how youtube.com looks. No code runs.”
• Page: a script on the named sites, for what CSS can’t do: color posts by who wrote them, keep a feed sorted, add a button. “Run code on x.com. It can read and change these pages.”
• Tool: actions your agents can call on a site, with your sign-in there: find issues, create one. “Adds 2 agent tools.”
• App: a page of its own, a job that runs on a schedule, commands and routines in Yab, or access to Yab’s own abilities (see The yab API).

Make one#

1. Open the site and ask in ⌘J: “color tweets from people I follow blue, others red”.
2. Your agent writes the plugin and tries it in a tab of its own. Nothing runs anywhere else until you press Keep ⌘↩ on its card.
3. To change it later, open Site Controls with ⌘E, open its menu and choose Change…. Show in Finder shows its files; Show Changes… has every version.

You can write the files yourself and hand them to your agent the same way. Yab doesn’t load a folder from disk directly: every plugin is tried first, and only you keep it. After three similar runs on a site, the chat offers Save as Tool… to turn what the agent did into a tool.

The folder#

manifest.json          Manifest V3, plus a "yab" key for plugins
BOOST.md               what it is for, and its checks
page/style.css         Look
page/page.js           Page: a script on the named sites
checks.js              checks that need code
tools.js               Tool: what your agents can call
skills/<name>/SKILL.md how an agent should use the site
evals.yaml             example asks for each tool
app/index.html         App: its own page
service.js             App: a job on a schedule
commands.json          App: commands, quick actions, routines

Up to 32 files and 512 KB. A plugin names its sites exactly, one to eight hosts. Scripts may not use eval, new Function or import().

Scripts on the page#

List the script in content_scripts as you would a stylesheet. It runs in a world of its own, apart from the page’s scripts and from other plugins, at the end of loading, in the top frame only.

// page/page.js
boost.observe(document.querySelector('main'), () => {
  for (const post of document.querySelectorAll('article')) {
    post.style.borderLeft = followed(post) ? '3px solid #3b82f6' : '3px solid #ef4444'
  }
})

boost.on and boost.observe clean up after themselves when the plugin is turned off. fetch reaches the same site only, without redirects; other ways out (XHR, WebSockets) are closed. A check that needs code goes in checks.js:

boost.check('colored', () => document.querySelectorAll('article[style]').length > 0)

and in BOOST.md as - on /*: script colored.

Tools for your agents#

The manifest declares each tool; Yab never runs your code to find out what it offers.

{"manifest_version": 3, "name": "Linear Tools", "version": "1.0",
 "yab": {"tools": {
   "find_issues":  {"description": "Find my open issues", "params": {"query": "string", "limit": "integer?"}},
   "create_issue": {"description": "Create an issue", "params": {"title": "string", "team": "string"}, "acts": "post"}
 }}}

// tools.js
export async function find_issues({ query, limit }, site) {
  return site.json('/api/issues?q=' + encodeURIComponent(query))
}
export async function create_issue(args, site) {
  return site.post('/api/issues', args)
}

• A tool runs in a blank page of its own, with no DOM. site.json and site.post reach your first site only, and Yab adds your sign-in there without your code ever seeing it.
• A tool marked acts (post, send, pay, delete or write) asks you on every call, with the arguments in front of you. A job running in the background can’t say yes for you.
• Agents see it as linear-tools.find_issues while they work on that site. In Terminal: yab linear-tools find-issues --query bug, or with JSON.
• A skills/<name>/SKILL.md teaches agents the site, and evals.yaml lists example asks for each tool: - ask: "Show my open issues", tool: find_issues, args: {"query": ""}.

Sharing it#

A Look goes to the Store as a pull request (see Publishing to the Store). For code, share the recipe: Share Recipe… in its menu saves BOOST.md, the intent and checks anyone’s agent can build it again from. Code in the Store will come as reviewed releases in plugins/ of yab-plugins; Yab doesn’t install code from the Store yet.