Channels and Plugins

How the extension ecosystem connects Animus to the outside world.

Overview

Animus is designed to be extended. The core engine handles thinking, memory, and goals, while channels and plugins handle everything else: communication, integrations, and new capabilities.

  • Channels are communication adapters (Discord, SMS, API endpoints)
  • Plugins are capability extensions (weather, browser, home automation)

Both are installed at runtime by the user, not bundled with the engine.

Channels

A channel adapts a communication platform into a format Animus understands. It handles:

  1. Inbound: Receiving messages from the platform and forwarding them to the engine
  2. Outbound: Sending the agent's responses back to the platform
  3. Presence: Reporting online/offline status, typing indicators, etc.

Isolation Model

Each channel runs as an isolated child process with restricted Node.js permissions:

┌──────────────────────┐
│     Animus Engine     │
│  ┌────────────────┐  │
│  │  Channel Mgr   │  │
│  └───┬───┬───┬────┘  │
│      │   │   │       │
│  ┌───┴┐ ┌┴──┐ ┌┴───┐ │
│  │ DC │ │SMS│ │API │ │  ← child processes
│  └────┘ └───┘ └────┘ │
└──────────────────────┘

This means a misbehaving channel cannot crash the engine or access data from other channels.

Available Channels

Channel Platform
Discord Discord Bot
Twilio SMS via Twilio
Slack Slack Bot
API Compat REST endpoint

Channels and plugins are not yet publicly available. If you're interested in early access, join the Discord to request them directly.

Plugins

Plugins teach Animus new capabilities through a skills-first philosophy. Rather than dumping raw tool definitions on the agent, plugins provide structured skill descriptions that the agent can learn and compose.

Plugin Components

A plugin can include up to seven component types:

Component Purpose
Skills Natural language capability descriptions
Tools MCP server definitions for structured tool access
Context Additional data sources for mind sessions
Hooks Event listeners (on message, on tick, etc.)
Decisions Decision points the agent can invoke
Triggers Automated actions based on conditions
Agents Sub-agent definitions for delegation

The SKILL.md Standard

Every plugin starts with a SKILL.md file. This is a token-efficient, human-readable document that teaches the agent what the plugin does and how to use it:

---
name: weather
description: >
  Get current weather, forecasts, and severe weather alerts
  for any city. Use when the user asks about weather,
  temperature, rain, snow, or outdoor conditions.
allowed-tools: Bash
---

# Weather

## When to Use

Use this skill when the user asks about weather, forecasts,
temperature, or outdoor conditions for any location.

## Core Commands

curl -s "https://wttr.in/Tokyo?format=j1" | jq '.current_condition[0]'

Example output:
{
  "temp_C": "22",
  "FeelsLikeC": "24",
  "humidity": "65",
  "weatherDesc": [{"value": "Partly cloudy"}]
}

The agent reads this skill file and learns the capability without needing complex configuration. The frontmatter description is used by the SDK to decide when to load the skill, so include relevant trigger words.

Hot-Swap Lifecycle

Plugins can be installed and removed without restarting the engine:

  1. Install: Download package, verify signature, extract, register
  2. Activate: Load skill files, register tools, start hooks
  3. Deactivate: Unregister tools, stop hooks, clean up
  4. Remove: Delete package files, remove from registry

Credentials

Plugin credentials (API keys, tokens) are encrypted with AES-256-GCM and stored locally. The engine never sends credentials to any external service beyond the plugin's intended API.

Building Extensions