griz
Code edits as composable primitives, for agents and the programs they write.
griz splits an edit into small steps whose outputs feed the next step: find text, plan a change without writing it, diff or select part of the plan, apply it all-or-nothing, and undo it later. Served over MCP, every step is its own tool, so a Code Mode program composes griz with anything else it can call: run checks through apoc, judge matches with jev, record work in devsql.
// One apoc Code Mode program: rename across files, check, roll back on failure.
const root = "/path/to/repo"; // over MCP, griz runs wherever its host started it
const found = await griz.;
const ops = found..;
const plan = await griz.;
const applied = await griz.;
const check = await apoc.;
if
return ;
Only what the program returns reaches the model. The 12 matches, the plan, and the check output stay inside the program.
Guarantees
- Nothing is written before apply.
planbuilds every file's new text in memory and records it;diffshows it. - Stale files are refused. Every match and every planned file carries the
fingerprint of the text it was computed against.
applywrites nothing unless every file still has that fingerprint, or, withon_stale: "merge", unless a three-way merge is clean. - All or nothing. Every file is staged before the first rename, and the operation is journaled first. A process killed mid-apply is finished by the next griz invocation.
- Tolerant matches are labeled. An anchor is matched exactly first, then
ignoring trailing whitespace, then by relative indentation, then trimmed.
Only exact matches and find ranges are
machineconfidence;applyrefusesmaybeedits unless asked, andselectcan keep only the exact ones. - Ambiguity is an error. An anchor matching twice reports every candidate line instead of taking the first.
- Misses show the real text. A missed anchor records the nearest real window
of the file, readable with
get. - Undo never clobbers. Undo restores only files still exactly as the
operation left them, or, with
on_stale: "merge", merges cleanly around later edits. An undo is itself an operation that can be undone. - Restores follow history.
undo --sincerewinds a span of operations only where every file's writes hand off the same fingerprint; a change made outside griz in between refuses the restore. - Parse facts, not judgments. A plan reports whether each file still parses; griz never refuses on it.
- Formatters do not break undo. Run a formatter after
apply, thenabsorbthe operation; undo restores the text from before the apply. - Retries are safe. Mutations take an
idempotency_key; the same key and input replay the original result, and different input with the same key is refused.
Commands
| Command | Kind | Does |
|---|---|---|
read PATH |
read | Numbered lines and fingerprint; --grep, --lines. |
find |
read | Literal, regex, or structural (--pattern 'foo($A, $$$REST)') matches with byte ranges, captures, fingerprints; --within comment; honors .gitignore; --expect-matches. |
plan |
records | Operations (--ops), Codex patch text (--patch, @file), or an LSP --workspace-edit into a plan id, with parse facts. |
select PLAN |
records | A new plan from part of another, by path, edit id, or confidence. |
diff ID |
read | Unified diff of a plan or operation, with the named items it changes; --grep or --lines. |
apply PLAN |
writes | All-or-nothing write; --min-confidence, --on-stale merge, --expect-files. |
undo OP |
writes | Restore an operation's files; --paths, --on-stale merge, or --since OP for a span. |
absorb OP |
records | Fold a later formatter run into an operation so undo still works. |
log / get ID |
read | Operation history, narrowed with --paths; the complete record of a plan, operation, or blob_<hash>. |
Mutations answer {id, outcome} with outcome one of passed, failed
(a declared expectation did not hold), or error (nothing was done). Add
--verbosity warn|info|debug|trace for more; trace returns the full record.
A verdict other than passed exits nonzero.
Operations, applied in order:
{op:"replace", path, find:"text" | {text, after?, whole_lines?} | range:{start,end} | pattern:{pattern, language?}, target?, replace, occurrence?, expect_hash?}
{op:"insert", path, anchor:{text}, after?, text, expect_hash?}
{op:"create", path, text, overwrite?}
{op:"delete", path, expect_hash?}
{op:"move", path, to, expect_hash?}
Use
State lives in $GRIZ_HOME, or the user data directory.
Workspace
griz-core: the pure engine. It reads files it is handed and never writes;cargo xtask checkenforces that.griz-store: journal, content store, locks, idempotency receipts, recovery.griz: the command graph, CLI, and MCP server.xtask: quality policy. Files at most 300 lines, functions at most 60 code lines, narrow test-only lint suppressions, dependency directiongriz → griz-store → griz-core.