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";
const expectedMatches = 12;
const found = await griz.;
if
return ;
const ops = found..;
const plan = await griz.;
if return ;
const applied = await griz.;
if return ;
const check = await apoc.;
const result = ;
if return result;
const undone = await griz.;
return ;
Only what the program returns reaches the model. A failed preflight stops before the next step. For a pending check, keep its execution id and the operation id, then wait for the check to finish before deciding whether to undo. A terminal check failure returns the undo verdict too; undo can refuse later file changes.
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. Recovery skips operations that another writer already completed.
- 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. The starting operation must exist; an unknown ID is rejected before any restoration. History follows journal order under file locks, so a delayed concurrent edit appears after the writes it builds on, regardless of when its ID was created. - Parse facts. A plan reports whether each file still parses. Request
expect_syntax: "clean"to fail a plan that introduces syntax errors. - Parent paths follow the filesystem. Before traversing
.., griz resolves the preceding directory, including directory symlinks. Missing or non-directory prefixes are rejected instead of silently choosing a different file. Mutation retries consult their original receipt before resolving target paths again. - Directory aliases compose. New plans resolve existing parent directories, so a directory symlink and its target share one planned file and one lock. Retargeting the link later does not redirect a new saved plan. Missing directory suffixes stay creatable; dangling directory links are rejected. Older saved paths and their original filters remain usable, but a write containing multiple paths to the same destination is refused before staging. This identifies parent directories; final file-name case aliases and file symlinks are separate.
- Replacement permissions stay intact. Replacing an existing file retains its Unix access and executable bits, including during undo and crash recovery. A later permission change is retained when undo replaces that file. Newly created files, including restores of deleted files, use creation defaults.
- Large write batches stage concurrently. Batches with at least 32 writes use at most four staging workers. Every file keeps its full sync, and every worker finishes before the operation is journaled. Final renames retain plan order. On staging errors, workers finish and attempt cleanup before returning.
- Formatters do not break undo. Run a formatter after
apply, thenabsorbthe operation; undo restores the text from before the apply. Concurrent absorbs retain one another's selected-file updates. Undo and span restore refresh selected records after waiting for file locks, including absorbs that completed during the wait. A span keeps its original operation IDs. - Selection uses saved inputs. Selecting part of a plan uses its original file snapshots, including files whose operations cancelled out. An older plan missing a required snapshot is refused; plan again to use current files. Selection loads only snapshots needed by the operations it keeps, including both ends of a move; missing discarded snapshots do not block selection.
- 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>. |
diff items keep kind, name, and change. Nested definitions also include
scope, an outer-to-inner list such as ["left", "impl A"]. File-level items
omit it. Same-named definitions in different scopes remain distinct; overloads
can produce multiple items with the same kind, name, and scope. Rust callers
constructing DiffItem values must initialize scope; use Vec::new() at file
scope.
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. Each level retains the fields and
values below it; trace also includes the full record without dropping the
reason, summary, or detail.
A verdict other than passed exits nonzero.
Absorb retries retain the original call's counts, skipped-file reason, and
operation snapshot, even after another absorb updates the operation. Use get
for the operation's current state. Older absorb receipts saved only the ID and
verdict: they still replay at off or error verbosity, but requesting details
returns IDEMPOTENCY_DETAIL_UNAVAILABLE instead of reconstructing missing facts.
WorkspaceEdit plan retries compare the parsed edit JSON and position encoding
(default utf-16) before reading target files. Keep any @file input available
and unchanged for a retry. Older versions identified these requests by converted
operations: their WorkspaceEdit keys now return IDEMPOTENCY_CONFLICT, while
saved plan IDs remain usable. New planning requests need new keys.
Parent-traversal paths retain .. in mutation request identities. Older keys
whose recorded inputs removed those components can return IDEMPOTENCY_CONFLICT;
their saved plan and operation IDs remain available. Use a new key for a new request.
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. The journal uses schema 2.
Opening a schema-1 store saves a consistent *.pre-v2-from-v1-*.sqlite3 backup
beside the database and preserves its insertion order during the upgrade.
Older binaries refuse the upgraded store; keep the newer binary for continued
use of that history.
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.