Quickstart - Morph Documentation

Prerequisite: You’ll need an account on Morph to obtain an API key.

One-Shot the edit_file tool into your repo

Click here for a prompt for your AI IDE

① Prompt Your Agent

Configure your AI agent with the proper system prompt to handle code editing effectively:

System Prompt Configuration

Add this to your AI agent’s system prompt:

<making_code_changes>
When making code changes, NEVER output code to the USER, unless requested. Instead use one of the code edit tools to implement the change. Use the code edit tools at most once per turn. It is EXTREMELY important that your generated code can be run immediately by the USER. To ensure this, follow these instructions carefully:

Add all necessary import statements, dependencies, and endpoints required to run the code.
If you're creating the codebase from scratch, create an appropriate dependency management file (e.g. requirements.txt) with package versions and a helpful README.
If you're building a web app from scratch, give it a beautiful and modern UI, imbued with best UX practices.
NEVER generate an extremely long hash or any non-textual code, such as binary. These are not helpful to the USER and are very expensive.
Unless you are appending some small easy to apply edit to a file, or creating a new file, you MUST read the the contents or section of what you're editing before editing it.
If you've introduced (linter) errors, please try to fix them. But, do NOT loop more than 3 times when doing this. On the third time, ask the user if you should keep going.
If you've suggested a reasonable code_edit that wasn't followed by the apply model, you should try reapplying the edit.
</making_code_changes>

<tool_calling>
ALWAYS follow the tool call schema exactly as specified and make sure to provide all necessary parameters.
The conversation may reference tools that are no longer available. NEVER call tools that are not explicitly provided.
NEVER refer to tool names when speaking to the USER. For example, instead of saying 'I need to use the edit_file tool to edit your file', just say 'I will edit your file'.
Only calls tools when they are necessary. If the USER's task is general or you already know the answer, just respond without calling tools.
Before calling each tool, first explain to the USER why you are calling it.
</tool_calling>

These prompts ensure your agent:

Uses edit tools instead of outputting code directly
Handles errors gracefully with retry logic
Maintains professional communication without exposing tool names
Only calls tools when necessary

② The Edit File Tool

Implement the edit_file tool in your AI agent with the proper prompt and schema:

Tool Description:

Use this tool to propose an edit to an existing file.

This will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.

When writing the edit, you should specify each edit in sequence, with the special comment // ... existing code ... to represent unchanged code in between edited lines.

For example:

// ... existing code ...
FIRST_EDIT
// ... existing code ...
SECOND_EDIT
// ... existing code ...
THIRD_EDIT
// ... existing code ...

You should still bias towards repeating as few lines of the original file as possible to convey the change.
But, each edit should contain sufficient context of unchanged lines around the code you're editing to resolve ambiguity.
DO NOT omit spans of pre-existing code (or comments) without using the // ... existing code ... comment to indicate its absence. If you omit the existing code comment, the model may inadvertently delete these lines.
Make sure it is clear what the edit should be, and where it should be applied.
To create a new file, simply specify the content of the file in the code_edit field.
ALWAYS make all edits to a file in a single edit_file instead of multiple edit_file calls to the same file. The apply model can handle many distinct edits at once.

Parameters:

target_file (string, required): The target file to modify
code_edit (string, required): Specify ONLY the precise lines of code that you wish to edit. Use // ... existing code ... for unchanged sections.

Tool Description:

Use this tool to propose an edit to an existing file.

This will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.

When writing the edit, you should specify each edit in sequence, with the special comment // ... existing code ... to represent unchanged code in between edited lines.

For example:

// ... existing code ...
FIRST_EDIT
// ... existing code ...
SECOND_EDIT
// ... existing code ...
THIRD_EDIT
// ... existing code ...

You should still bias towards repeating as few lines of the original file as possible to convey the change.
But, each edit should contain sufficient context of unchanged lines around the code you're editing to resolve ambiguity.
DO NOT omit spans of pre-existing code (or comments) without using the // ... existing code ... comment to indicate its absence. If you omit the existing code comment, the model may inadvertently delete these lines.
Make sure it is clear what the edit should be, and where it should be applied.
To create a new file, simply specify the content of the file in the code_edit field.
ALWAYS make all edits to a file in a single edit_file instead of multiple edit_file calls to the same file. The apply model can handle many distinct edits at once.

