Threadmoth: a deterministic, source-preserving mutation boundary for AI coding agents

Matthew Watkins — Fri, 04 Sep 2026 20:32:45 +0000

I kept seeing the same failure in AI-assisted coding: the agent chose the right change, then applied it through an improvised mix of sed, regex replacement, patches, one-off scripts, direct writes, or whole-file rewrites.

The problem is not that those tools are bad. The problem is that each path has different rules for ambiguity, stale state, preservation, failure, and evidence. The agent is left responsible for deciding whether the final write was safe.

So I built Threadmoth, a small Rust CLI for the last mile of repository editing.

The boundary

Threadmoth turns a requested mutation into a narrow pipeline:

OBSERVE → IDENTIFY → GUARD → MUTATE → VERIFY → CERTIFY

It checks the bytes it read, identifies the intended target, refuses ambiguous or stale requests, applies only the authorised effect, reads the result back, and returns machine-readable evidence.

The current implementation includes:

exact identity and stale-file checks;
cardinality refusal when a target is ambiguous;
Tree-sitter structural targeting for code and web formats;
explicit effect budgets;
source-preserving byte edits;
guarded multi-file transactions with recovery; and
post-write certificates containing hashes, changed ranges, bounded diff evidence, and commit verification.

The important design constraint is that Threadmoth does not try to replace specialist tools. rustfmt, Prettier, Black, gofmt, jq, AST tooling, and similar tools can still decide the desired state. Threadmoth bounds and verifies what lands.

The parser gets to point at the cloth. It doesn’t get to re-weave it.

What I’m testing

Threadmoth 1.5.1 is released for Windows and Linux under the MIT license. Hosted Linux and Windows CI passed. Local correctness-checked runs reported 8/8 tough cases with zero wrong mutations, and torture reported FOOTGUN-100 safe 100/100.

Those are release checks, not proof that the tool is useful in every agent workflow. I’m now running a public field test and looking for people to try one or two real repository mutations with Codex, Claude Code, Gemini CLI, Cline, OpenCode, or another coding agent.

The feedback I want is specific:

Did the agent discover Threadmoth without being spoon-fed its request schema?
Did it choose Threadmoth when the task fit?
Did a valid edit get refused?
Did an unsafe or stale edit get refused correctly?
Were unrelated bytes preserved?
If Threadmoth was unavailable or not selected, what did the agent use instead?

Repo: https://github.com/matthewjameswatkins1978-cyber/Suture
Release: https://github.com/matthewjameswatkins1978-cyber/Suture/releases/tag/v1.5.1
Five-minute field test: https://github.com/matthewjameswatkins1978-cyber/Suture/blob/main/FIELD_TESTING.md

I’m the developer and this is my project. Parts of the implementation and testing were AI-assisted; I’m responsible for the architecture, integration, and release. Specific breakage is more useful than a star.

DEV Community: Matthew Watkins

Threadmoth: a deterministic, source-preserving mutation boundary for AI coding agents

The boundary

What I’m testing