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

*** 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 / - / +.

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

• @@ — 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.

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

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

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

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.

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.

• 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.

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