Reference
Manifest reference
Every field you can put in manifest.json, in one place. Use it to look something up once you know what you want to build.
Fields marked Required must be present or Charlie skips the extension. Every other field is optional. Paths to files are written from the extension's own folder, like "./handlers/run.js". Charlie reads the manifest only when it starts, so restart Charlie after any change.
Identity
Who the extension is. Charlie checks these first. See Your first extension.
| Field | What it does |
|---|---|
nametext | The extension's name, and the prefix on all its tool names. Use lowercase letters, numbers and hyphens; the catalog accepts nothing else. Required |
descriptiontext | One sentence on what the extension does, shown in Charlie's Extensions list. Required |
versiontext | Three numbers with dots, like "1.0.0", with an optional suffix such as "1.0.0-beta". Required |
tiertext | Must be "core". Any other value and Charlie skips the extension. Required |
developer{ name, contact } | Who made it: your name and a way to reach you, both text. Required |
The basics
What most extensions use.
| Field | What it does |
|---|---|
toolslist of tool entries | Things Charlie can do with your extension, each backed by a handler file. The fields of each entry are listed below. Tools |
instructionstext | Rules Charlie reads once at startup and keeps in mind in every conversation. Instructions |
guidefile path | A longer how-to file Charlie reads only when it needs it, so it doesn't take up room in every conversation. Instructions |
settings{ component } | A settings panel you open from Charlie's Extensions list. At most one per extension. Settings |
connectionslist of connection entries | Outside services the extension signs in to, such as an email account; each entry has a name plus details that depend on the kind of connection. Connections |
Going further
Windows, live information, roles and personality.
| Field | What it does |
|---|---|
sidebar{ label, component } | A section of your own in Charlie's left sidebar. Surfaces |
topBar{ label, component, icon?, keepAlive?, thread?, tools? } | An item in Charlie's top bar that opens a full page of your own, optionally with its own chat docked underneath. Surfaces |
boot{ module } | Code that adds one short line of up-to-date information at the start of every conversation. Live state |
channels{ module } | Functions your extension's own open window can call back into while it stays open. Live state |
role"remotePersistence", "email" or "rdbmsPg" | Makes this extension the one provider of a shared job, such as email; only one switched-on extension can hold each role. Roles |
persistence{ module } | The code that does the storing, needed alongside role: "remotePersistence". Roles |
rdbms{ module } | The code that runs the database, needed alongside a database role such as "rdbmsPg". Roles |
requiresRolelist of role names | Roles this extension needs some other extension to provide; without one, Charlie skips it. Roles |
systemPrompt{ module } | Code that supplies Charlie's personality text, fresh on every turn. Personality |
workingWithMe{ module } | Code that supplies your preferences for how Charlie works with you. Personality |
bootInstructions{ module } | Code that supplies instructions once, at the start of each new conversation. Personality |
documentInstructions{ module } | Code that supplies the instruction Charlie follows when you use Document and close on a conversation. Personality |
Other
| Field | What it does |
|---|---|
dependsOnlist of extension names | Other extensions this one relies on; if any is missing or switched off, Charlie skips this one. Building blocks |
Older manifests may still have wrapInstructions or doneInstructions. Charlie ignores them.
Tool entries
Each item in the tools list is an object with these fields. See Tools.
| Field | What it does |
|---|---|
nametext | The tool's short name; Charlie sees it with the extension name in front, so run in bash becomes bash__run. Letters, numbers, _ and - only. Required |
descriptiontext | Tells Charlie what the tool does and when to use it. Required |
input_schemaJSON Schema object | The inputs Charlie can pass, as { "type": "object", "properties": { ... } }; use empty properties for a tool with no inputs. Required |
handlerfile path | The JavaScript file that runs when the tool is called. Required |
delivery"narrated", "injected" or "card" | How the result reaches the conversation; "narrated", the default, means Charlie reads it and talks about it, and "injected" makes your on-screen answer appear as your next message. Tools |
ui{ surface, component } | Something the tool shows on screen; surface is "modal", "popover", "chat-replacement" or "window". Surfaces |
confirmtrue or false | Asks you to Allow or Deny, showing what the tool is about to do, before it runs; meant for tools that delete or change things. Tools |
surfacetrue or false | Offers the tool only in the chat docked under this extension's own top-bar page. Surfaces |
roleScopedtrue or false | Drops the extension-name prefix, so the tool name doesn't reveal which extension provides it; only allowed when the manifest has a role. Roles |
mcptrue or false | Also lets Claude Code on the same computer call the tool, once you turn that on in Charlie's settings. Sharing outward |
popover is accepted but not yet shown by Charlie. A tool with mcp is still not shared if it uses confirm, surface, or a ui other than "window", because those need you in a Charlie conversation.
What a handler's ctx offers
A tool handler is called as (input, ctx). ctx is a set of services, already tied to your extension:
requestUI(props, surface?): shows the tool's on-screenuiand waits for your answer.getSettings(),setSettings(),updateSettings(),patchTextSettings(),appendSettings(): read and change your extension's saved settings.secrets.get(key),secrets.has(key): read a password or key you saved in the settings panel. Handlers can't write them.openWindow(props, options?): opens a window of your own that stays open after the turn.postToWindow(key, message): sends a message to a window that is already open.postToView(message),requestView(message): talk to your extension's top-bar page.persistence: stores documents in a folder on this computer.remotePersistence: stores documents through whichever extension holds theremotePersistencerole.rdbmsPg: runs SQL against the database provided by therdbmsPgrole.email(tool, args): a limited set of email actions through theemailrole. It has no way to send.vault(tool, args): a limited set of task actions in your SelfActual vault.connections,getConnectionToken(),getConnectionUrl(): reach the services your manifest declared inconnections.callModel(messages, options?): asks the model a question of its own, on your API key.sendToChat(text): puts text in your message box without sending it.runHiddenTurn(text): runs a turn you don't see. Use it only once you have already decided.readFile(path),writeFile(path, content): read and write files, within the same limits as Charlie's own file tools.turnImages,conversationImages: images pasted in this message, or anywhere in the conversation.caller:"charlie"or"mcp", so you can record who ran the tool.