Plugins & Hooks System
Relevant source files
The following files were used as context for generating this wiki page:
The Plugins and Hooks system in Clawdbot provides a modular architecture for extending the bot's core functionality. Plugins (also referred to as extensions) allow for the registration of new tools, gateway methods, CLI commands, and services, while Hooks enable the system to respond to specific internal events such as command execution or gateway startup. These systems are designed to be discoverable, manageable via CLI, and configurable through centralized configuration files.
Sources: src/hooks/bundled/README.md, src/cli/plugins-cli.ts:133-140, CLAUDE.md
Plugins System Architecture
The plugin system allows developers to package and distribute functionality as "extensions." Plugins can be installed from local paths, archives (.zip, .tgz), or npm package specifications. Once installed, they are discovered by the system and can be enabled or disabled via the configuration.
Plugin Discovery and Registration
Clawdbot discovers plugins by scanning global extension directories, workspace-specific directories (.clawdbot/extensions), and explicitly configured extra paths.
The diagram shows the sequential scanning of directories to identify plugin candidates before registering their components.
Sources: src/plugins/discovery.test.ts:56-65, src/cli/plugins-cli.ts:252-260
Component Types
Plugins can register multiple types of components within the bot's runtime:
- Tools: Functions available for AI agents to call.
- Gateway Methods: Custom API endpoints for the gateway.
- CLI Commands: Extensions to the
clawdbotcommand-line interface. - Services: Background processes that manage specific lifecycles.
Sources: src/cli/plugins-cli.ts:153-170, scripts/e2e/plugins-docker.sh:19-24
Hooks System Architecture
Hooks are event-driven handlers that execute in response to internal system triggers. They are defined by a HOOK.md metadata file and a handler.ts implementation.
Event Lifecycle
Hooks listen for specific event types, allowing for automation such as logging commands or persisting session memory.
| Event Type | Trigger Description |
|---|---|
command | Triggered by any slash command. |
command:new | Triggered specifically by the /new command. |
agent:bootstrap | Triggered before workspace bootstrap files are injected. |
gateway:startup | Triggered after gateway and channels have started. |
Sources: src/hooks/bundled/README.md:120-135
Hook Metadata (HOOK.md)
Every hook requires a HOOK.md file containing YAML frontmatter. This metadata defines the hook's identity and requirements.
---
name: session-memory
description: "Save session context to memory"
metadata:
{
"clawdbot": {
"emoji": "💾",
"events": ["command:new"],
"requires": { "bins": ["node"], "config": ["workspace.dir"] }
}
}
---
Sources: src/hooks/bundled/README.md:92-105, src/hooks/frontmatter.test.ts:167-185
Hook Execution Flow
When an event occurs, the system identifies all eligible and enabled hooks associated with that event and executes their handlers.
The sequence diagram illustrates how a system event triggers a filtered list of hooks, which can then push messages back to the user channel.
Sources: src/hooks/bundled/README.md:143-162, src/cli/hooks-cli.ts:40-47
Management and Configuration
Both plugins and hooks are managed primarily through the clawdbot CLI.
CLI Command Summary
| Command | System | Description |
|---|---|---|
clawdbot plugins list | Plugins | Lists all discovered plugins and their load status. |
clawdbot plugins install <path> | Plugins | Installs a plugin from a path, archive, or npm spec. |
clawdbot hooks list | Hooks | Displays available hooks and their readiness (eligibility). |
clawdbot hooks enable <name> | Hooks | Enables a specific hook in the config. |
clawdbot hooks check | Hooks | Validates requirements (binaries, env vars) for all hooks. |
Sources: src/cli/plugins-cli.ts:93-110, src/cli/hooks-cli.ts:286-300
Configuration Structure
Configurations are stored in ~/.clawdbot/clawdbot.json. Both systems track "installs" to manage updates and "entries" to track manual enablement states.
{
"hooks": {
"internal": {
"enabled": true,
"entries": { "session-memory": { "enabled": true } }
}
},
"plugins": {
"entries": { "my-plugin": { "enabled": true } }
}
}
Sources: src/hooks/bundled/README.md:75-90, src/cli/plugins-cli.ts:210-220
Summary
The Plugins & Hooks system enables Clawdbot to remain lean while allowing for significant extensibility. Plugins serve as the primary mechanism for adding new capabilities and integrations (Tools, Providers), while Hooks provide a powerful event-intercept system for automation and auditing. Both leverage a robust discovery mechanism and CLI-first management workflow to ensure ease of use for both developers and operators.