Environment Variables and Configuration

Relevant source files

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

• README.md
• src/config.ts
• src/index.ts
• src/routing.ts
• AGENTS.md
• test/morph.test.ts

The oh-my-pi-plugin-morph extension utilizes environment variables as the primary mechanism for configuration. These variables control API authentication, feature flagging for specific tools, and tuning parameters for LLM-driven operations like compaction and routing guidance.

The configuration system is designed to allow the plugin to remain registered even when mandatory credentials like MORPH_API_KEY are missing. In such cases, the plugin provides setup guidance to the user via tool descriptions and runtime notes rather than failing silently or crashing.
Sources: README.md:38-40, src/routing.ts:16-36, AGENTS.md:12-14

Configuration Parameters

The following table details the environment variables supported by the plugin, their default values, and their impact on system behavior.

Variable	Default	Description
MORPH_API_KEY	undefined	Required. The API key for Morph LLM services. If missing, tools register but return guidance.
MORPH_EDIT	true	Enables or disables the fast_edit tool.
MORPH_WARPGREP	true	Enables or disables the codebase_warpsearch tool.
MORPH_WARPGREP_GITHUB	true	Enables or disables the github_warpsearch tool.
MORPH_COMPACT	true	Enables or disables the session_before_compact event hook.
MORPH_FASTCOMPACT	true	Enables or disables the fastcompact standalone tool.
MORPH_ROUTING_HINT	true	Enables or disables system-level routing hints for the agent.
MORPH_COMPACT_RATIO	0.3	Target fraction (0.05 to 1.0) to keep during Morph compaction.

Sources: src/config.ts:1-32, README.md:46-55

Initialization and Feature Gating

During the plugin initialization phase, the morphPlugin function evaluates the state of environment variables to determine which tools and event handlers should be registered with the ExtensionAPI.

The diagram shows the logic flow for feature registration based on configuration flags.
Sources: src/index.ts:18-40, test/morph.test.ts:983-1033

Feature Flag Enforcement

The plugin uses specific boolean constants derived from process.env to gate registration. For example, if MORPH_EDIT is set to "false", the fast_edit tool is entirely omitted from the pi.registerTool calls.
Sources: src/config.ts:25-32, src/index.ts:19-22

Dynamic Routing Guidance

Configuration variables directly influence the system prompt generated for the agent. The buildMorphSystemRoutingHint function checks the availability of the MORPH_API_KEY and specific feature flags to provide the agent with a prioritized list of tools.

• Unconfigured State: If MORPH_API_KEY is absent, the system prompt explicitly instructs the agent that Morph tools are unavailable and to favor native tools.
• Configured State: When the key is present, the plugin injects a "Morph-first" preference, encouraging the agent to use tools like fast_edit for complex tasks while reserving native tools for trivial operations.

Sources: src/routing.ts:39-81, AGENTS.md:12-18

Routing Priority Logic

Scenario	Instruction to Agent
MORPH_API_KEY Missing	"Use native edit/write/grep tools until Morph credentials are configured."
MORPH_EDIT Enabled	"Prefer fast_edit for edits inside existing files... Native edit still wins for trivial replacements."
MORPH_WARPGREP Enabled	"Prefer codebase_warpsearch over manual grep-and-read loops for exploratory questions."

Sources: src/routing.ts:41-81

Compaction Tuning

The MORPH_COMPACT_RATIO environment variable controls the compression behavior of the Morph Compact API bridge. The plugin enforces a valid range between 0.05 and 1.0.

const parsedCompactRatio = Number.parseFloat(
  process.env.MORPH_COMPACT_RATIO || "0.3",
);
export const COMPACT_RATIO =
  Number.isFinite(parsedCompactRatio) && parsedCompactRatio >= 0.05 && parsedCompactRatio <= 1
    ? parsedCompactRatio
    : 0.3;

Sources: src/config.ts:20-27

Additionally, the configuration defines hard limits for the fastcompact tool to prevent unbounded data egress:

• FASTCOMPACT_MAX_BYTES: 1,048,576 bytes (1MB) per input.
• FASTCOMPACT_MAX_LOCATIONS: 10 locations per call.
• FASTCOMPACT_MAX_QUERY_BYTES: 16,384 bytes for focus queries.

Sources: src/config.ts:38-45, test/morph.test.ts:829-840

Internal Runtime Constants

While not configurable via environment variables, the system relies on internal constants for operational stability, primarily timeouts for remote calls:

• MORPH_TIMEOUT: 30,000ms
• MORPH_WARP_GREP_TIMEOUT: 60,000ms
• MORPH_COMPACT_TIMEOUT: 60,000ms
• GITHUB_RESOLVER_TIMEOUT: 10,000ms

Sources: src/config.ts:7-11

Conclusion

The configuration architecture of oh-my-pi-plugin-morph prioritizes graceful degradation. By using environment variables to gate features and providing runtime feedback when credentials are missing, the plugin ensures that the agent remains functional with native tools while making Morph-backed capabilities easy to toggle and tune for different deployment environments.
Sources: README.md:112-117, AGENTS.md:12-22