---
title: Plugins and extensions
description: Extend venom with plugins, pi packages, Claude Code plugins, hooks, sounds, skills, MCP servers, themes, templates and roles.
section: plugins
order: 0
audience: [user, builder, agent]
sources: [docs/plugins.md, docs/hooks.md, packages/harness/src/plugin.ts, packages/harness/src/plugins]
features: []
---

venom is built on [pi](https://github.com/earendil-works/pi), and its extension points are pi's. A venom plugin is a pi extension loaded by pi's own loader, so a pi package works as a venom plugin without changes, and Claude Code plugins load through venom's compatibility layer.

| You want to | Use | Runs code? |
|---|---|---|
| Add a tool, slash command, leader key, renderer or HUD field | a plugin | yes, in-process |
| Run a shell command or play a sound when the agent finishes, fails or needs you | a hook (`hooks:` in venom.yaml) | a shell command |
| Teach the agent a procedure it loads on demand | a skill (`SKILL.md`) | no |
| Give the agent tools from another process or service | an MCP server | yes, as a separate process or remote service |
| Change venom's colours | a theme file | no |
| Start a recurring kind of job from a saved setup | a template | no |
| Add a standing scheduled agent to `venom serve` | a plugin role | no (a schedule entry) |

A plugin can bundle all of these: its manifest lists extensions, skills, commands, agents, prompts, themes, hooks, MCP servers and roles.

## Trust in one paragraph

A plugin's extension code runs inside venom with your user's rights. venom's permission gate judges the model's tool calls, including a plugin's tools, but it does not sandbox the plugin's own code. Plugins you install yourself load because you installed them. Plugins, hooks and MCP servers that come from a project's files load only after you trust the project (`venom trust`, or the dialog venom shows the first time), and a change to any of them suspends that trust until you confirm it again. Themes, skills and templates are data, not code.

## Built-in plugins

The CLI ships some of its own features as plugins: the terminal charts (`charts`), the pull requests pane (`github-prs`) and `/rewind`. `venom plugin list` shows them as `[builtin]`, and `venom plugin disable <name>` turns one off.


## In this section {#in-this-section}

- [Install and manage plugins](/docs/plugins/installing.md): Add plugins from a directory, npm, git or your org's marketplace, turn them on and off, configure them and see why one did not load.
- [Write a plugin](/docs/plugins/writing.md): Scaffold, write, test and publish a venom plugin with tools, commands, leader keys, block renderers, HUD fields and panel sections.
- [Claude Code plugins and pi packages](/docs/plugins/claude-code-plugins.md): Load Claude Code plugins and pi packages in venom as they are, and see which parts of their formats venom supports.
- [Hooks and venom's events](/docs/plugins/hooks.md): Run a command or play a sound when the agent finishes, fails, needs approval or completes a step, and use Claude Code's hooks as they are.
- [Sounds](/docs/plugins/sounds.md): Hear when venom is done, failed or needs approval, pick or replace the sounds, set quiet hours and choose the player.
- [Skills and slash commands](/docs/plugins/skills.md): Add skills the agent loads on demand and slash commands from markdown files, list what is loaded, and find skills the agent asked for but did not have.
- [MCP servers](/docs/plugins/mcp.md): Give the agent tools from MCP servers in Claude Code's .mcp.json format, and use your organisation's approved servers with sign-in and tool pins.
- [Themes](/docs/plugins/themes.md): Pick one of venom's sixteen colour themes, tweak one, write your own theme file or ship themes in a plugin.
- [Session templates and learned templates](/docs/plugins/templates.md): Start a session from a saved setup (prompt, gear, mode, tools, checks) and save jobs you repeat as templates.
- [Team library](/docs/plugins/library.md): Use your organisation's shared prompts as /org commands and its skills in every session, offline from a cache, and hide what you do not want.
- [Plugin roles](/docs/plugins/roles.md): Install a standing agent a plugin ships (cron, prompt, mode, budget) as a reviewed schedule entry that venom serve runs.
- [Terminal charts](/docs/plugins/charts.md): Draw bar, line, area, scatter, sparkline, histogram, heatmap, pie, gauge and timeline charts in the terminal from a small YAML or JSON spec.
- [Pull requests pane](/docs/plugins/pr-pane.md): Browse the repository's open pull requests beside the chat and approve, comment, request changes or merge through the GitHub CLI.
- [venom-board, GitHub issues as an agent control plane](/docs/plugins/venom-board.md): Run a GitHub issue board where agents file ranked proposals, an owner approves with labels, and agents build, gate and merge what was approved.
