fast_edit Tool

Relevant source files

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

• src/tools/morph-edit.ts
• README.md
• src/format.ts
• src/routing.ts
• src/config.ts
• test/morph.test.ts
• AGENTS.md

The fast_edit tool is a high-performance file modification utility within the oh-my-pi-plugin-morph extension. It leverages Morph's AI-powered "Fast Apply" technology to merge partial code snippets into existing files. It is specifically designed to handle complex refactoring, large files (typically 300+ lines), and scattered changes where traditional exact-string matching methods (like the native edit tool) might be fragile or inefficient.

The tool operates by receiving a code_edit string that uses specific // ... existing code ... markers to denote unchanged sections. This allows the AI to precisely anchor and apply changes without requiring the full content of the file to be transmitted in the edit request, while still ensuring the integrity of the surrounding code through validation checks like marker leakage and catastrophic truncation detection.

Sources: src/tools/morph-edit.ts:16-36, README.md:46-52, AGENTS.md:14-16

Architecture and Execution Flow

The execution of fast_edit involves several stages: input normalization, security validation (path resolution), remote AI processing via the Morph API, and safety checks on the resulting merged code before writing back to the disk.

Workflow Diagram

The following diagram illustrates the lifecycle of a fast_edit call, from initial parameter validation to final file writing.

Key Components and Logic

1. Marker-Based Editing

fast_edit uses the EXISTING_CODE_MARKER (// ... existing code ...) to identify parts of the file that should remain untouched.

• Mandatory Markers: If a file has more than 10 lines, markers are required to prevent accidental full-file replacement.
• Context Requirement: Users are encouraged to include 1-2 unique context lines around edits to assist the AI in precise anchoring.

Sources: src/tools/morph-edit.ts:25-33, src/config.ts:15, src/tools/morph-edit.ts:101-115

2. Security and Path Resolution

The tool implements strict path containment checks to ensure it only operates within the workspace root.

• Absolute Path Rejection: Absolute paths are prohibited.
• Root Escape Protection: Paths using .. to escape the cwd are blocked.
• Symlink Awareness: The resolveFilepath function walks path components to ensure symlinks do not point to targets outside the real workspace root.

Sources: src/format.ts:63-100, test/morph.test.ts:175-183

3. Safety Validations

After the Morph API returns merged code, the tool performs two critical safety checks:

• Marker Leakage: Detects if // ... existing code ... markers appear in the output, which indicates the AI treated them as literal text instead of expanding them.
• Catastrophic Truncation: Triggers if the merged code loses more than 60% of characters AND 50% of lines compared to the original, provided markers were used.

Sources: src/format.ts:114-142, src/tools/morph-edit.ts:156-189

Tool Parameters and Configuration

Parameters

The tool is defined with the following Zod-validated parameters:

Parameter	Type	Description
target_filepath	string	Relative path of the file to modify within the workspace.
instructions	string	Description of the change (e.g., "adding X to function Y").
code_edit	string	Code changes wrapped with // ... existing code ... markers.

Sources: src/tools/morph-edit.ts:48-56

Configuration Environment Variables

The availability and behavior of fast_edit are controlled via environment variables.

Variable	Default	Description
MORPH_API_KEY	(Required)	Necessary for remote AI merging. Without it, the tool returns guidance.
MORPH_EDIT	true	Set to false to disable the registration of the fast_edit tool.
MORPH_API_URL	https://api.morphllm.com	The endpoint for the Morph Fast Apply service.

Sources: src/config.ts:1-12, README.md:29-37

Usage Comparison

fast_edit is part of a suite of tools. The project defines a clear "Routing Hint" policy for when to use it versus native alternatives.

Task Type	Preferred Tool	Rationale
Complex/Large Edits	fast_edit	Handles whitespace, scattered changes, and refactors better than string matching.
Trivial Replacements	Native edit	Faster for single-line or exact-string matches; no API call required.
New Files	Native write	fast_edit is optimized for merging into existing state.

Sources: src/routing.ts:48-61, src/tools/morph-edit.ts:18-23, AGENTS.md:14-16

Implementation Detail: Input Normalization

The tool automatically strips Markdown code fences if the agent wraps the code_edit in them (e.g., ```typescript ... ```). This ensures the raw code is sent to the Morph API.

// From src/format.ts:8-21
export function normalizeCodeEditInput(codeEdit: string): string {
  const trimmed = codeEdit.trim();
  const lines = trimmed.split("\n");
  if (lines.length < 3) return codeEdit;
  const firstLine = lines[0];
  const lastLine = lines[lines.length - 1];
  if (/^```[\w-]*$/.test(firstLine) && /^```$/.test(lastLine)) {
    return lines.slice(1, -1).join("\n");
  }
  return codeEdit;
}

Sources: src/format.ts:8-21, test/morph.test.ts:133-137

Conclusion

The fast_edit tool serves as the primary mechanism for robust, AI-driven code modifications in the oh-my-pi-plugin-morph extension. By combining the flexibility of marker-based partial edits with rigorous local safety checks, it provides a reliable bridge between high-level agent instructions and low-level file mutations. Its integration into the plugin's routing logic ensures that it is prioritized for complex tasks while falling back to native tools for simpler operations.