---
title: Claude Code plugins and pi packages
description: Load Claude Code plugins and pi packages in venom as they are, and see which parts of their formats venom supports.
section: plugins
order: 30
audience: [user, builder]
sources: [docs/plugins.md, cli/AGENTS.md, packages/harness/src/compat]
features: []
---

venom reads Claude Code's files and pi's packages without changes. It never writes under `.claude/` or `~/.claude`.

## pi packages

A pi package (a `package.json` with a `pi` key, or pi's conventional `extensions/` layout) is a venom plugin with only pi's resource kinds. Install it like any plugin:

```bash
venom plugin add npm:some-pi-package
```

A `venom` key in the same `package.json` overrides the `pi` key key by key.

## Claude Code plugins

A directory with `.claude-plugin/plugin.json` loads as a plugin. Plugins you installed with Claude Code are read from `~/.claude/plugins/installed_plugins.json` (honouring `enabledPlugins`) with no extra step. For any other directory:

```bash
venom plugin add ~/src/my-claude-plugin
```

| Claude Code | venom |
|---|---|
| `plugin.json` `name`, `version`, `description` | read |
| `commands/` (or `commands` as paths) | loaded as `/<plugin>:<command>` |
| `agents/` (or `agents` as directories) | loaded for the `task` tool; inline `mcpServers` in a plugin's agent are ignored, as in Claude Code |
| `skills/` (or `skills` paths) | loaded |
| `hooks/hooks.json`, `hooks` as a path or inline object | loaded (`command` and `prompt` hooks, for the events venom fires) |
| `.mcp.json`, `mcpServers` as a path or inline map | loaded |
| `${CLAUDE_PLUGIN_ROOT}` | expanded in hooks and MCP config |
| `commands` as an object map, `agents` as `.md` file paths, `hooks`/`mcpServers` arrays | not yet; use the default directories |
| no `.claude-plugin/plugin.json` | not recognised; add the manifest |
| `userConfig`, `${user_config.*}`, `CLAUDE_PLUGIN_OPTION_*`, `${CLAUDE_PLUGIN_DATA}` | not supported; use venom's `configSchema` |
| `lspServers`, `.lsp.json`, `outputStyles`, `workflows`, `channels`, `bin/` on PATH, `settings.json`, `dependencies`, `defaultEnabled` | not supported |
| `marketplace.json`, `/plugin install name@marketplace` | not supported; clone the plugin, then `venom plugin add <dir>` |

## The rest of a Claude Code project

Outside plugins, venom also reads a project's `CLAUDE.md`, `.claude/skills`, `.claude/commands`, `.claude/agents`, `.claude/settings.json` (permission rules, hooks, `env`, `model`) and `.mcp.json`. Project hooks, MCP servers and allow rules take effect only once you trust the project. Details per part: [Hooks](/docs/plugins/hooks.md), [Skills and commands](/docs/plugins/skills.md), [MCP servers](/docs/plugins/mcp.md).

## Related

- [Install and manage plugins](/docs/plugins/installing.md)
- [Write a plugin](/docs/plugins/writing.md)
