Introduction to Morph Plugin

Relevant source files

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

• README.md
• package.json
• src/index.ts
• src/config.ts
• src/routing.ts
• src/compaction.ts
• src/tools/morph-edit.ts
• src/tools/warpgrep.ts
• AGENTS.md

The Morph Plugin is an extension for the oh-my-pi (omp) coding agent that integrates Morph LLM capabilities. It provides advanced code editing, natural-language codebase searching, and efficient session compaction features. The plugin serves as a bridge between the local agent environment and Morph's specialized remote APIs, enhancing the agent's ability to handle large-scale refactors and complex repository explorations.

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

Architecture Overview

The plugin is structured as a modular extension that registers tools and event handlers within the oh-my-pi ecosystem. It utilizes the morphsdk to communicate with Morph APIs.

Component Logic Flow

The following diagram illustrates how the plugin initializes and interacts with the host agent and remote Morph services.

The plugin's lifecycle state is kept within the morphPlugin(pi) factory function to prevent cross-session leakage.

Sources: src/index.ts:13-33, AGENTS.md:32-35, src/morph-clients.ts:11-30

Core Features and Tools

Code Editing with fast_edit

The fast_edit tool utilizes Morph's "Fast Apply" technology to perform large or scattered edits within existing files. It is specifically designed to be more robust than exact-string matching for complex refactors.

• Mechanism: The model provides partial snippets using // ... existing code ... markers. The tool merges these changes into the full file via remote API and validates the output for "marker leakage" or "catastrophic truncation" before writing to disk.
• Approval Tier: write.

Sources: README.md:46-53, src/tools/morph-edit.ts:16-56, src/format.ts:121-144

Codebase Exploration with WarpGrep

The plugin provides two primary search tools:

1. codebase_warpsearch: Performs agentic natural-language search over the currently checked-out workspace.
2. github_warpsearch: Provides grounded source search for public GitHub repositories without requiring a local clone.

Sources: README.md:55-63, src/tools/warpgrep.ts:33-54

Session and File Compaction

The plugin implements high-efficiency compaction to manage token usage:

• fastcompact: A tool to condense specific files or artifacts into shorter, query-focused text.
• session_before_compact Hook: Automatically intercepts oh-my-pi compaction events to use Morph's specialized compaction API instead of native LLM summaries.

Sources: README.md:65-89, src/compaction.ts:145-195

Configuration and Environment Variables

The plugin is configured entirely via environment variables. If MORPH_API_KEY is missing, the tools remain registered but provide guidance on how to configure the key.

Variable	Default	Description
MORPH_API_KEY	Required	Morph API key for remote service access.
MORPH_EDIT	true	Enables/Disables the fast_edit tool.
MORPH_WARPGREP	true	Enables/Disables local codebase_warpsearch.
MORPH_COMPACT	true	Enables/Disables the session compaction hook.
MORPH_COMPACT_RATIO	0.3	Target fraction (0.05 to 1.0) to keep during compaction.

Sources: src/config.ts:1-35, README.md:27-42

Data Flow: Session Compaction

Compaction involves serializing agent history and sending it to the Morph Compact API.

Compaction Contracts

• Fallback Logic: If the API errors or returns an empty summary, the bridge returns undefined, allowing oh-my-pi to fall back to its native compaction strategy.
• Snapcompact Yield: The plugin yields to the host's native snapcompact strategy (image-archive) if no focus text is provided.
• Local-only path: If remoteEnabled is false (e.g., /compact soft), the plugin yields to prevent transcript egress.

Sources: src/compaction.ts:147-185, AGENTS.md:14-25, CHANGELOG.md:14-20

Implementation Details

File Path Resolution and Security

The plugin implements strict security checks to ensure file operations do not escape the workspace root. It uses realpathSync and component-wise traversal to handle symlinks securely.

// src/format.ts:88-106
export function resolveFilepath(targetFilepath: string, cwd: string): string {
  if (isAbsolute(targetFilepath)) {
    throw new Error(`Unsafe target_filepath: absolute paths are not allowed...`);
  }
  const resolved = resolvePath(cwd, targetFilepath);
  if (escapesRoot(cwd, resolved)) {
    throw new Error(`Unsafe target_filepath: resolved path escapes the workspace root...`);
  }
  // ... further symlink-aware checks
}

Sources: src/format.ts:88-115

Routing Hints

The plugin appends a tool-selection policy to the system prompt via the before_agent_start event. This directs the agent to favor Morph-backed tools (like fast_edit) for complex tasks while using native tools for trivial operations.

Sources: src/routing.ts:46-88, README.md:91-97

Conclusion

The Morph Plugin integrates advanced LLM-driven development tools into the oh-my-pi environment. By offloading complex merge logic, natural language search, and context-aware compaction to remote Morph services, it enables the agent to operate more effectively in large codebases while maintaining strict security boundaries and efficient token management.