Skip to content

Manifest ​

A plugin's manifest is its package.json, with everything specific to Agent Playgrounds under the agentPlaygrounds key. It says what the plugin is, what it adds to the app, what settings it needs and what it's allowed to do.

Preview

The TypeScript SDK is being designed in the open. Fields on this page may change before the first release.

json
{
  "$schema": "https://agentplaygrounds.com/schemas/plugin.json",
  "name": "weather",
  "agentPlaygrounds": {
    "id": "acme.weather",
    "title": "Weather",
    "description": "Share live weather cards in any room.",
    "icon": "icon.png",
    "author": "acme",
    "platforms": ["macOS", "iOS"],
    "categories": ["Productivity"],
    "permissions": { "network": ["api.open-meteo.com"] },
    "blocks": [{ "name": "weather", "type": "acme.weather", "title": "Weather card" }],
    "commands": [{ "name": "weather", "title": "Share Weather", "description": "Post the current weather for a city." }]
  },
  "dependencies": { "@agentplaygrounds/sdk": "^0.1.0" }
}

Add the $schema line and your editor will autocomplete and check every field.

Plugin ​

FieldRequiredDescription
idYesA unique, namespaced id like acme.weather. It never changes after you publish.
titleYesThe name people see, in Title Case. A noun, like "Weather" or "GitHub Pull Requests".
descriptionYesOne sentence for the Store.
iconYesA 512 × 512 PNG in assets/. Add icon@dark.png for dark mode.
authorYesYour Store handle.
platformsYesmacOS, iOS or both. iOS covers iPhone and iPad.
categoriesYesOne or more Store categories, like Productivity or Developer Tools.
permissionsNoWhat the plugin may access. See Permissions.
preferencesNoSettings for the whole plugin. See Preferences.
contributorsNoStore handles of people who help maintain the plugin.
keywordsNoExtra words for Store search.

The SDK version in dependencies is checked against the app when the plugin is installed. If someone's app is older than your plugin needs, they're asked to update.

Contributions ​

Contributions are what a plugin adds to the app. Each one has a name, and its code lives at a matching path. A plugin can have any mix.

KeyAddsCode
agentsAn agent people can start rooms withsrc/agents/<name>.ts
connectionsA service the plugin reaches, set up once in Settings and shared by its agentssrc/connections/<name>.ts
blocksA way to draw a block type in the conversationsrc/blocks/<name>.tsx
commandsA / command in the composersrc/commands/<name>.ts or .tsx
slotsUI in a fixed place: a sidebar row, beside messages, in the composersrc/slots/<name>.tsx
surfacesA larger view a block can open, beside the chat or in its own windowsrc/surfaces/<name>.tsx
inspectorTabsA tab in the room's inspector. In a plugin with a directory, the app draws it from what the directory's inspect returnssrc/inspector/<name>.tsx, or no code with a directory
roomActionsAn item in a room's context menusrc/room-actions/<name>.ts
toolsA capability agents can callsrc/tools/<name>.ts

Names are forever

A contribution's name is its identity. People's shortcuts, pinned commands and saved permissions refer to it. Don't rename one after you publish; add a new one instead.

Common fields ​

Every contribution has:

FieldRequiredDescription
nameYesUnique within the plugin. Lowercase, with hyphens. Matches the code's file name.
titleYesWhat people see.
descriptionDependsRequired for agents, commands and tools. Agents read tool descriptions too, so be specific.
iconNoAn icon from assets/, or an SDK icon name. Defaults to the plugin's icon.
preferencesNoSettings for just this contribution. They're added to the plugin's preferences.

agents ​

FieldDescription
instructionsDefault instructions for new agents created from this one. People can edit them.
preferencesSettings asked for when someone creates the agent, like an endpoint or API key. An agent with a directory needs no address or token preferences: the connection holds them.
directoryThis agent is one of many on a service the plugin connects to: { "connection": "gateway", "create": true, "update": true, "delete": true }. The app lists the agents on that connection with the code at src/directories/<name>.ts, syncs them into the Agent library, and offers New, Edit and Delete for the ones set to true.

See Connect your first agent, and Connections and directories for a directory.

connections ​

A connection is a service the plugin talks to, like a gateway on this Mac. The person sets it up once, in a Settings pane titled after the plugin, and every agent with a directory on it shares it. Its code lives at src/connections/<name>.ts.

FieldDescription
name, title, descriptionAs for every contribution. The title and description head the Settings pane.
preferencesSettings for the connection, asked for in the Settings pane: an address. A token for a service on another machine is not a preference: Connect another gateway… asks for it and hands it to connect as bootstrapToken, once.
localHow the app may find the service on this Mac: { "probeUrl": "http://127.0.0.1:18789/healthz", "bootstrap": { "file": "~/.openclaw/openclaw.json", "tokenPath": "gateway.auth.token" } }.

