Skip to main content
Predict a developer’s next code edit with Mercury Edit 2. Provide recent snippets, the current file with an editable region, and edit history — the request format is documented below. Set your API key as an environment variable and install the SDK.

Next Edit Request Format

Mercury Edit expects next-edit requests to contain 3 sections of code contents: recently viewed snippets, the current file with the editable region, and a time-ordered edit history. The primary purpose of the recently viewed snippets and edit history is to provide context to Mercury Edit so that it can better understand the user’s current intent in modifying code.
The recently viewed snippets should be formatted as:
Each snippet should correspond to a piece of code (or entire code files) that a user has recently viewed. If you do not wish to use recently viewed snippets, please add <|recently_viewed_code_snippets|>\n\n<|/recently_viewed_code_snippets|> with no contents inside the tags.
The current file content should be formatted as:
Mercury Edit will return an updated version of the editable region in its response (e.g., completing a function) enclosed in triple backticks.
The edit history should be formatted as:
As seen above, each edit should follow unidiff formatting. It is important to make sure that the bottommost edits in the prompt correspond to the most recent edits made by the user. If you do not wish to use edit history, please add <|edit_diff_history|>\n\n<|/edit_diff_history|> with no contents inside the tags.

Next Edit Prompting Best Practices

The following best practices will help you get the most relevant suggestions out of Mercury Edit while maintaining low latency.
Include 3–5 snippets of roughly 20 lines each, centered around the user’s recent cursor positions. These should be focused code excerpts — not full files. For more advanced implementations, consider using AST nodes at cursor locations or code RAG to surface relevant type definitions and method implementations across the codebase.Always provide the latest state of code at each snippet location, as stale snippets can cause the model to suggest reverting recent changes. Both full declarations and outlines (e.g., type signatures and docstrings) are acceptable snippet formats.
Include at least the last 3–5 user edits, ordered chronologically with the most recent edit last. Edits should be range-based — if a user made multiple modifications in the same area, combine them into a single unidiff rather than many granular diffs.The edit history is often the strongest signal for identifying user intent. Ensuring the final entry corresponds to the user’s most recent edit can significantly improve suggestion quality.
Pass in the entire current file so the model can draw on imports, function signatures, and surrounding code. For extremely large files, trim distant regions while preserving the area around the editable region.
The editable region directly determines output token count and dominates latency. We recommend starting with 10–15 lines (~100–150 tokens) and tuning from there. At ~1,000 tokens/second decoding speed, an upper bound of around 25 lines (~250 tokens) is practical depending on network latency.For selecting which lines to include, a simple approach is to center the region around the cursor: [currentLine - 5, currentLine + 10].To suggest edits beyond the cursor vicinity:
  • Parallel requests: Fire multiple requests with disjoint editable regions and check which ones produce meaningful diffs.
  • Linter-guided selection: Wrap editable regions around locations where the linter identifies errors.
We recommend making the maximum editable region size configurable so you can tune the tradeoff between suggestion scope and latency.