Appearance
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
| Field | Required | Description |
|---|---|---|
id | Yes | A unique, namespaced id like acme.weather. It never changes after you publish. |
title | Yes | The name people see, in Title Case. A noun, like "Weather" or "GitHub Pull Requests". |
description | Yes | One sentence for the Store. |
icon | Yes | A 512 × 512 PNG in assets/. Add icon@dark.png for dark mode. |
author | Yes | Your Store handle. |
platforms | Yes | macOS, iOS or both. iOS covers iPhone and iPad. |
categories | Yes | One or more Store categories, like Productivity or Developer Tools. |
permissions | No | What the plugin may access. See Permissions. |
preferences | No | Settings for the whole plugin. See Preferences. |
contributors | No | Store handles of people who help maintain the plugin. |
keywords | No | Extra 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.
| Key | Adds | Code |
|---|---|---|
agents | An agent people can start rooms with | src/agents/<name>.ts |
connections | A service the plugin reaches, set up once in Settings and shared by its agents | src/connections/<name>.ts |
blocks | A way to draw a block type in the conversation | src/blocks/<name>.tsx |
commands | A / command in the composer | src/commands/<name>.ts or .tsx |
slots | UI in a fixed place: a sidebar row, beside messages, in the composer | src/slots/<name>.tsx |
surfaces | A larger view a block can open, beside the chat or in its own window | src/surfaces/<name>.tsx |
inspectorTabs | A tab in the room's inspector. In a plugin with a directory, the app draws it from what the directory's inspect returns | src/inspector/<name>.tsx, or no code with a directory |
roomActions | An item in a room's context menu | src/room-actions/<name>.ts |
tools | A capability agents can call | src/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:
| Field | Required | Description |
|---|---|---|
name | Yes | Unique within the plugin. Lowercase, with hyphens. Matches the code's file name. |
title | Yes | What people see. |
description | Depends | Required for agents, commands and tools. Agents read tool descriptions too, so be specific. |
icon | No | An icon from assets/, or an SDK icon name. Defaults to the plugin's icon. |
preferences | No | Settings for just this contribution. They're added to the plugin's preferences. |
agents
| Field | Description |
|---|---|
instructions | Default instructions for new agents created from this one. People can edit them. |
preferences | Settings 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. |
directory | This 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.
| Field | Description |
|---|---|
name, title, description | As for every contribution. The title and description head the Settings pane. |
preferences | Settings 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. |
local | How 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
| Field | Description |
|---|---|
type | Required. 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
| Field | Description |
|---|---|
arguments | Up to three inline arguments, typed in the composer after the command. See Arguments. |
mode | action (default) runs and finishes, like posting a card. view opens a surface with UI. |
slots
| Field | Description |
|---|---|
slot | Required. Where it goes: sidebar.row, message.actions, composer.leading, composer.trailing, composer.accessory, chat.activity or inspector.header. |
order | Position among other plugins' contributions to the same slot. Lower comes first. |
surfaces
| Field | Description |
|---|---|
size | Where it opens by default: stage (beside the chat), sheet or window. |
roomActions
| Field | Description |
|---|---|
style | default 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 }
]| Field | Required | Description |
|---|---|---|
name | Yes | The key in code. |
type | Yes | text, password, url, number, checkbox or dropdown. |
title | Yes | The label. |
description | No | Shown as help below the field. |
required | No | If true, the contribution can't be used until it's filled in. The app asks for it at the right moment. |
default | No | The starting value. |
placeholder | No | Hint text for text, password, url and number. |
label | For checkbox | The text beside the checkbox. |
data | For dropdown | The options, as { title, value }. |
hidden | No | If 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. |
advanced | No | If 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.
| Field | Required | Description |
|---|---|---|
name | Yes | The key in code. |
type | Yes | text or dropdown. |
placeholder | Yes | Shown in the composer. |
required | No | Required arguments must come first. |
data | For dropdown | The 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.
| Permission | Value | Allows |
|---|---|---|
network | A list of hosts | fetch and WebSockets to those hosts only. Use *.example.com for subdomains, or { "preference": "endpoint" } for a host the person enters. |
notifications | true | Sending 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