# Custom panels

> Plain-Markdown copy of https://optimisticagency.com/docs/panels. Links are relative to https://optimisticagency.com.

Custom panels let you add your own views to Maestro: a table for a CSV file, a viewer for your logs, a chart of your results. A panel is one HTML file. Install it, open it beside your chats and code, and it works with the files you choose. Custom panels are in beta.

## The idea in one minute

- **A panel is one HTML file.** Its manifest, a small JSON block, sits inside the file. Write it by hand, ask an agent to write it, or build it with React or any web framework and bundle it into one file.
- **You install it, or an agent makes it for you.** It then appears in **+ Panel** next to Chat, Editor, Terminal and the other built-in panels, in every project on your account, on the web and in the Maestro app.
- **Every pane is its own copy.** Open the same panel twice on two different files. Each pane remembers its file and its view in split panes, in floating windows and after a reload.
- **It sees only what you hand it.** You can choose a file in Maestro’s file finder, or an agent can bind an authorized file to the pane. The panel receives that file's name and contents, never its path or anything else in your project.
- **It can't send your data anywhere.** Panels run in a sandbox with no network, no access to your Maestro session, and no way to open pages or windows.

## Make one

There are two ways to make a panel: write the file yourself, or ask an agent in a Maestro chat. Both work on the web and in the Maestro app on your phone, and the result is the same one file.

### By hand, on the web

1. In a Maestro project, open **+ Panel → Manage panels…** and choose **Copy starter panel**.
2. Save it as a file in your project, such as `panels/my-panel.html`. Give it your own `id` and `name`, and write the page.
3. In **Manage panels…**, choose **Install from a project file…**, pick the file, then **Install panel**.
4. Open it from **+ Panel**. To change it, edit the file, raise its `version` and install it again.

### By hand, on your phone

1. Save the panel's file in your project, from the web or by asking an agent to write it.
2. In the Maestro app, tap **+ → Custom panel → Manage panels…**, then **Install from a project file…**, choose the file and tap **Install panel**. **Examples** install with one tap.
3. Back in the chooser, tap the panel to open it.
4. In a phone's browser, Maestro on the web has the same **+ → Custom panel** chooser and the same **Manage panels…**.

### With an agent, on the web

1. In any Maestro chat, ask: “Make me a panel that …”.
2. The agent asks first. **Approve** the **Create panel** card, and the panel appears in **+ Panel**, marked **Draft**.
3. Open it beside the chat, or let the agent open it. Its edits need no approval, and the pane redraws after each one.
4. When you like it, **Approve** the **Publish panel** card, which lists each change in plain words. **Draft** goes away.
5. If a later edit breaks it, choose **Draft → Go back to published version**.

### With an agent, on your phone

1. In a chat in the Maestro app, ask the same: “Make me a panel that …”.
2. The **Create panel** and **Publish panel** cards appear in the chat. Tap **Approve** on each.
3. The panel opens on your phone, not on a computer you left open. **Draft** sits in its top strip. Before the first publish it reads **Not published yet**; after it, it offers **Go back to published version**.

## Use a panel

1. In a Maestro project, open **+ Panel** and choose **Manage panels…**. On your phone, in the Maestro app or in a phone's browser, tap **+ → Custom panel → Manage panels…**.
2. Under **Examples**, choose **Install** next to Table Lens. To install a panel of your own, save its file in your project and choose **Install from a project file…**.
3. Open **+ Panel** again (on your phone, **+ → Custom panel**) and choose the panel. It opens as a new pane.
4. Choose a file when the panel asks. Table Lens browses CSV files; if you don't have one handy, [download a sample](/panels/sample-inventory.csv) and add it to your project.
5. To update a panel, install the new file. A file with the same `id` replaces the old version everywhere it's open.
6. To turn a panel off or remove it, use **Manage panels…**. Panes that use it show a notice and keep their place in your layout, so turning it back on brings them back.

### Draft and published

A panel an agent is working on is a **draft**: each edit is saved and runs at once, and the pane's top strip shows **Draft**. Publishing makes the current draft the version to go back to; nothing is listed in a store. If a later edit breaks the panel, choose **Draft → Go back to published version**. A panel that was never published shows **Not published yet** under **Draft**.

### Storage and GitHub

Panel files count toward your cloud storage, shown in **Billing** as **Panels and tools**. In **Manage panels…** you can also link GitHub and choose a repository: from then on, every create, publish and delete becomes one commit there, under `<panel id>/panel.html`. Maestro only writes to that repository; it never reads panels back from it. Changes made on your phone wait until you choose **Copy to GitHub** on the web.

## Write a panel

### Start from this file

```html
<!doctype html>
<html>
<head>
  <script type="application/oa-panel+json">
    {"id": "my-panel", "name": "My Panel", "version": "1.0.0",
     "description": "Shows the first lines of a file.", "icon": "✨", "permissions": ["file.read"],
     "tools": [{"name": "get_preview", "description": "Read the displayed first 20 lines.", "input_schema": {"type": "object", "properties": {}}}]}
  </script>
  <style>
    body { margin: 0; padding: 12px; font-family: var(--font-sans); color: var(--color-text-primary);
           background: var(--color-background-primary); }
  </style>
</head>
<body>
  <button id="choose">Choose file</button>
  <pre id="preview"></pre>
  <script>
    const preview = document.getElementById("preview");
    async function show() {
      const file = await oa.file.current();
      if (file) preview.textContent = (await oa.file.read()).text().split("\n").slice(0, 20).join("\n");
    }
    document.getElementById("choose").onclick = async () => { if (await oa.file.choose()) await show(); };
    oa.tools.handle("get_preview", async () => {
      await loaded;
      if (!await oa.file.current()) throw new Error("Bind a file with open_file_for_user first.");
      return { text: preview.textContent };
    });
    const loaded = oa.ready().then(show);
    loaded.catch(error => { preview.textContent = error.message; });
  </script>
</body>
</html>
```

Every panel has the same three parts: a manifest, CSS that uses Maestro's theme, and a script that talks to Maestro through `window.oa`.

### The manifest

The manifest is JSON inside `<script type="application/oa-panel+json">`.

| Field | Required | Meaning |
| --- | --- | --- |
| `id` | Yes | Lowercase letters, digits and dashes, up to 63 characters. Installing a file whose `id` you already have updates that panel. |
| `name` | Yes | Shown in **+ Panel** and on the pane, up to 60 characters. |
| `version` | Yes | Your version, for example `1.2.0`. |
| `description` | No | One line shown in **Manage panels…**, up to 280 characters. |
| `icon` | No | An emoji shown in menus and on the pane. |
| `permissions` | No | `["file.read"]` if the panel reads files the person chooses. It is the only permission today. |
| `tools` | No | Callable functions declared by this panel. See the [custom tools contract](/docs/tools). |

### The `oa` API

Maestro adds `window.oa` to the panel before the panel's own scripts run. The file and state calls return promises and wait until the panel is connected. Register callable functions with `oa.tools.handle(name, handler)` before `oa.ready()`; the [custom tools guide](/docs/tools) defines that contract.

| Call | Resolves to | What it does |
| --- | --- | --- |
| `oa.ready()` | `oa` | Connects to Maestro and applies the theme. `oa.ready().then(start)` is a good way to begin. |
| `oa.state.get()` | any JSON, or `null` | This pane's saved view state. |
| `oa.state.set(state)` | `{}` | Saves this pane's view state: any JSON value up to 16 KiB. Maestro keeps it with the pane. |
| `oa.file.choose()` | `{ name }` or `null` | Opens Maestro's file finder. `null` means the person cancelled. Needs `file.read`. |
| `oa.file.current()` | `{ name }` or `null` | The file this pane is using. |
| `oa.file.read({ maxBytes })` | `{ bytes, version, text() }` | Reads the whole chosen file. `bytes` is a `Uint8Array`; `text()` decodes UTF-8 and throws on anything else. Rejects if no file is chosen, if the file is larger than `maxBytes`, or if the file changes while it is read. |

`oa.context` holds what Maestro shares about where the panel runs: `theme` (`"light"` or `"dark"`), `platform`, `locale` and `timeZone`. `oa.onContextChange(listener)` calls `listener` with the new context, for example when the person switches theme, and returns a function that stops listening.

### Match Maestro's look

Maestro sets its colors and font as CSS variables on the panel's root element and updates them when the theme changes. Use them with fallbacks so the panel still reads well anywhere else:

```css
body {
  background: var(--color-background-primary, #fff);
  color: var(--color-text-primary, #111);
  font-family: var(--font-sans, system-ui, sans-serif);
}
```