With local, the app sends a GET to probeUrl (with the port the bootstrap file names beside the token, like gateway.port, when it differs) to say "running on this Mac", and the Settings pane and the Agent library offer Connect. On Connect it reads the one-time secret at bootstrap.tokenPath in bootstrap.file, once, hands it to the connection's connect, and never keeps it. The app reads only a JSON file in a dot folder under the home folder, and never one under ~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, ~/.docker, ~/.azure or ~/.config. See Connections and directories.

blocks ​

FieldDescription
typeRequired. The block type this renders, like acme.weather. Namespace it with your plugin's id.

Block renderers are pure functions of the block's payload. See How UI works.

commands ​

FieldDescription
argumentsUp to three inline arguments, typed in the composer after the command. See Arguments.
modeaction (default) runs and finishes, like posting a card. view opens a surface with UI.

slots ​

FieldDescription
slotRequired. Where it goes: sidebar.row, message.actions, composer.leading, composer.trailing, composer.accessory, chat.activity or inspector.header.
orderPosition among other plugins' contributions to the same slot. Lower comes first.

surfaces ​

FieldDescription
sizeWhere it opens by default: stage (beside the chat), sheet or window.

roomActions ​

FieldDescription
styledefault or destructive. Destructive actions are shown in red and ask for confirmation.

tools ​

Tools are described by their code: the input's TypeScript type becomes the schema agents see, and doc comments become descriptions. A tool can export a confirmation to ask the person first.

Preferences ​

Preferences are settings people fill in. The app draws the settings form, so you don't build any UI. Read them in code with getPreferences(), typed from your manifest.

json
"preferences": [
  { "name": "units", "type": "dropdown", "title": "Units", "default": "metric",
    "data": [{ "title": "Celsius", "value": "metric" }, { "title": "Fahrenheit", "value": "imperial" }] },
  { "name": "apiKey", "type": "password", "title": "API key", "required": true }
]
FieldRequiredDescription
nameYesThe key in code.
typeYestext, password, url, number, checkbox or dropdown.
titleYesThe label.
descriptionNoShown as help below the field.
requiredNoIf true, the contribution can't be used until it's filled in. The app asks for it at the right moment.
defaultNoThe starting value.
placeholderNoHint text for text, password, url and number.
labelFor checkboxThe text beside the checkbox.
dataFor dropdownThe options, as { title, value }.
hiddenNoIf true, never shown in a form. For a preference agents saved by an earlier version of your plugin still carry: it reaches your code, and nobody is asked for it.
advancedNoIf true, shown in the app's Settings ▸ Advanced, under your plugin's name, instead of with the rest. For a setting most people should leave as it is. A connection's advanced preference is saved with the connection and reaches connect like the others; changing it connects again, so apply it there.

password values are stored in the Keychain, only your plugin can read them, and they're never synced in plain text. Add a help.md file next to your manifest to show setup instructions beside the settings form, like how to get an API key.

Arguments ​

Commands can take up to three arguments, typed inline after the command name in the composer.

FieldRequiredDescription
nameYesThe key in code.
typeYestext or dropdown.
placeholderYesShown in the composer.
requiredNoRequired arguments must come first.
dataFor dropdownThe options, as { title, value }.

Permissions ​

Plugins start with no access to anything outside their own sandbox. Each permission is listed in the Store and shown before install. Ask only for what you need: plugins that ask for less get installed more.

PermissionValueAllows
networkA list of hostsfetch and WebSockets to those hosts only. Use *.example.com for subdomains, or { "preference": "endpoint" } for a host the person enters.
notificationstrueSending notifications when something needs attention.
clipboard"write" or "read-write"Copying, and with read-write, reading the clipboard.
rooms"read"Reading rooms the plugin isn't part of, such as for a dashboard. Without it, a plugin only sees the room it's working in.

Some things need no permission: storing data for your own plugin, showing toasts, opening links (through the app's link policy) and asking the person questions.

Generated types ​

When you run npm run dev or npm run build, the SDK writes agent-playgrounds-env.d.ts from your manifest. It types your preferences and arguments, so code like CommandProps<Arguments.Weather> always matches what you declared.

File structure ​

my-plugin/
├── package.json        The manifest
├── help.md             Optional setup help, shown beside required settings
├── assets/             Icons and images
├── metadata/           Store screenshots
├── src/
│   ├── agents/
│   ├── blocks/
│   ├── commands/
│   ├── connections/
│   ├── directories/
│   ├── inspector/
│   ├── room-actions/
│   ├── slots/
│   ├── surfaces/
│   └── tools/
├── CHANGELOG.md
└── README.md

All your Agents, playing nicely in one Playground.