Guide: Write Your First Extension

Start an extension, try it in the chat, change it live, and share it.

Guide: Write Your First Extension

An extension adds to the chat and the app without touching the framework: a command, a key, a status item, a tool, a web page slot. This guide takes one from nothing to something you can share. It needs a project (bxAgents new makes one).

1. Start it

bxAgents add extension standup --with=command,key --description="Daily standup"

That writes extensions/standup.bx: one class with a /standup command and a key, each with a TODO to fill in. Leave --with out at a terminal and it asks what to bring. If you tick a scheduler, gateway, tool, skill or web files, it makes a folder (extensions/standup/Extension.bx plus those files) instead.

2. Try it

bxAgents chat

Type /extensions to see it loaded, then /standup. A problem in the file shows up there with its reason, so a typo is never silent.

3. Change it live

Edit the command in extensions/standup.bx, then type /reload in the same chat. The change is in, with no restart. A setting goes in configure():

function configure() {
	variables.settings = { greeting : "Good morning" }
}

Read it in the command as settings.greeting. Agent.yaml (or your own ~/.bxagents/bxAgents.yml) can change it without touching the code:

extensions:
  standup:
    greeting: "Hello team"

4. Use it in every project

An extension in the project's extensions/ belongs to that project and goes into its built app. To have one in your own terminal chat everywhere, link it:

bxAgents extensions link ./extensions/standup.bx

It now loads from where you edit it, in every chat on this machine, and /reload picks up a change.

5. Share it

An extension is a folder or a file, so sharing is giving someone that:

• zip the folder, or push it to a GitHub repository;
• they run bxAgents extensions install ./standup.zip, or bxAgents extensions install you/standup.

They see what it adds and what its code mentions, and say yes before anything is placed. The install is recorded in extensions.lock.json, which they commit; the extension itself is restored from it at build time.

Where next

• Extensions lists everything an extension can bring, with the exact shape of each.
• examples/extensions-agent has a working extension of each kind.