Building block 5 · The basics
Surfaces
A surface is a place your extension can show you something. It can ask a quick question, open a window that stays put, or add its own section or page to Charlie.
What you'd use it for
- Ask permission or a choice before Charlie carries on, like bash's approval pop-up.
- Keep a list or view open beside the chat, like a checklist window.
- Add a quick list to the left sidebar, or a full page to the top bar.
In your manifest
From the checklist extension, trimmed: a tool that opens a window, and a sidebar section.
"sidebar": { "label": "Checklists", "component": "./build/ChecklistSidebar.js" }, "tools": [ { "name": "open", "handler": "./handlers/open.js", "ui": { "surface": "window", "component": "./build/ChecklistWindow.js" } } ]
From the hub-persistence extension (Finder), trimmed: a top-bar page with its own chat.
"topBar": { "label": "Finder", "icon": "folders", "component": "./build/Finder.js", "keepAlive": true, "thread": { "instructions": { "module": "./handlers/finderInstructions.js" } } }
What each part means
| Field | What it does |
|---|---|
ui.surface: "modal" | A pop-up card over the chat, which dims behind it. It waits for one answer, then closes. |
ui.surface: "chat-replacement" | Takes the place of the message box until you answer. The conversation above stays visible. Questions uses this. |
ui.surface: "window" | A separate window that stays open after the reply. Later tool calls can update it. |
ui.component | The built file to show in that surface. |
sidebar | A section in Charlie's left sidebar, with a label and a component. |
topBar | An item in Charlie's top bar. Picking it fills the main area with your component. icon is a Tabler icon name. |
topBar.keepAlive | Optional. Hides the page when you switch away, so unsaved work survives. |
topBar.thread | Optional. Docks a chat under the page. See Instructions. |
Charlie also accepts "popover" for ui.surface, but it isn't built yet.
How a tool uses its surface
For a modal or chat-replacement, the handler calls ctx.requestUI(props). Your answer comes back as the result. A handler can also pass a second value to pick a different surface for that one call.
For a window, the handler calls ctx.openWindow(props, { instanceKey }). It returns at once and never waits for an answer. Calling again with the same instanceKey brings the same window forward.
Components are built files
Each component is a React component, written as JSX in src/ and compiled to plain JavaScript in build/. Point your manifest at the build/ file. Don't import anything: React and CharlieUI are already there.
Talking to Charlie
What a component receives depends on where it lives:
- A
modalorchat-replacementcomponent gets the props fromrequestUI, plusonAnswerto send your answer back. - A window, sidebar or top-bar component gets a
charlieprop.charlie.invoke(channel, payload)calls a function in yourchannelsmodule. See Live state. - Windows and top-bar pages can also hear messages your handlers push with
ctx.postToWindoworctx.postToView.
CharlieUI is Charlie's kit of ready-made pieces: Surface, Field, Text, Button, Choice, TextInput, List, Badge, Markdown and more. They follow light and dark mode for you. Escape lets you drop to plain markup, such as a dense table, and still match the theme.
Things to know
- Restart Charlie after adding or changing a surface. Rebuild
build/after editing a component. - A modal hides the chat, so put the full question in the props you pass.
ctx.postToWindowdoes nothing if you closed the window. It won't reopen it.- A sidebar section only draws while it's expanded.
- A switched-off extension shows no sidebar section, top-bar item or window channels.
- A tool marked
"surface": trueis offered only in its top-bar page's chat, never in ordinary chats.
See it in
Every field, in full: reference: ui, sidebar and topBar.