Edit safely: the three tools that stop an AI agent trashing your files

Giving an AI agent edit access to a real business file is the bit that makes people nervous — and rightly so. A free, open-source plugin released this week packages the three editing primitives that let an agent change a line, a paragraph or a query without ever touching the rest of the document.

The plugin is datasette-agent-edit, a base plugin for the Datasette Agent ecosystem (a set of extensions that give an AI assistant direct access to a SQLite database and the files around it). It’s an alpha release — 0.1a0 — so the audience is firmly tinkerers. But the design pattern it borrows is the part worth understanding, because every team that builds or buys an “AI edits my files” feature will end up reinventing it.

What the three tools actually do

The plugin gives the agent exactly three ways to touch a file, and nothing else. They’re lifted from the design Anthropic uses for Claude’s own text editor — which Simon Willison calls his favourite published pattern for safe agentic editing.

• view — returns a slice of the file with line numbers, so the agent can see exactly what’s there before changing anything. There is no “rewrite the whole file” shortcut.
• str_replace — finds an exact string and swaps it for a new one. The operation fails if the original string isn’t found, or if it appears more than once. The agent has to know what it is replacing.
• insert — drops new text after a specified line number. Used carefully, it lets the agent append a line, a paragraph or a chunk of code without disturbing the rest.

The point of str_replace isn’t the syntax. It’s the constraint: an agent that has to quote back the exact text it is replacing is an agent that cannot accidentally rewrite your whole price list because it hallucinated the third line.

That last rule is the safety layer. A model that can only replace a string it can identify precisely — and only when that string is unique in the file — is a model that simply cannot clobber the surrounding text. It’s the same logic a careful human editor uses with Find and Replace, codified for software.

Why the pattern matters for any business

Most agent failures on real files aren’t dramatic. They’re the small ones: a marketing assistant rewrites your product description and drops a line; a finance bot edits a SQL query and loses a comment; a docs helper reformats a whole page to “tidy it up.” The pattern in this plugin makes those failure modes structurally impossible.

For UK SMEs thinking about deploying agents, that’s the real news. We’ve written before about guardrails you can wrap around an agent before it goes near anything important. File-editing primitives are the inner version of those guardrails: a constraint built into the tool the agent uses, so even a confused or hallucinating model cannot smash the file.

The plugin is also storage-agnostic. The same three tools can be wired up to edit Markdown files, large SQL queries, SVG drawings or any other piece of text — which is exactly the use case Simon flags: collaborative Markdown editing, query tweaks, design files. For a small team, that’s the difference between “agent helps me draft” and “agent silently edits the source of truth.”

How to try it this afternoon

This is alpha software, so treat it as a tinkerer’s tool, not a production system. You’ll need Python 3.10 or later, the Datasette CLI, and an LLM provider configured for Datasette Agent.

• Install the lot in one line: pip install datasette datasette-agent-edit
• Add an LLM provider: follow the datasette-agent quickstart for Anthropic, OpenAI, or a local model via Ollama — our LM Studio vs Ollama comparison covers the local angle.
• Point it at a database: datasette serve my-database.db --open and enable the agent on a writable table.
• Try the pattern: open a Markdown file, ask the agent to change one paragraph, and watch which of the three tools it picks. The point isn’t the demo — it’s seeing in the logs that the model could only replace the exact string you specified.

If you don’t run Datasette, you can still steal the pattern. The three-tool contract is small and self-contained; lift the logic into whatever agent framework you’re already using. Our case study on building an agent-run site in 24 hours relies on similar primitives under the hood — and we wish we’d had this exact contract when we started.

What this means for your business

The plugin itself is a niche, alpha release for people who already live in the Datasette world. Treat it as a free textbook, not a finished product. The lesson is the contract: if you’re buying or building a feature that lets an AI edit a real file in your business, the only safe shape is one that constrains the agent to view, exact-string replace, or line-anchored insert. Anything looser is a future incident report.

The cheapest thing you can do this afternoon is ask whichever vendor is selling you an “AI edits your documents” feature exactly which primitives their agent is allowed to use. If the answer is “the whole file,” push back.