/metaphorics/oh-my-pi-plugin-morph

Wiki directory

Browse AI-generated documentation for any repository.

Setup and Installation Guide

Relevant source files

The following files were used as context for generating this wiki page:

Introduction

The oh-my-pi-plugin-morph is an extension for the oh-my-pi (omp) coding agent that integrates Morph LLM capabilities. This plugin provides advanced tools for code editing (fast_edit), natural language codebase searching (codebase_warpsearch), public GitHub repository analysis (github_warpsearch), and context compaction (fastcompact).

The installation process involves configuring a Morph API key and integrating the plugin into an oh-my-pi environment using either local linking or remote installation. Once installed, the plugin utilizes environment variables to toggle specific features and define runtime behavior, such as compaction ratios and routing hints for the agent.

Sources: README.md:1-12, src/index.ts:18-37

Installation Procedures

Prerequisites

Before installation, users must obtain a Morph API key from the Morph Dashboard.

Sources: README.md:18-20

Installation Methods

The plugin can be installed via the omp CLI using three primary methods:

Local Linking: Used for development or when the repository is cloned locally.
```
omp plugin link .
```
Remote Installation: Directly installs the plugin from the GitHub repository.
```
omp plugin install https://github.com/metaphorics/oh-my-pi-plugin-morph
```
One-off Execution: Running the extension without a permanent installation for testing.
```
MORPH_API_KEY=sk-... omp -e ./src/index.ts -p "List the Morph tools you can call."
```

Sources: README.md:22-38

Dependency and Manifest Configuration

The plugin is structured as a Bun-compatible module. The package.json defines the entry point for oh-my-pi extensions.

Field	Value	Description
`name`	`oh-my-pi-plugin-morph`	The package identifier.
`omp.extensions`	`["./src/index.ts"]`	Defines the module path loaded by the host.
`type`	`module`	Specifies ESM module type.

Sources: package.json:2-10

Configuration and Environment Variables

Configuration is handled exclusively via environment variables. While tools remain registered without a valid MORPH_API_KEY, they will return runtime guidance indicating unavailability until the key is provided.

Core Configuration Options

Variable	Default	Description
`MORPH_API_KEY`	`undefined`	Required for remote tool execution.
`MORPH_EDIT`	`true`	Toggles the `fast_edit` tool.
`MORPH_WARPGREP`	`true`	Toggles local `codebase_warpsearch`.
`MORPH_WARPGREP_GITHUB`	`true`	Toggles `github_warpsearch`.
`MORPH_COMPACT`	`true`	Toggles the `session_before_compact` history hook.
`MORPH_FASTCOMPACT`	`true`	Toggles the standalone `fastcompact` tool.
`MORPH_ROUTING_HINT`	`true`	Toggles system prompt hints for tool selection.
`MORPH_COMPACT_RATIO`	`0.3`	Compression ratio for Morph Compact (0.05 to 1.0).

Sources: README.md:42-53, src/config.ts:21-39

System Flow: Plugin Initialization

The following diagram illustrates how the plugin initializes and registers components based on the environment configuration.

Generating architecture diagram...

The plugin factory evaluates environment flags during the morphPlugin(pi) call, conditionally registering tools and event handlers.

Sources: src/index.ts:18-37, src/routing.ts:46-93

Runtime Environment & Development

Release Discipline

Any update to the plugin requires synchronized changes to ensure version consistency:

The version in package.json must match PLUGIN_VERSION in src/config.ts.
CHANGELOG.md must be updated from [Unreleased] to a dated version heading before push.

Sources: AGENTS.md:3-7

Development Commands

The project uses Bun for testing and type checking.

Task	Command
Install Dependencies	`bun install`
Run Tests	`bun test ./test`
Type Verification	`bun run typecheck`

Sources: README.md:95-100, AGENTS.md:40-42

Session State

State management is handled within the morphPlugin factory closure. Session-specific mutable state is isolated to prevent leakage between separate agent sessions or subagents.

Sources: AGENTS.md:35-37

Conclusion

Setting up the oh-my-pi-plugin-morph requires a valid API key and standard omp plugin installation procedures. By leveraging environment-based configuration, developers can granularly control which Morph features are exposed to the agent, while the built-in routing hints ensure the agent correctly prioritizes Morph tools over native fallbacks when configured.