Writing a plugin

A plugin adds slash commands to a room. It is a Python file on the host's machine; everyone in the room sees its commands in the suggestions and can run the ones the plugin allows.

Create oneCopy Anchor Link

The easiest way is to ask the agent: it has a built-in plural-plugins skill with this whole guide, loads it when you ask for a plugin, and writes the file for you to install.

In the terminal client, as the host:

/plugins new hello      creates ~/.plural/plugins/hello.py from a template
/plugins                lists plugins, their commands and file paths
/plugins rm hello       deletes ~/.plural/plugins/hello.py and unloads it
/plugins reload         applies your edits without restarting the host

Open the file, edit it, run /plugins reload, then /hello in the room.

Write oneCopy Anchor Link

A plugin file defines setup(plural) and registers commands with plural.command:

def setup(plural):
    @plural.command("hello", description="Say hello")
    async def hello(ctx):
        await ctx.reply(f"Hello {ctx.author}! You wrote: {ctx.args or 'nothing'}")

    @plural.command("review", description="Review the current diff", host_only=True)
    async def review(ctx):
        diff = await ctx.run("git", "diff")
        await ctx.prompt(f"Review these changes:\n{diff}")

plural.command(name, description="", usage="", host_only=False) registers an async handler for /name. Names use a-z, 0-9, - and _, and cannot reuse a built-in command or another plugin's command. host_only=True refuses the command to everyone but the host. Viewers cannot run commands.

The handler gets a context:

A side question that should not touch the conversation, answered only to the person who asked:

@plural.command("btw", description="Ask something on the side", usage="/btw <question>")
async def btw(ctx):
    answer = await ctx.ask(ctx.args)
    await ctx.show("btw", answer)

Asking before acting:

@plural.command("deploy", host_only=True)
async def deploy(ctx):
    target = await ctx.select("where to?", ["staging", "prod"])
    if target is None or not await ctx.confirm(f"deploy to {target}?"):
        return
    await ctx.notify("deploying")
    await ctx.reply(await ctx.run("./deploy.sh", target))

A question goes only to the person who ran the command: the terminal opens it under the composer (esc closes it), the web client puts it first in the inbox. One question is open per person at a time.

ctx.ask sees the conversation so far, cannot call tools, and adds nothing to the history; its tokens count as session usage. ctx.prompt goes through the same path as a typed prompt: in review mode a guest's prompt becomes a proposal, write and exec actions still wait for the host, and PLURAL_GUEST_RUN_TOKENS applies.

Tools for the agentCopy Anchor Link

A plugin can also give the agent a tool. The agent calls it like any other tool, and its return value is the tool's result:

def setup(plural):
    @plural.tool(
        "ticket",
        description="Look up a ticket by key: title, status and assignee",
        parameters={"key": "Ticket key, for example PLR-123"},
        risk="read",
    )
    async def ticket(args, ctx):
        ctx.log("asking the tracker")
        return await ctx.run("tracker", "show", args["key"])

plural.tool(name, description, parameters=None, risk="read", exposure="deferred"):

The handler receives the arguments as a dict and a context with ctx.workspace, ctx.log(text), which streams progress to the room, and await ctx.run(*argv). A string result goes to the model as is, any other value as JSON. If the handler raises, the model gets the error as the tool's result.

Keeping stateCopy Anchor Link

Module variables reset on /plugins reload. What must last goes in plural.store, a JSON file of the plugin's own at ~/.plural/plugins/.data/<name>.json:

runs = plural.store.get("runs", 0)
plural.store.set("runs", runs + 1)
plural.store.delete("old")
plural.store.all()

Values are anything JSON can hold. Every set and delete writes the file at once, through a temporary file, and a store holds at most 1 MB. /plugins rm leaves the file, so a plugin added back finds its data.

A line in the side panelCopy Anchor Link

plural.status(text) keeps a short line for the plugin in the side panel, under the session, for everyone in the room: ci tests 3/3 ✓. Call it from a command, a tool or a hook; an empty text removes the line. It is one line of at most 80 characters, the host shows at most one change a second (the latest wins), and the line goes away when the plugin is removed or fails to load.

NextCopy Anchor Link