Plugin manager for pi - install and manage pi config plugins from git repos
npm install @oh-my-pi/cli

Think oh-my-zsh, but for pi.
---
| | Plugin | Description |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ |
|  | subagents | Task delegation with specialized sub-agents (task, planner, explore, reviewer) |
|  | lsp | Language Server Protocol for code intelligence, diagnostics, and refactoring |
|  | basics | Essential tools: rg (ripgrep), glob (fd), replace-all (sd), ast (ast-grep) |
|  | exa | Exa AI-powered web search, company/people lookup, and websets |
|  | perplexity | Perplexity AI search with Sonar models (fast and pro) |
|  | anthropic-websearch | Claude web search using Anthropic's built-in web_search tool |
|  | user-prompt | Interactive user prompting for gathering input during execution |
|  | init | /init command to generate AGENTS.md documentation for a codebase |
|  | metal-theme | A metal theme π€ |
---
Install community plugins with a single command. Themes, custom agents, slash commands, tools β sourced through npm/git, all a omp install away.
``bash`
npm install -g @oh-my-pi/cli
`bashInstall a plugin
omp install @oh-my-pi/subagents
How It Works
omp installs plugins globally via npm and sets up your pi configuration:
`
~/.pi/
βββ agent/ # Pi's agent directory
β βββ agents/ # Agent definitions (.md) - symlinked
β βββ commands/ # Slash commands (.md) - symlinked
β βββ hooks/omp/ # Hook loader
β β βββ index.ts # Generated loader - imports hooks from node_modules
β βββ tools/omp/ # Tool loader
β β βββ index.ts # Generated loader - imports tools from node_modules
β βββ themes/ # Theme files (.json) - symlinked
βββ plugins/
βββ package.json # Installed plugins manifest
βββ node_modules/ # Plugin packages (tools/hooks loaded directly from here)
βββ store/ # Runtime configs (survives npm updates)
`Non-tool files (agents, commands, themes) are symlinked via
omp.install entries.Tools and Hooks are loaded directly from node_modules via generated loaders. Plugins specify
omp.tools and/or omp.hooks pointing to their factory modules. This allows using npm dependencies without workarounds.Project-Level Overrides
While plugins are installed globally, you can customize their behavior per-project using
.pi/overrides.json:`bash
Initialize project overrides
omp initDisable a plugin for this project only
omp disable @oh-my-pi/subagents -lEnable different features in this project
omp features @oh-my-pi/exa --set search -lOverride config variables for this project
omp config @oh-my-pi/exa apiKey sk-project-specific -l
`Project overrides are stored in:
-
.pi/overrides.json - disabled plugins list
- .pi/store/ - feature and config overrides (merged with global, project takes precedence)The loader automatically merges project overrides at runtime.
Commands
| Command | Alias | Description |
| ---------------------- | ----- | -------------------------------------------------------- |
|
omp install [pkg...] | i | Install plugin(s). No args = install from package.json |
| omp uninstall | rm | Remove plugin and its symlinks |
| omp update [pkg] | up | Update to latest within semver range |
| omp list | ls | Show installed plugins |
| omp search | | Search npm for plugins |
| omp info | | Show plugin details before install |
| omp outdated | | List plugins with newer versions |
| omp doctor | | Check for broken symlinks, conflicts |
| omp link | | Symlink local plugin (dev mode) |
| omp create | | Scaffold new plugin from template |
| omp init | | Create .pi/overrides.json for project-local config |
| omp why | | Show which plugin installed a file |
| omp enable | | Enable a disabled plugin (-l for project override) |
| omp disable | | Disable plugin without uninstalling (-l for project) |
| omp features | | List or configure plugin features (-l for project) |
| omp config | | Get or set plugin configuration (-l for project) |
| omp env | | Print environment variables for shell eval (-l to merge) |Commands that modify plugin state (enable, disable, features, config, env) accept
-l/--local to use project-level overrides instead of global config.Feature Selection
Plugins can expose optional features that you can selectively enable. Use pip-style bracket syntax during install:
`bash
Install with default features (plugin decides which are on by default)
omp install @oh-my-pi/exaInstall with specific features only
omp install @oh-my-pi/exa[search]
omp install @oh-my-pi/exa[search,websets]Explicitly all features
omp install @oh-my-pi/exa[*]No optional features (core only)
omp install @oh-my-pi/exa[]Reinstall preserves feature selection unless you specify new ones
omp install @oh-my-pi/exa # Keeps existing features
omp install @oh-my-pi/exa[search] # Reconfigures to search only
`Plugins define which features are enabled by default via
default: true in their manifest. Features with default: false are opt-in.Manage features after install with
omp features:`bash
List available features and their current state
omp features @oh-my-pi/exaEnable/disable specific features
omp features @oh-my-pi/exa --enable websets
omp features @oh-my-pi/exa --disable searchSet exact feature list
omp features @oh-my-pi/exa --set search,websetsOverride features for current project only
omp features @oh-my-pi/exa --set search -l
`Plugin Configuration
Plugins can define configurable variables. Manage them with
omp config:`bash
List all variables for a plugin
omp config @oh-my-pi/exaGet a specific value
omp config @oh-my-pi/exa apiKeySet a value
omp config @oh-my-pi/exa apiKey sk-xxxReset to default
omp config @oh-my-pi/exa apiKey --deleteOverride for current project only
omp config @oh-my-pi/exa apiKey sk-project -l
`Variables with
env mappings can be exported as environment variables:`bash
Print shell exports
eval "$(omp env)"Fish shell
omp env --fish | sourceMerge project overrides
eval "$(omp env -l)"Persist in your shell config
omp env >> ~/.bashrc
`Creating Plugins
Plugins are npm packages with an
omp field in package.json:`json
{
"name": "my-cool-plugin",
"version": "1.0.0",
"keywords": ["omp-plugin"],
"omp": {
"install": [
{ "src": "agents/researcher.md", "dest": "agent/agents/researcher.md" },
{ "src": "commands/research.md", "dest": "agent/commands/research.md" }
]
},
"files": ["agents", "commands"]
}
`$3
For plugins with custom tools, use the
tools field instead of install:`json
{
"name": "@oh-my-pi/my-tools",
"version": "1.0.0",
"keywords": ["omp-plugin"],
"omp": {
"tools": "tools"
},
"files": ["tools"],
"dependencies": {
"some-npm-package": "^1.0.0"
}
}
`The
tools field points to a directory containing an index.ts that exports a tool factory. Tools are loaded directly from node_modules, so npm dependencies work normally.$3
For plugins with lifecycle hooks, use the
hooks field:`json
{
"name": "@oh-my-pi/my-hooks",
"version": "1.0.0",
"keywords": ["omp-plugin"],
"omp": {
"hooks": "hooks"
},
"files": ["hooks"]
}
`The
hooks field points to a directory containing an index.ts that exports a hook factory (HookFactory). Hooks subscribe to agent events like tool_call, session, etc.$3
Plugins can define optional features and configurable variables:
`json
{
"name": "@oh-my-pi/exa",
"version": "1.0.0",
"keywords": ["omp-plugin"],
"omp": {
"tools": "tools",
"runtime": "tools/runtime.json",
"variables": {
"apiKey": {
"type": "string",
"env": "EXA_API_KEY",
"description": "Exa API key",
"required": true
}
},
"features": {
"search": {
"description": "Web search capabilities",
"default": true
},
"websets": {
"description": "Curated content collections",
"default": false,
"variables": {
"defaultCollection": {
"type": "string",
"default": "general"
}
}
}
}
}
}
`The
runtime field points to a JSON file that the plugin imports to check feature state. omp stores user's feature selections in ~/.pi/plugins/store/ and injects them at load time, so they persist across npm updates.$3
`
my-cool-plugin/
βββ package.json
βββ agents/ # Agent definitions
β βββ researcher.md
βββ commands/ # Slash commands
β βββ research.md
βββ tools/ # Custom tools
β βββ search/
β βββ index.ts
βββ themes/ # Theme files
βββ dark.json
`$3
The
omp.install array maps source files to their destination in the agent directory:-
src: Path relative to the plugin root
- dest: Path relative to the pi config dir (usually starts with agent/)$3
1. Add
omp-plugin to your keywords array (required for omp search discovery)
2. Include source directories in the files array
3. Publish to npm: npm publishYour plugin is now discoverable via
omp search.$3
`bash
Scaffold a new plugin
omp create my-pluginLink for local development (changes reflect immediately)
omp link ./my-pluginTest your plugin
omp listWhen ready, publish
cd my-plugin && npm publish
`Troubleshooting
`bash
Check for broken symlinks and conflicts
omp doctorSee which plugin installed a specific file
omp why ~/.pi/agent/agents/researcher.mdTemporarily disable a plugin
omp disable @oh-my-pi/subagentsRe-enable it later
omp enable @oh-my-pi/subagentsDisable just for this project
omp disable @oh-my-pi/subagents -l
``MIT