Parameters:

target_file (string, required): The target file to modify
code_edit (string, required): Specify ONLY the precise lines of code that you wish to edit. Use // ... existing code ... for unchanged sections.

Tool Definition:

{
  "name": "edit_file",
  "description": "Use this tool to propose an edit to an existing file.\n\nThis will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.\nWhen writing the edit, you should specify each edit in sequence, with the special comment // ... existing code ... to represent unchanged code in between edited lines.\n\nYou should bias towards repeating as few lines of the original file as possible to convey the change.\nNEVER show unmodified code in the edit, unless sufficient context of unchanged lines around the code you're editing is needed to resolve ambiguity.\nIf you plan on deleting a section, you must provide surrounding context to indicate the deletion.\nDO NOT omit spans of pre-existing code without using the // ... existing code ... comment to indicate its absence.",
  "parameters": {
    "properties": {
      "target_file": {
        "type": "string",
        "description": "The target file to modify."
      },
      "code_edit": {
        "type": "string",
        "description": "Specify ONLY the precise lines of code that you wish to edit. Use // ... existing code ... for unchanged sections."
      }
    },
    "required": ["target_file", "code_edit"]
  }
}

Example Good Edit Pattern:

// ... existing code ...
function calculateTotal(items) {
  // ... existing code ...
  for item in items:
    total += item.price;
  return total * 1.1;  // Add 10% tax
}
// ... existing code ...

const total, setTotal = useState(0);

useEffect(() => {
  setTotal(calculateTotal(items));
}, [items]);

// ... existing code ...
return <div>Total: {total}</div>;

Best Practices:

Use // ... existing code ... to indicate unchanged sections
Provide sufficient context around edits for proper placement
Keep instructions concise and action-oriented
Minimize token usage by not repeating large unchanged sections

③ Pass to Morph API

When your agent calls the edit_file tool, send the original file content and update snippet to Morph:

Morph API Documentation

View our OpenAI-compatible API

API Base URL:

https://api.morphllm.com/v1

Implementation Example:

import { promises as fs } from 'fs';
import OpenAI from 'openai';

// Initialize the OpenAI client with Morph's API endpoint
const openai = new OpenAI({
  apiKey: process.env.MORPH_API_KEY || 'your-morph-api-key',
  baseURL: 'https://api.morphllm.com/v1'
});

async function editFile(params: {
  target_file: string;
  code_edit: string;
}): Promise<{ success: boolean; message: string; error?: any }> {
  try {
    // 1. Read the original file
    const originalContent = await fs.readFile(params.target_file, 'utf8');
    
    // 2. Send to Morph API
    const response = await openai.chat.completions.create({
      model: 'morph-v3-large',
      messages: [
        {
          role: 'user',
          content: `<code>${originalContent}</code>\n<update>${params.code_edit}</update>`
        }
      ]
    });
    
    // 3. Write the updated content back to the file
    await fs.writeFile(params.target_file, response.choices[0].message.content);
    
    return {
      success: true,
      message: `File ${params.target_file} was successfully updated`
    };
  } catch (error) {
    return {
      success: false,
      message: `Error: ${error.message}`,
      error
    };
  }
}

Input Format:

The Morph API expects two key components:

Original code wrapped in <code>...</code> tags
Update snippet wrapped in <update>...</update> tags

The update snippet should use truncation markers like // ... existing code ... to indicate unchanged parts of the code.

Why Morph?

Morph’s apply model offers significant advantages over search/replace or full file rewriting:

Speed: Process edits at 4500+ tokens per second
Native: Models can output code in a natural way without artificial constraints on output format which bias code results
Accuracy: Precise application of changes with context awareness
Cost-effective: >4x lower token usage compared to generating entire files

For access to our latest models, self-hosting, or business inquiries, please contact us at info@morphllm.com.

On this page

① Prompt Your Agent
② The Edit File Tool
③ Pass to Morph API

Prerequisite: You’ll need an account on Morph to obtain an API key.

One-Shot the edit_file tool into your repo

Click here for a prompt for your AI IDE

① Prompt Your Agent

Configure your AI agent with the proper system prompt to handle code editing effectively:

System Prompt Configuration

