Getting started
Your first extension
In about ten minutes you will teach Charlie a new habit, then give it a new ability. All you need is a text editor.
The example is called tea-time. First it reminds Charlie that 4pm is for tea. Then it adds a tool Charlie can call to suggest a tea.
Part 1: an extension with instructions only
The simplest extension is one file. It adds a few lines to what Charlie always knows, and nothing else.
Make a folder
Charlie looks for extensions in one place:
~/ClaudeShared/charlie/extensions/. Each extension gets its own folder there. Make one calledtea-time.~/ClaudeShared/charlie/extensions/ tea-time/ manifest.jsonWrite the manifest
Inside the folder, create a file named
manifest.jsonand paste this in. Put your own name and email indeveloper.{ "name": "tea-time", "description": "Reminds Charlie that 4pm is for tea.", "version": "0.1.0", "tier": "core", "developer": { "name": "Your Name", "contact": "you@example.com" }, "instructions": "When planning the operator's afternoon, keep 4:00 to 4:20pm free for tea." }Every line above the last one is required. Charlie skips any extension that is missing one of them:
name: what the extension is called. Use lowercase letters, numbers and hyphens.description: one sentence on what it does.version: three numbers with dots, like0.1.0.tier: always"core"for now.developer: yournameand acontact.
instructionsis the useful part. Charlie reads it once at startup and keeps it in mind in every conversation.Restart Charlie
Charlie only looks for extensions when it starts. Quit Charlie completely and open it again. New extensions are switched on by default, so there is nothing else to turn on.
Try it
Ask Charlie to help plan your afternoon. It should leave 4:00 to 4:20 free for tea.
Part 2: add a tool
Instructions change what Charlie knows. A tool gives Charlie something it can do. A tool has two parts: an entry in the manifest that tells Charlie when to use it, and a small JavaScript file, called a handler, that does the work.
Add the tool to the manifest
Add a
toolslist tomanifest.json. Remember the comma after theinstructionsline.{ "name": "tea-time", "description": "Reminds Charlie that 4pm is for tea.", "version": "0.2.0", "tier": "core", "developer": { "name": "Your Name", "contact": "you@example.com" }, "instructions": "When planning the operator's afternoon, keep 4:00 to 4:20pm free for tea.", "tools": [ { "name": "suggest", "description": "Suggest a tea to drink. Call this when the operator asks what tea to have.", "input_schema": { "type": "object", "properties": { "caffeine": { "type": "boolean", "description": "false for caffeine-free teas only." } } }, "handler": "./handlers/suggest.js", "delivery": "narrated" } ] }What each part does:
name: the tool's short name. Charlie sees it astea-time__suggest, with the extension name and two underscores in front.description: tells Charlie what the tool does and when to call it. This is the most important line to get right.input_schema: the inputs Charlie can pass in, written as JSON Schema. It is always an object with"type": "object"and apropertieslist. A tool with no inputs still needs one, with empty properties:{ "type": "object", "properties": {} }.handler: where the handler file is, starting from the extension's own folder.delivery: how the result reaches the conversation. Leave it as"narrated", which is also what you get if you leave it out. Charlie reads the result and talks about it in its reply. The other values,"injected"and"card", are for tools that show you a question on screen and wait for your answer.
The version went up to
0.2.0. Charlie does not require that, but it is a good habit whenever the extension changes.Write the handler
Make a folder called
handlersinsidetea-time, and in it a file calledsuggest.js:// tea-time__suggest: pick a tea at random. const TEAS = [ { name: 'Assam', caffeine: true }, { name: 'Earl Grey', caffeine: true }, { name: 'Sencha', caffeine: true }, { name: 'Peppermint', caffeine: false }, { name: 'Rooibos', caffeine: false }, { name: 'Chamomile', caffeine: false } ] module.exports = async function suggest(input, ctx) { const choices = input && input.caffeine === false ? TEAS.filter((t) => !t.caffeine) : TEAS const pick = choices[Math.floor(Math.random() * choices.length)] return `How about ${pick.name}?` }This follows the same pattern as the handlers in Charlie's own extensions, such as
bash/handlers/rules.js:- The file sets
module.exportsto one async function. Charlie calls it each time the tool is used. - The function gets two things, always in this order:
input, the values Charlie passed in that match yourinput_schema, andctx, a set of services Charlie offers your code. This tool doesn't needctx. The manifest reference lists what it offers. - Whatever the function returns is the tool's result. Return a string. Anything else is turned into JSON text first.
- If the function throws an error, Charlie gets a short failure message instead of a result, and the full error goes to the console.
Charlie also accepts a function exported under the name
handle, butmodule.exportsis what every real extension uses.The finished folder looks like this:
tea-time/ manifest.json handlers/ suggest.js- The file sets
Restart and try it
Restart Charlie again, then ask: "What tea should I have? Nothing with caffeine." Charlie should call
tea-time__suggestand offer you something like Rooibos.Charlie loads a handler file the first time the tool runs and keeps it. If you edit
suggest.jslater, restart Charlie to pick up the change.
If it doesn't show up
When Charlie starts, it checks each folder in the extensions folder. A problem in one extension never stops the others. Charlie skips that extension, or just that tool, and moves on.
First, open the Extensions page in Charlie's settings. If tea-time is not listed at all, Charlie skipped the whole extension. If it is listed, check that it is switched on.
Charlie skips the whole extension when:
- The folder has no file named exactly
manifest.json. manifest.jsonis not valid JSON. A missing comma or an extra one at the end of a list is the usual cause.name,description,version,developer.nameordeveloper.contactis missing, orversionis not three numbers like1.0.0.tieris anything other than"core".- It lists another extension in
dependsOnthat is not installed or is switched off. - It claims a role another switched-on extension already holds, or needs a role that no extension provides.
Charlie skips a single tool when its name, with the extension prefix, is already taken by another tool.
If the tool shows up but fails when used, check that handler points at the right file, starting with ./ from the extension folder, and that the file sets module.exports to a function.
Where the error messages go
Charlie writes each of these problems to its console as a line starting with [extensions] and the extension's name, saying what was wrong and that it was skipped. You can see the console when Charlie is started from a terminal. These messages do not appear in the chat.
Where next
- Building blocks: everything else an extension can add, one page each.
- Tools: more on writing tools and handlers.
- Manifest reference: every field in one place.
- The checklist example: a real extension with tools, a window and a sidebar.
- Publish to the catalog: share your extension with other people.