AI-PATCH

AI-PATCH is a concept: a format for ApplyPatch-style edits—single target per patch, absolute path. Lets an LLM or tool output one parseable block that spells out what to add, remove, or change, without ambiguity. Same line semantics as unified diff (space = context, - = remove, + = add), so streaming and “next edit” mapping stay simple. Aligned with NES (Next Edit Suggestion): optional @@ :N gives 1-based line targeting; omitting it applies hunks in order. One target per call keeps responses focused and predictable.

→ Use case: tool-calling flow

Structure

*** Begin Patch
*** Add File: <path>   |   *** Update File: <path>
<hunks>
*** End Patch

• Begin / End — Delimit the patch. Body is between them.
• One header per patch — Either *** Add File: <path> (new file) or *** Update File: <path> (edit existing). Nothing else.
• Hunks — For Add: lines prefixed with +. For Update: optional @@ or @@ :N, then lines with / - / +.

Line Prefix (Unified Diff)

Prefix	Meaning
(space)	Context. Copy exact line from file. Blank line in file → space or empty line in patch.
-	Remove this line from the file.
+	Add this line.

Context-only hunk = no-op. Match file content exactly (indentation, spacing). Read the file before patching.

Hunk Header (Update Only)

• @@ — Apply hunk by searching for the block in order from the previous hunk (or from start of file).
• @@ :N — N = 1-based line number; search for this block starting at line N. NES-style direct targeting.

Hunks are applied in order. Use @@ :N when you know the line; use @@ when order is enough.

Add File

After *** Add File: <path>, every line must start with +. The rest of the line (after stripping +) is file content.

*** Begin Patch
*** Add File: /path/to/new.ts
+export function foo() {
+  return 1
+}
*** End Patch

Update File (Single Change)

Context lines must match the file exactly (including leading space).

*** Begin Patch
*** Update File: /path/to/file.ts
@@
   oldMethod(): void {
-    return
+    return 1
   }
*** End Patch

Update File (Remove Block)

Use - for every line to remove. Keep context (space-prefix) for the lines before and after.

*** Begin Patch
*** Update File: /path/to/file.ts
@@
   mod(n: number): this {
-    if (n === 0) {
-      throw new Error('Division by zero')
-    }
-    this.val %= n
-    return this
-  }
-
   pow(n: number): this {
*** End Patch

Optional: End-of-File Marker

Inside Update, *** End of File can end the current hunk so the next @@ starts a new hunk. Useful for multi-hunk patches. If you omit it, one contiguous block of change lines is one hunk.

Grammar

The patch format can be specified as a formal grammar for parsing and validation. Lark is a parsing library that supports this: you define rules for the structure (begin/end markers, add vs update, hunk headers, line prefixes) and get a parse tree or use it to reject invalid patches. The concept is independent of any particular implementation—any parser that respects the structure and line semantics above will do.

References

• Use case — Tool-calling flow, sequence diagram, minimal schema.
• AI-NES — NES concept, unified diff, streaming, line targeting.
• Lark — Parsing library for context-free grammars; one way to define and parse the patch format.
• Unified diff — Standard diff format.

License

This project is licensed under the MIT license. See the LICENSE file for details.