plugins.md

Plugins

Autoloom keeps the plugin model intentionally close to tinyloom.

If you already understand tinyloom plugins, you already understand the plugin surface Autoloom exposes.

Important distinction:

• Autoloom core features are not plugins
• configured plugin module paths are tinyloom plugins
• the current first-party webhook server lives under autoloom/plugins/, but it is an Autoloom package module, not part of the tinyloom plugin lists

Plugin shape

Plugins are normal Python modules loaded from config.

Each plugin receives the full tinyloom Agent instance and can:

• register tools
• add hooks
• inspect config
• modify runtime state

This is the same "full agent access" model tinyloom uses.

Config

Autoloom has two tinyloom plugin lists.

Root session plugin paths live at the top level of ~/.autoloom/config.yaml:

plugins:
  - tinyloom.plugins.todo
  - mypackage.plugins.audit

Child subagent plugin paths live under autoloom.subagent_plugins:

autoloom:
  subagent_plugins:
    - tinyloom.plugins.todo
    - tinyloom.plugins.subagent
    - mypackage.plugins.audit

By default, the module's activate(agent) function is called.

Use module.path:function_name to select a different entrypoint.

Root vs subagent plugins

Autoloom uses different plugin sets for different levels:

• root Autoloom sessions load plugins
• child Autoloom subagent sessions load autoloom.subagent_plugins

Default behavior:

• root sessions include tinyloom.plugins.todo
• child subagent sessions include tinyloom.plugins.todo
• child subagent sessions also include tinyloom.plugins.subagent

That means the root session gets Autoloom's persisted subagent behavior, while the child session gets tinyloom's own subagent tool for one more delegation level.

What Autoloom loads itself

Autoloom always registers a few core runtime pieces itself:

• persistent task management
• session logging
• the root-session subagent tool that creates persisted child Autoloom sessions

These are runtime features, not tinyloom plugins.

User-configured plugins are loaded after those built-ins.

Building a tinyloom plugin for Autoloom

You build it the same way you would build a tinyloom plugin anywhere else: expose an activate(agent) function.

Small example:

from tinyloom.core.tools import Tool

def activate(agent):
    async def ping(_inp):
        return "pong"

    agent.tools.register(Tool(
        name="ping",
        description="Return pong.",
        input_schema={"type": "object", "properties": {}},
        function=ping,
    ))

Then either:

• install the plugin as a Python package into the same environment as autoloom (or uv run autoloom from a source checkout) so it can import it
• or for a source-checkout workflow, keep the module in your repo so uv run autoloom ... can import it directly

Example config:

plugins:
  - mypackage.plugins.ping

autoloom:
  subagent_plugins:
    - tinyloom.plugins.todo
    - tinyloom.plugins.subagent
    - mypackage.plugins.ping

How to set up plugin code locally

If you want to build plugins next to your Autoloom checkout, keep them importable Python modules.

Simple repo-local example:

autoloom/
  my_plugins/
    __init__.py
    review.py

with:

# my_plugins/review.py
def activate(agent):
    ...

and config:

plugins:
  - my_plugins.review

If the module imports successfully in the same environment as the autoloom command (or uv run autoloom from a source checkout), Autoloom can load it.

Relationship to the webhook feature

The webhook server is now isolated under autoloom.plugins.webhook, but it is still not part of the tinyloom plugin lists above.

It is an Autoloom-side integration that creates new root sessions from HTTP requests:

autoloom webhook serve

That keeps HTTP server lifecycle concerns out of the tinyloom plugin path while still letting webhook-triggered work become ordinary persisted Autoloom sessions.

When to use plugins vs files

Use plugins when you need:

• new tools
• hook-based behavior
• custom integration logic
• policy around tool calls or messages

Use plain files when you need:

• persistent tasks
• skills
• memories
• knowledge artifacts
• soul or heartbeat guidance

Autoloom prefers file-based behavior until executable logic is clearly necessary.

Guidance

Keep plugins small and specific.

Good plugin candidates:

• approval hooks
• extra tools for a private service
• logging or audit integrations layered on top of tinyloom agents
• task or workflow helpers that do not belong in core

Bad plugin candidates:

• replacing plain markdown memories with a database without a real need
• moving SOUL or heartbeat content into code
• duplicating tinyloom core behavior inside Autoloom