Think oh-my-zsh, but for pi.

---

Core Plugins

| | 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.

Installation

``bash
npm install -g @oh-my-pi/cli
`

Quick Start

`bash


Install a plugin

omp install @oh-my-pi/subagents

See what you've got

omp list

Search for more

omp search agents

Check for updates

omp outdated

Update everything

omp update
`

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 init

Disable a plugin for this project only

omp disable @oh-my-pi/subagents -l

Enable different features in this project

omp features @oh-my-pi/exa --set search -l

Override 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/exa

Install 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/exa

Enable/disable specific features

omp features @oh-my-pi/exa --enable websets
omp features @oh-my-pi/exa --disable search

Set exact feature list

omp features @oh-my-pi/exa --set search,websets

Override 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/exa

Get a specific value

omp config @oh-my-pi/exa apiKey

Set a value

omp config @oh-my-pi/exa apiKey sk-xxx

Reset to default

omp config @oh-my-pi/exa apiKey --delete

Override 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 | source

Merge 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 publish

Your plugin is now discoverable via omp search.

$3

`bash


Scaffold a new plugin

omp create my-plugin

Link for local development (changes reflect immediately)

omp link ./my-plugin

Test your plugin

omp list

When ready, publish

cd my-plugin && npm publish
`

Troubleshooting

`bash


Check for broken symlinks and conflicts

omp doctor

See which plugin installed a specific file

omp why ~/.pi/agent/agents/researcher.md

Temporarily disable a plugin

omp disable @oh-my-pi/subagents

Re-enable it later

omp enable @oh-my-pi/subagents

Disable just for this project

omp disable @oh-my-pi/subagents -l
``

Credits

Built for pi by @badlogic.

License

MIT