Using Plugins

Plugins are little add-on programs that sit between your editor and your agent and get to look at and even change every message that passes between the two. Want to block prompts that contain a secret word? Rewrite a file path before the agent ever sees it? A plugin can do all of that.

Using an Existing Plugin#

Plugins are tiny standalone files (they end in .wasm). To use one, you only need to tell Abyss where the file lives. You do that in the same config file you created in Getting Started, in a section called plugins.

Open your config file and add a plugins block that looks like this:

docker:
  image: "ghcr.io/sethcurry/abyss-pi:latest"
  agent_command:
    - pi-acp
  host_mounts:
    - source: "./"
    - source: "~/.pi"
      destination: "/root/.pi"

plugins:
  client:
    - path: ./my-plugins/prompt_filter.wasm

The new part is everything under plugins:. Let’s unpack it:

• plugins is the top-level section that holds all of your plugin settings.
• client is the list of plugins that run on your computer (the “client” side), before messages are sent into the container. Today every plugin is a client plugin, so this is always where they go.
• path is the location of the .wasm file on your computer. It can be a relative path (like the example above, relative to your config file) or an absolute one (like /home/you/plugins/prompt_filter.wasm).

Loading More Than One#

You can list as many plugins as you like. They run one after the other, in the order you wrote them, like a bucket brigade: the first plugin hands its result to the second, the second to the third, and so on, until the last one hands the message off to the agent (or back to your editor).

plugins:
  client:
    - path: ./my-plugins/prompt_filter.wasm
    - path: ./my-plugins/global_logger.wasm
    - path: /home/you/plugins/audit-trail.wasm

If a plugin drops a message (we’ll see how in a moment), the message never makes it to the plugins after it. Order matters, so put the plugin you trust most first if you want it to have the final say on what gets through.

Checking That It Loaded#

The easiest way to confirm your plugin is being picked up is abyss oneshot, which we met in Getting Started. When abyss loads a plugin it writes a line to the logs that looks like loading ACP plugin with the path next to it. If you see that line, you’re in business. If you instead see an error mentioning the plugin path, double-check the path is correct and that the file really exists there.

abyss oneshot -f ./abyss-agent.yaml "What is the capital of France?"

That’s all there is to using one. The rest of this guide is about building your own.

Where to Go Next#

• Custom Docker Images — pair your plugin with a custom agent image.
• Configuration — the full reference for every config option, including plugins.
• Troubleshooting — when your plugin loads but doesn’t behave, start here.