Getting Started

Write your first Stoa plugin in five minutes. A zero-to-sidebar walkthrough — no build step, no CLI, no deploy. Just a JavaScript file.

Plugins are JavaScript files that extend the Stoa workspace. You write them in the editor, they sync to all participants via CRDT, and they execute in a sandboxed Web Worker. Output renders natively in the sidebar and content panel.

Your first plugin

Create a _stoa_plugins/ directory at the root of any project in your workspace, then add a .js file:

// _stoa_plugins/hello.js

// @stoa-plugin
// @name Hello World
// @type widget
// @icon Zap

module.exports = {
  render(context) {
    return {
      type: 'markdown',
      content: '**Plugin works!**\n\nBuilt with Stoa plugins.'
    }
  }
}

The plugin appears in the Space section of the sidebar. Expand it to see the output. Click "Open" to see the full-panel view.

Tip

Edit the file and the output updates in ~100ms for all participants. No restart, no refresh.

File location

Plugins must live in a _stoa_plugins/ directory at the root of any project in the workspace. Only .js and .ts files are discovered.

my-project/
  _stoa_plugins/
    sprint-board.js
    data-preview.js
  src/
    ...

Plugin header

Every plugin must start with comment lines declaring its metadata. The @stoa-plugin marker is required.

// @stoa-plugin
// @name Sprint Board
// @type widget
// @icon BarChart3
// @refresh 60s

Required fields

Field	Description
`@stoa-plugin`	Marker identifying this file as a plugin. Must be present.
`@name`	Human-readable name shown in the sidebar.
`@type`	Plugin type: `widget`, `renderer`, or `agent`.

Optional fields

Field	Description	Example
`@icon`	Lucide icon name for the sidebar. Defaults to `Puzzle`.	`BarChart3`
`@refresh`	Auto-refresh interval. Plugin re-executes on this timer.	`30s`, `5m`, `2h`
`@permissions`	Comma-separated capability grants.	`network:api.linear.app`
`@runtime`	Force `server` execution (V8 isolate). Default is `client` (Web Worker).	`server`
`@filetype`	For renderer plugins: comma-separated glob patterns.	`.csv,.tsv`
`@events`	Event subscriptions for live data.	`transcript:segment`
`@toolbar`	For agent plugins: display mode.	`pills`, `menu`, `icons`

Available icons

BarChart3, Users, Globe, Database, Bell, Table, Activity, FileText, Puzzle, Zap, Code, Settings, Terminal

Plugin types

Stoa supports three plugin types:

Widgets

Sidebar panels with full-screen expanded views. Dashboards, status boards, timers.

Renderers

Override how file types display. CSVs as tables, JSON as trees, config as forms.

Agent Plugins

Prompt buttons on the AI agent toolbar. One-click context-aware prompts.

Execution environment

All plugins run client-side in a Web Worker by default:

~1ms execution — no server round-trip
fetch() works — browser's native fetch API
async/await supported
5 second timeout — worker is terminated if exceeded
No DOM access — Web Workers can't touch the page
CommonJS only — use module.exports, not export default
No state persists between runs — each execution is fresh

Auto-refresh

Add @refresh to re-execute the plugin on a timer:

// @stoa-plugin
// @name Clock
// @type widget
// @refresh 1s

module.exports = {
  render() {
    return {
      type: 'text',
      content: new Date().toLocaleTimeString()
    }
  }
}

Supported units: s (seconds), m (minutes), h (hours).

Live editing

Plugins are files in the workspace — edit them in the editor and the output updates for all participants. The CRDT sync propagates changes in ~50ms, and the plugin re-executes in ~16ms. The full loop from keystroke to visible update is under 100ms.