Writing slash commands

A slash command is a small action a person runs by sending /name in a chat's message box. DataMind Oda performs it directly, without starting a model turn, and its answer appears in the chat. Slash commands and references explains how people run commands; this page is for the person who writes one.

Commands come from plugins: Oda ships with its own set, and a plugin can register more. Oda's built-in commands, such as /plan and /goal, are listed in Chat with Oda.

What a command provides

A definition carries five parts:

Part	What it is	The rules
Name	How people call the command, after the slash	Lowercase; starts with a letter; then letters, digits, underscores and dashes
Description	The line the menu shows for the command	A non-empty piece of text
Input hint	A short hint for what to type after the name	A non-empty piece of text
Attachments	Whether the command accepts files and images	On or off
Handler	The code that runs when the command is sent, and returns its result	Required

Oda checks the definition when the command is registered, and refuses one that does not fit: a name outside the shape, an empty description or hint, or a missing handler.

What counts as a command

A command starts at the very start of the message: a slash, then a lowercase name.
The name stops at the first whitespace character or at the end of the message. A name starts with a letter and then holds letters, digits, underscores and dashes.
Everything after the name is the command's input, passed on exactly as typed. Nothing is trimmed or split into arguments, and the whitespace that separates the name from the input stays in the input.
/goal alone runs with an empty input; /goal create the thing hands the command create the thing.

Nothing runs as a command when the shape does not hold:

goal carries no slash, and /goal starts with a space instead.
/ is a bare slash with no name.
/Goal uses a capital, and names are lowercase.
/goal/path holds a slash inside the name.
/goal🔥 uses a character outside the allowed set.

None of these shapes runs a command, and neither does a message that names a command which is not registered. In both cases, the message goes to Oda as ordinary text.

Registering a command

Registering a definition returns a handle; keep it to unregister the command later.
Registration ends with the plugin that made it: when the plugin is removed or reloaded, its commands go with it.
Two commands cannot share a name in the same scope; registering a name that is already in use is refused.
A command registered for one agent shadows the general command of the same name for that agent only. Everywhere else, the general command stays in force.
The list people read is sorted by name and frozen, so it cannot change halfway through a read. Add and remove commands by registering and unregistering; Oda is notified when commands are added or removed.

What a command returns

Every run ends with one result: a success or an error.
A success can carry a line of text; an error must carry a non-empty line. The line is what the chat shows.
Oda checks every result: a result that is neither a success nor an error is refused, and so is an empty error line.
A handler that throws ends the command as an error.
When someone cancels a command, Oda stops waiting for the handler and the command ends as an error reading command aborted. A cancellation that lands first means the handler never runs; a side effect the handler already started is not rolled back.

Files and images

A command takes files and images only when its attachments part is on. When it is on, the items reach the command in the order they were added.
When a message carries attachments for a command that did not take them, nothing runs: the refusal names the command and reads /<name> does not accept attachments.
A missing upload, and an image batch over the message's limit, are refused just the same, and always before the handler runs: your command never sees the items.

What a command does not do

A command never reaches the model: the menu listing, the input and the answer all stay out of every model request, so running one adds no model tokens.
A command never runs in work without people: a run with no interface, such as one started by an automation client, has no slash commands.

Questions, answered

What do I need to register a command?

Five parts: a name, a description, an input hint, an attachments choice and a handler. Oda checks them at registration and refuses a name outside the shape, an empty description or hint, or a missing handler.

Which names are allowed?

A name is lowercase, starts with a letter, and then holds letters, digits, underscores and dashes. A capital or a slash inside a name does not fit the shape, so such a name cannot register.

What does my command receive as its input?

Everything after the name, exactly as typed: nothing is trimmed, split or resolved, and the whitespace after the name is part of it. /goal alone gives an empty input; /goal create the thing gives create the thing.

Can two commands share a name?

Not in the same scope: registering a name that is already in use is refused. The exception is a command registered for one agent, which shadows the general command of that name for that agent only.

How do I remove a command?

Unregister it through the handle you got at registration. Its registration also ends with the plugin that made it, so removing or reloading that plugin takes its commands with it.

What should my command return?

A success or an error. A success can carry a line of text; an error must carry a non-empty one. That line is what the chat shows, and a result outside the two shapes is refused.

What happens if my handler throws?

It ends the command as an error, reported like any other failed run.

What happens to files and images sent to my command?

Nothing reaches the command unless its attachments part is on. Without it, the message is refused before the handler runs, with a line such as /<name> does not accept attachments. With it on, attachments arrive in the order they were added.

Does the model see what my command does?

No. The menu listing, the input and the answer all stay out of model requests. Running a command adds no model tokens, and nothing it says reaches the model.

What happens if someone cancels my command?

Oda stops waiting for the handler, and the command ends as an error reading command aborted. A cancellation that lands first means the handler never runs; a side effect the handler already started is not rolled back.

Do commands work in runs without a person?

No. A command needs someone to send it: a run with no interface, such as one started by an automation client, has no slash commands.