Building plugins

A boost is a small folder Veb keeps for you. When it only restyles a site it is a Look. Give it code and it becomes a plugin. Veb 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 Veb, or access to Veb’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. Veb 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; only page styles and scripts can be kept for every site, with ⌥ on Keep. 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, and up to four more hosts named in "hosts" under yab (JSON over https, without cookies), never through 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; Veb 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 Veb 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 comes to the Store only as reviewed releases in plugins/ of yab-plugins, and Veb installs only the release the Store lists.