Add this to your AI agent’s system prompt:

<making_code_changes>
When making code changes, NEVER output code to the USER, unless requested. Instead use one of the code edit tools to implement the change. Use the code edit tools at most once per turn. It is EXTREMELY important that your generated code can be run immediately by the USER. To ensure this, follow these instructions carefully:

Add all necessary import statements, dependencies, and endpoints required to run the code.
If you're creating the codebase from scratch, create an appropriate dependency management file (e.g. requirements.txt) with package versions and a helpful README.
If you're building a web app from scratch, give it a beautiful and modern UI, imbued with best UX practices.
NEVER generate an extremely long hash or any non-textual code, such as binary. These are not helpful to the USER and are very expensive.
Unless you are appending some small easy to apply edit to a file, or creating a new file, you MUST read the the contents or section of what you're editing before editing it.
If you've introduced (linter) errors, please try to fix them. But, do NOT loop more than 3 times when doing this. On the third time, ask the user if you should keep going.
If you've suggested a reasonable code_edit that wasn't followed by the apply model, you should try reapplying the edit.
</making_code_changes>

<tool_calling>
ALWAYS follow the tool call schema exactly as specified and make sure to provide all necessary parameters.
The conversation may reference tools that are no longer available. NEVER call tools that are not explicitly provided.
NEVER refer to tool names when speaking to the USER. For example, instead of saying 'I need to use the edit_file tool to edit your file', just say 'I will edit your file'.
Only calls tools when they are necessary. If the USER's task is general or you already know the answer, just respond without calling tools.
Before calling each tool, first explain to the USER why you are calling it.
</tool_calling>

These prompts ensure your agent:

Uses edit tools instead of outputting code directly
Handles errors gracefully with retry logic
Maintains professional communication without exposing tool names
Only calls tools when necessary

② The Edit File Tool

Implement the edit_file tool in your AI agent with the proper prompt and schema:

Tool Description:

Use this tool to propose an edit to an existing file.

This will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.

When writing the edit, you should specify each edit in sequence, with the special comment // ... existing code ... to represent unchanged code in between edited lines.

For example:

// ... existing code ...
FIRST_EDIT
// ... existing code ...
SECOND_EDIT
// ... existing code ...
THIRD_EDIT
// ... existing code ...

You should still bias towards repeating as few lines of the original file as possible to convey the change.
But, each edit should contain sufficient context of unchanged lines around the code you're editing to resolve ambiguity.
DO NOT omit spans of pre-existing code (or comments) without using the // ... existing code ... comment to indicate its absence. If you omit the existing code comment, the model may inadvertently delete these lines.
Make sure it is clear what the edit should be, and where it should be applied.
To create a new file, simply specify the content of the file in the code_edit field.
ALWAYS make all edits to a file in a single edit_file instead of multiple edit_file calls to the same file. The apply model can handle many distinct edits at once.

Parameters:

target_file (string, required): The target file to modify
code_edit (string, required): Specify ONLY the precise lines of code that you wish to edit. Use // ... existing code ... for unchanged sections.

Tool Description:

Use this tool to propose an edit to an existing file.

This will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.

When writing the edit, you should specify each edit in sequence, with the special comment // ... existing code ... to represent unchanged code in between edited lines.

For example:

// ... existing code ...
FIRST_EDIT
// ... existing code ...
SECOND_EDIT
// ... existing code ...
THIRD_EDIT
// ... existing code ...

You should still bias towards repeating as few lines of the original file as possible to convey the change.
But, each edit should contain sufficient context of unchanged lines around the code you're editing to resolve ambiguity.
DO NOT omit spans of pre-existing code (or comments) without using the // ... existing code ... comment to indicate its absence. If you omit the existing code comment, the model may inadvertently delete these lines.
Make sure it is clear what the edit should be, and where it should be applied.
To create a new file, simply specify the content of the file in the code_edit field.
ALWAYS make all edits to a file in a single edit_file instead of multiple edit_file calls to the same file. The apply model can handle many distinct edits at once.

Parameters:

target_file (string, required): The target file to modify
code_edit (string, required): Specify ONLY the precise lines of code that you wish to edit. Use // ... existing code ... for unchanged sections.

Tool Definition:

