Charliehub · by A.N.D.Why

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

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.

bash / manifest.json
"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

FieldWhat it does
nameThe tool's short name inside your extension. Required
descriptionPlain words telling Charlie what the tool does and when to use it. Charlie reads this to decide when to call it. Required
input_schemaA JSON Schema listing the inputs Charlie must fill in, such as command above. Required
handlerThe path to the handler file, relative to your extension folder. Required
uiOptional. A screen the tool can show you: a surface (where it appears) and a component (the built file to show). See Surfaces.
deliveryOptional. 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.
roleScopedOptional. Drops the extension-name prefix from the tool name. Only works in an extension that holds a role.
mcpOptional. Also offers the tool to Claude Code on the same computer, through Charlie's local bridge.
confirmOptional. 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.

checklist / handlers/open.js (trimmed)
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:

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

See it in

Every field, in full: reference: tools.