Charliehub · by A.N.D.Why

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.

FieldWhat it does
name
text
The extension's name, and the prefix on all its tool names. Use lowercase letters, numbers and hyphens; the catalog accepts nothing else. Required
description
text
One sentence on what the extension does, shown in Charlie's Extensions list. Required
version
text
Three numbers with dots, like "1.0.0", with an optional suffix such as "1.0.0-beta". Required
tier
text
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.

FieldWhat it does
tools
list 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
instructions
text
Rules Charlie reads once at startup and keeps in mind in every conversation. Instructions
guide
file 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
connections
list 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.

FieldWhat 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
requiresRole
list 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

FieldWhat it does
dependsOn
list 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.

FieldWhat it does
name
text
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
description
text
Tells Charlie what the tool does and when to use it. Required
input_schema
JSON Schema object
The inputs Charlie can pass, as { "type": "object", "properties": { ... } }; use empty properties for a tool with no inputs. Required
handler
file 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
confirm
true 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
surface
true or false
Offers the tool only in the chat docked under this extension's own top-bar page. Surfaces
roleScoped
true 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
mcp
true 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: