Structured data and diffs (@json, @diff)

Two tools for the data an agent handles between reads and edits. @json answers questions about a payload — the 2 MB API response @http saved to disk, a Helm values file — without reading it whole. @diff shows what changed and applies a patch only when every context line matches.

`@json`

<tool_call name="@json" args='{"cmd":"schema","args":{"file":"resp.json"}}' />
<tool_call name="@json" args='{"cmd":"get","args":{"file":"resp.json","path":"data.items[3].name"}}' />
<tool_call name="@json" args='{"cmd":"query","args":{"file":"resp.json","path":"data.items","where":"status=failed && name~^web","select":["id","name"],"limit":20}}' />
<tool_call name="@json" args='{"cmd":"validate","args":{"text":"{\"a\": 1,}"}}' />

Verb	Arguments	What it does
`get`	`file\|text`, `path`	the value at a dotted/bracket path: `a.b[0].c`, `[-1]`, `*` fans out over arrays and objects; a miss names the segment and lists the keys available there
`keys`	`file\|text`, `path?`	keys one level down with a type summary (`object{n}`, `array[n]`, `string(len)`)
`query`	`file\|text`, `path?`, `where`, `select?`, `limit?`	filters an array of objects: `field=value`, `field!=value`, `field~regex`, several joined with `&&`; dotted fields; `limit` default 20, max 200
`schema`	`file\|text`, `depth?` (3, max 8)	the inferred shape of an unknown payload, with how often each key appears across sampled elements
`validate`	`file\|text`	parse errors with 1-based line and column and a snippet; trailing data is an error
`pretty`	`file\|text`, `compact?`	re-indents or compacts

Files up to 20 MB, inside the workspace. YAML is accepted for .yaml/.yml files, or when the text is not JSON but parses as a YAML mapping or list (text that starts with {/[ is judged as JSON only, so a broken JSON document is not silently accepted as YAML flow syntax). Numbers are kept verbatim. Output is capped at 24 000 bytes with a note on how to narrow (deeper path, select, limit). All verbs are read-only and run in parallel.

`@diff`

<tool_call name="@diff" args='{"cmd":"files","args":{"a":"config/old.yaml","b":"config/new.yaml","context":3}}' />
<tool_call name="@diff" args='{"cmd":"dirs","args":{"a":"./v1","b":"./v2","glob":"*.go"}}' />
<tool_call name="@diff" args='{"cmd":"apply","args":{"file":"main.go","patch":"@@ -10,3 +10,3 @@\n ...","dry_run":true}}' />

Verb	Arguments	What it does
`files`	`a`, `b`, `context?` (3, max 50)	unified diff of two files (≤ 4 MB each); identical files say so in one line; binary files are reported, not dumped
`text`	`a`, `b`, `context?`	unified diff of two inline strings, with `\ No newline at end of file` markers
`dirs`	`a`, `b`, `glob?`	added, removed and changed files between two trees (names only, 2000-entry budget, `.git`/`node_modules`/`vendor` skipped)
`apply`	`file`, `patch`, `dry_run?` (true)	parses the `@@` hunks, verifies every context and removed line at its stated position, and refuses on the first mismatch naming the hunk, the line and what the patch expected; `dry_run: false` writes `<file>.bak` and then the file

The diff is a Myers line diff with an edit budget; past it the differing middle is emitted as one block replacement with an explicit note. Output is capped at 30 000 bytes. files, text and dirs are read-only; apply with dry_run: false is the only mutation.

@diff apply is the right tool when the model already has a unified patch (from a PR, a mailing list, a previous @diff files); for search/replace edits @coder patch stays the precise option.

Get started

Documentation

Structured data and diffs (@json, @diff)

`@json`

`@diff`

​@json

​@diff

`@json`

`@diff`