Building block 1 · The basics
Tools
A tool is one thing Charlie can do on your behalf, like running a command or opening a checklist. You describe it in your manifest, and a short handler file does the work when Charlie calls it.
What you'd use it for
- Let Charlie look something up for you, such as searching your email.
- Let Charlie change something, such as ticking an item on a checklist.
- Ask you a question with buttons, or ask your permission, before it acts.
- Open a window that stays on screen while you work.
In your manifest
This is the run tool from the bash extension, with the long descriptions trimmed. It runs a shell command and asks your permission first in a pop-up.
"tools": [ { "name": "run", "description": "Run a shell command on the operator's...", "input_schema": { "type": "object", "properties": { "command": { "type": "string", "description": "..." }, "cwd": { "type": "string", "description": "..." } }, "required": ["command"] }, "handler": "./handlers/run.js", "ui": { "surface": "modal", "component": "./build/ApprovalModal.js" }, "delivery": "narrated" } ]
What each part means
| Field | What it does |
|---|---|
name | The tool's short name inside your extension. Required |
description | Plain words telling Charlie what the tool does and when to use it. Charlie reads this to decide when to call it. Required |
input_schema | A JSON Schema listing the inputs Charlie must fill in, such as command above. Required |
handler | The path to the handler file, relative to your extension folder. Required |
ui | Optional. A screen the tool can show you: a surface (where it appears) and a component (the built file to show). See Surfaces. |
delivery | Optional. How your answer to a ui prompt shows up. narrated is the default. injected puts your answer into the chat as your own message. card is accepted but today behaves like narrated. |
roleScoped | Optional. Drops the extension-name prefix from the tool name. Only works in an extension that holds a role. |
mcp | Optional. Also offers the tool to Claude Code on the same computer, through Charlie's local bridge. |
confirm | Optional. Shows you the call and asks Allow or Deny before it runs. Meant for tools that delete things. |
The handler file
A handler is a small JavaScript file that exports one async function. Charlie calls it with two things: input, the values Charlie filled in from your schema, and ctx, a toolbox of things Charlie lets your code do. Whatever text you return is what Charlie sees as the result.
module.exports = async function open(input, ctx) {
if (!input || typeof input.slug !== 'string')
return 'Invalid input: slug is required.'
const checklist = await store.load(ctx, input.slug)
ctx.openWindow(
{ slug: checklist.slug, title: checklist.title },
{ instanceKey: checklist.slug, title: checklist.title }
)
return `Opened "${checklist.title}".`
}The parts of ctx you'll reach for most:
ctx.getSettings()reads what you saved in the extension's settings.ctx.secrets.get(key)reads a key or password you saved in the settings panel.ctx.requestUI(props)shows the tool'suiand waits for your answer.ctx.openWindow(props)opens a window that stays open after the reply.ctx.persistencestores data on your computer. See Data & storage.
How Charlie sees the name
Charlie sees each tool as the extension name, two underscores, then the tool name. Tool run in extension bash becomes bash__run. Use that full name when your instructions or descriptions mention a tool.
The one exception is a roleScoped tool. Gmail's email__search reaches Charlie as plain email__search, so the name doesn't reveal which email extension is behind it.
Things to know
- Charlie reads tools only at startup. Restart Charlie after adding or changing one.
- If another extension already uses the same full tool name, your tool is skipped. The rest of your extension still loads.
- A
roleScopedtool in an extension with noroleis skipped. - If your handler throws an error, Charlie reports the message back as the tool result. It won't crash Charlie.
mcpdoes nothing until you turn the bridge on in Settings > Tool use. It's also ignored for tools that need you mid-call: amodal,popoverorchat-replacementui, orconfirm.
See it in
Every field, in full: reference: tools.