Available: `--color-background-primary`, `--color-background-secondary`, `--color-background-tertiary`, `--color-text-primary`, `--color-text-secondary`, `--color-text-tertiary`, `--color-border-primary`, `--color-border-secondary`, `--color-ring-primary` (Maestro's accent) and `--font-sans`. The root element also carries `data-theme="light"` or `data-theme="dark"`. These are the standard MCP Apps style variables, so a panel written for another MCP Apps host looks right in Maestro too.

### What the sandbox allows

- **No network.** `fetch`, `XMLHttpRequest`, WebSockets, and remote scripts, stylesheets, fonts and images are blocked. Put everything in the file and use `data:` URLs for images and fonts.
- **No browser storage.** `localStorage`, `sessionStorage`, IndexedDB and cookies are unavailable. Keep what a pane should remember in `oa.state`.
- **No popups, dialogs or downloads.** `window.open`, `alert`, `confirm`, `prompt`, downloads and navigating away do nothing. Show messages inside the panel.
- **Size.** A panel file can be up to 4 MiB and a pane's view state up to 16 KiB.

### Build with React, Vue or Svelte

Any framework works if the build produces one HTML file with everything inlined. With Vite:

1. Create the app: `npm create vite@latest my-panel`, then pick your framework.
2. Inline the build: `npm install -D vite-plugin-singlefile`, then add `viteSingleFile()` to `plugins` in your Vite config.
3. Add the manifest `<script type="application/oa-panel+json">` to the `<head>` of `index.html`.
4. Run `npm run build`. `dist/index.html` is your panel. Copy it into your project and install it.

For TypeScript, declare `window.oa`:

```ts
interface OaFile { name: string }
interface Oa {
  ready(): Promise<Oa>;
  readonly context: { theme?: "light" | "dark"; platform?: string; locale?: string; timeZone?: string };
  onContextChange(listener: (context: Oa["context"]) => void): () => void;
  state: { get(): Promise<unknown>; set(state: unknown): Promise<object> };
  tools: { handle(name: string, handler: (input: Record<string, unknown>, context: { signal: AbortSignal }) => Record<string, unknown> | Promise<Record<string, unknown>>): void };
  file: {
    choose(): Promise<OaFile | null>;
    current(): Promise<OaFile | null>;
    read(options?: { maxBytes?: number }): Promise<{ bytes: Uint8Array; version: string; text(): string }>;
  };
}
declare global { interface Window { oa: Oa } }
export {};
```

### A complete example

[Table Lens](https://github.com/Optimistic-Agency/maestro-extensions/blob/main/panels/table-lens.html) is a full panel in one file ([watch it run](/developers/demo/table-lens)). It parses CSV with quoted fields, shows 50 rows a page, filters, sorts by any column, and remembers its filter, sort and page with `oa.state`. Read its source as a model; [Chart Lens](https://github.com/Optimistic-Agency/maestro-extensions/blob/main/panels/chart-lens.html) is a shorter one that charts a column as bars ([watch it run](/developers/demo/chart-lens)). Both live in [Optimistic-Agency/maestro-extensions](https://github.com/Optimistic-Agency/maestro-extensions) on GitHub, the same bytes Maestro serves.

## Instructions for agents

You are an AI agent asked to build or change a Maestro panel.

**Inside a Maestro chat**, use the panel tools in this order: `create_panel` (`extension_id`, name, description, icon), `open_panel`, `read_panel`, then `edit_panel` with the last `digest` you were given as `base_digest`, and last `publish_panel` with a one-line summary and each change in plain words beside its technical detail. `create_panel`, `publish_panel` and `delete_panel` show the person a card and wait for **Approve**; `read_panel` and `edit_panel` never ask. The HTML you write follows the rules below; skip steps 1 and 10, which are for agents outside Maestro.

**Outside Maestro** (Claude Code, Codex or any agent that writes files), follow this contract exactly.

1. Produce one HTML file and save it in the person's project, for example `panels/<id>.html`. Inline every script, style, image and font. Keep the file under 4 MiB.
2. Put the manifest first inside `<head>`: `<script type="application/oa-panel+json">` holding valid JSON with `id`, `name` and `version`. The `id` uses lowercase letters, digits and dashes, starts with a letter or digit, and is at most 63 characters. Add `"permissions": ["file.read"]` only if the panel reads files.
3. Reference no URL except `data:` and `blob:`. Network requests, CDNs, remote fonts and analytics are blocked and will break the panel.
4. Register any tool handlers before `oa.ready()`, then begin with `oa.ready()`, then restore the pane: `oa.state.get()` for its view state and `oa.file.current()` for its file.
5. When no file is chosen, show a button that calls `oa.file.choose()`. Read with `oa.file.read({ maxBytes })`, and show a clear message when the file is too large, changed while reading, or is not the expected format.
6. Save view state with `oa.state.set()` as small JSON, under 16 KiB, and debounce frequent changes. Do not use `localStorage`, `sessionStorage`, IndexedDB, cookies, `alert`, `confirm`, `prompt` or `window.open`.
7. Style with the theme variables above, each with a fallback, and support both light and dark.
8. Show every error inside the panel. Never fail silently.
9. To change an existing panel, keep its `id` and raise its `version`.
10. Finish by telling the person: open **+ Panel → Manage panels… → Install from a project file…**, choose the file, then open the panel from **+ Panel**.

Before you hand it over, check that the manifest parses as JSON, that no `src`, `href`, `url()`, `import` or `fetch` points at an `http:` or `https:` address, and that every `oa` call handles rejection.

## Maestro Store: coming soon

Soon you'll share panels and tools in a store for other people to install, with updates and removal handled for them, and later, paid ones. Publishing a panel in Maestro today only makes it the version to go back to; it does not list it anywhere. Until the store opens, share a panel by sending someone the file; they install it from their project.

Tell us what you build and what's missing: [hello@optimisticagency.com](mailto:hello@optimisticagency.com).
