The plugins crate provides a robust extensibility layer for claw, allowing the agent's capabilities to be augmented via external tools, commands, and lifecycle hooks. The system supports multiple distribution methods and enforces a strict manifest-based security model.
The plugin system is centered around the PluginManager and the PluginRegistry. It categorizes extensions into three distinct types defined by the PluginKind enum rust/crates/plugins/src/lib.rs25-29
| Plugin Kind | Description | Marketplace ID |
|---|---|---|
Builtin | Hardcoded core functionality integrated directly into the binary. | builtin |
Bundled | Shipped alongside the distribution in a dedicated bundled/ directory. | bundled |
External | Third-party plugins installed from local paths or Git repositories. | external |
Sources: rust/crates/plugins/src/lib.rs15-17 rust/crates/plugins/src/lib.rs41-50
The following diagram maps the high-level plugin concepts to the specific Rust structs and files that implement them.
Plugin System Entity Map
Sources: rust/crates/plugins/src/lib.rs25-29 rust/crates/plugins/src/lib.rs114-129 rust/crates/plugins/src/lib.rs19-21
Every plugin must provide a plugin.json manifest rust/crates/plugins/src/lib.rs20-21 This file defines the plugin's identity, required permissions, and the surface area it integrates with (hooks, tools, or commands).
The PluginManifest rust/crates/plugins/src/lib.rs114-129 includes:
name, version, and description.PluginPermission levels (Read, Write, Execute) rust/crates/plugins/src/lib.rs133-137hooks: Scripts to run during the tool execution lifecycle rust/crates/plugins/src/lib.rs64-72tools: Definitions for new model-callable tools rust/crates/plugins/src/lib.rs166-175commands: New slash commands for the REPL rust/crates/plugins/src/lib.rs215-219Tools defined by plugins must specify a PluginToolPermission rust/crates/plugins/src/lib.rs177-183:
read-onlyworkspace-writedanger-full-accessSources: rust/crates/plugins/src/lib.rs114-203
Plugins can intercept the ConversationRuntime loop using hooks. These are shell commands or scripts triggered at specific stages of tool execution rust/crates/plugins/src/hooks.rs10-14
The HookRunner aggregates hooks from all enabled plugins via the PluginRegistry rust/crates/plugins/src/hooks.rs70-72 When a hook is triggered, the system executes the configured command and passes context via environment variables like HOOK_EVENT, HOOK_TOOL_NAME, and HOOK_TOOL_INPUT rust/crates/plugins/src/hooks.rs190-196
Hook Integration Flow
Sources: rust/crates/runtime/src/conversation.rs224-232 rust/crates/plugins/src/hooks.rs75-84 rust/crates/plugins/src/hooks.rs186-212
For detailed implementation specifics, refer to the following child pages:
Covers the installation process (Git vs Local), the install_root directory structure, the InstalledPluginRegistry persistence in installed.json, and how tools are aggregated into the global registry. Detailed explanation of PluginTool subprocess execution and environment variables.
Detailed look at the bundled/ plugins provided with claw. Covers the HookEvent stages (PreToolUse, PostToolUse, PostToolUseFailure), how scripts signal a Deny outcome via exit codes, and the HookAbortSignal mechanism for cancelling long-running hooks.
Sources: rust/crates/plugins/src/lib.rs1-130 rust/crates/plugins/src/hooks.rs1-120