Plugins

The ArgentOS plugin system — extend agent behavior with argent.plugin.json manifests.

Overview

Plugins are extensions that modify agent behavior at the runtime level. They can register new tools, inject system prompt context, intercept messages, and hook into the agent lifecycle. Plugins are the lowest-level extension mechanism in ArgentOS.

Plugin Location

Plugins are stored in the extensions directory:

~/.argentos/extensions/
├── response-validator/
│   └── argent.plugin.json
├── summarize-tts-enforcer/
│   └── argent.plugin.json
├── canvas-docs-enforcer/
│   └── argent.plugin.json
└── openclaw-mem/
    └── argent.plugin.json

Plugin Manifest

Every plugin has an argent.plugin.json manifest:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A custom plugin",
  "enabled": true,
  "tools": [
    {
      "name": "my_tool",
      "description": "Does something useful",
      "schema": {
        "type": "object",
        "properties": {
          "input": { "type": "string" }
        }
      }
    }
  ],
  "systemPromptInjection": "Additional instructions for the agent...",
  "hooks": {
    "onMessage": "handlers/on-message.js",
    "onResponse": "handlers/on-response.js"
  }
}

Plugin Capabilities

Tool Registration

Plugins can register new tools that become available to the agent:

{
  "tools": [
    {
      "name": "weather_lookup",
      "description": "Look up current weather for a location",
      "schema": { ... },
      "handler": "handlers/weather.js"
    }
  ]
}

System Prompt Injection

Plugins can inject text into the agent's system prompt:

{
  "systemPromptInjection": "When creating documents, always use doc_panel for dashboard documents and canvas for external screens."
}

Lifecycle Hooks

Plugins can hook into agent events:

Hook	When
`onMessage`	Before a message is processed
`onResponse`	After the agent generates a response
`onToolCall`	Before a tool is executed
`onStartup`	When the gateway starts
`onShutdown`	When the gateway stops

Tool Name Conflicts

When multiple plugins register tools with the same name, the built-in tool wins. For example, if a plugin registers memory_store but the builtin already has it, the plugin's version is skipped.

This is important to understand when working with legacy plugins that may have been superseded by built-in functionality.

Managing Plugins

# List installed plugins
argent plugins list

# Enable/disable a plugin
argent plugins enable <name>
argent plugins disable <name>

# Install from a directory
argent plugins install ./my-plugin

On this page