Docs / Review before save

Review before save.

No GridPath tool writes to your file except save_workbook. Everything else accumulates as pending batches you can inspect, reject and save from a local review page.

Pending batches

Each write tool call becomes one batch: set_cell is one batch of one mutation, a run_script that writes 2,000 cells is one batch of 2,000. Batches apply to an in-memory model of the workbook, so the agent's next read sees them, but the .xlsx on disk is untouched.

Every write returns the batch id, a readback of what landed, the number of pending batches, and a review_url:

{
  "ok": true,
  "batch_id": "b3",
  "write_check": "ok",
  "cells": [ { "sheet": "Model", "cell": "F12", "value": 1250, "formula": "=E12*1.05" } ],
  "row_map": [ { "sheet": "Model", "row": 12, "label": "Revenue" } ],
  "pending_batches": 3,
  "review_url": "http://127.0.0.1:51234/review?path=…&token=…",
  "note": "Changes are pending in memory. …"
}

Batches are also written to disk next to the workbook, at .gridpath/<file>.batches.json, so they survive the agent's session ending and a later gridpath review can pick them up.

The review page

The review_url opens a page served by the MCP server on loopback only. The address carries a per-process token, so another web page cannot drive it. The page shows:

• The workbook, sheet by sheet, with changed cells highlighted and the first change already in view.
• Before and after for each changed cell: value, formula and display text.
• A panel of pending batches, each named for the tool that produced it, with its mutation count.

From there you can:

• Accept a batch, or Accept all.
• Reject a batch. The remaining batches are replayed onto a fresh model, so a later edit that depended on the rejected one may change. Check the page again.
• Reject individual cells inside a batch and keep the rest.
• Save to file, which patches the original in place and clears the batches.
• Save as, which writes a patched copy to a path you choose and leaves the original and its pending batches exactly as they were.

Review-required mode

Start the server with --review-required, or set GRIDPATH_REVIEW_REQUIRED=true, and the agent cannot save. save_workbook returns the review link with saved: false and a note telling the agent to hand you the link:

{
  "ok": true,
  "saved": false,
  "pending_batches": 3,
  "review_url": "http://127.0.0.1:51234/review?path=…&token=…",
  "note": "This server requires human review before saving. …"
}

The Claude Desktop bundle turns this on by default. One exception: save_workbook with as still writes a copy, because the original is never touched.

Without the flag, the agent may call save_workbook itself. The review link still comes back with every write, so you can inspect afterwards.

What the agent can do with batches

• list_batches: pending batches with ids, status and mutation counts, plus the review link.
• reject_batch: drop one batch by id. Same replay behaviour as rejecting from the page.
• save_workbook: write every pending batch, or with as write a copy.

What save does to the file

Save diffs the in-memory model against the file as it was loaded and rewrites only the zip parts an edit touched, typically one sheet XML and the shared strings. Untouched parts are copied through byte for byte: charts, pivot caches, vbaProject.bin, add-in data, custom XML, themes, printer settings. If an edit cannot be represented as a surgical patch, the save is refused with a reason instead of falling back to a full rewrite. See Fidelity.

Reopening a review later

npx -y gridpath review ~/models/forecast.xlsx

Starts a review server for that workbook's pending batches and opens the page in your browser. Press Ctrl-C when you are done.

Found a mistake? Open an issue or email support@gridpath.dev.