← Optimistic Agency

Maestro docs

Custom panels

Last updated November 11, 2026

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 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

<!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">.

FieldRequiredMeaning
idYesLowercase letters, digits and dashes, up to 63 characters. Installing a file whose id you already have updates that panel.
nameYesShown in + Panel and on the pane, up to 60 characters.
versionYesYour version, for example 1.2.0.
descriptionNoOne line shown in Manage panels…, up to 280 characters.
iconNoAn emoji shown in menus and on the pane.
permissionsNo["file.read"] if the panel reads files the person chooses. It is the only permission today.
toolsNoCallable functions declared by this panel. See the custom tools contract.

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 defines that contract.

CallResolves toWhat it does
oa.ready()oaConnects to Maestro and applies the theme. oa.ready().then(start) is a good way to begin.
oa.state.get()any JSON, or nullThis 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 nullOpens Maestro's file finder. null means the person cancelled. Needs file.read.
oa.file.current(){ name } or nullThe 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:

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:

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 is a full panel in one file (watch it run). 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 is a shorter one that charts a column as bars (watch it run). Both live in 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.