{
  "name": "edit_file",
  "description": "Use this tool to propose an edit to an existing file.\n\nThis will be read by a less intelligent model, which will quickly apply the edit. You should make it clear what the edit is, while also minimizing the unchanged code you write.\nWhen writing the edit, you should specify each edit in sequence, with the special comment // ... existing code ... to represent unchanged code in between edited lines.\n\nYou should bias towards repeating as few lines of the original file as possible to convey the change.\nNEVER show unmodified code in the edit, unless sufficient context of unchanged lines around the code you're editing is needed to resolve ambiguity.\nIf you plan on deleting a section, you must provide surrounding context to indicate the deletion.\nDO NOT omit spans of pre-existing code without using the // ... existing code ... comment to indicate its absence.",
  "parameters": {
    "properties": {
      "target_file": {
        "type": "string",
        "description": "The target file to modify."
      },
      "code_edit": {
        "type": "string",
        "description": "Specify ONLY the precise lines of code that you wish to edit. Use // ... existing code ... for unchanged sections."
      }
    },
    "required": ["target_file", "code_edit"]
  }
}

Example Good Edit Pattern:

// ... existing code ...
function calculateTotal(items) {
  // ... existing code ...
  for item in items:
    total += item.price;
  return total * 1.1;  // Add 10% tax
}
// ... existing code ...

const total, setTotal = useState(0);

useEffect(() => {
  setTotal(calculateTotal(items));
}, [items]);

// ... existing code ...
return <div>Total: {total}</div>;

Best Practices:

Use // ... existing code ... to indicate unchanged sections
Provide sufficient context around edits for proper placement
Keep instructions concise and action-oriented
Minimize token usage by not repeating large unchanged sections

③ Pass to Morph API

When your agent calls the edit_file tool, send the original file content and update snippet to Morph:

Morph API Documentation

View our OpenAI-compatible API

API Base URL:

https://api.morphllm.com/v1

Implementation Example:

import { promises as fs } from 'fs';
import OpenAI from 'openai';

// Initialize the OpenAI client with Morph's API endpoint
const openai = new OpenAI({
  apiKey: process.env.MORPH_API_KEY || 'your-morph-api-key',
  baseURL: 'https://api.morphllm.com/v1'
});

async function editFile(params: {
  target_file: string;
  code_edit: string;
}): Promise<{ success: boolean; message: string; error?: any }> {
  try {
    // 1. Read the original file
    const originalContent = await fs.readFile(params.target_file, 'utf8');
    
    // 2. Send to Morph API
    const response = await openai.chat.completions.create({
      model: 'morph-v3-large',
      messages: [
        {
          role: 'user',
          content: `<code>${originalContent}</code>\n<update>${params.code_edit}</update>`
        }
      ]
    });
    
    // 3. Write the updated content back to the file
    await fs.writeFile(params.target_file, response.choices[0].message.content);
    
    return {
      success: true,
      message: `File ${params.target_file} was successfully updated`
    };
  } catch (error) {
    return {
      success: false,
      message: `Error: ${error.message}`,
      error
    };
  }
}

Input Format:

The Morph API expects two key components:

Original code wrapped in <code>...</code> tags
Update snippet wrapped in <update>...</update> tags

The update snippet should use truncation markers like // ... existing code ... to indicate unchanged parts of the code.

Why Morph?

Morph’s apply model offers significant advantages over search/replace or full file rewriting:

Speed: Process edits at 4500+ tokens per second
Native: Models can output code in a natural way without artificial constraints on output format which bias code results
Accuracy: Precise application of changes with context awareness
Cost-effective: >4x lower token usage compared to generating entire files

For access to our latest models, self-hosting, or business inquiries, please contact us at info@morphllm.com.

On this page

① Prompt Your Agent
② The Edit File Tool
③ Pass to Morph API

One-Shot the edit_file tool into your repo

​① Prompt Your Agent

​② The Edit File Tool

​③ Pass to Morph API

Morph API Documentation

One-Shot the edit_file tool into your repo

​① Prompt Your Agent

​② The Edit File Tool

​③ Pass to Morph API

Morph API Documentation

① Prompt Your Agent

② The Edit File Tool

③ Pass to Morph API

① Prompt Your Agent

② The Edit File Tool

③ Pass to Morph API