How AI Agents Actually Edit Code Using Python

Ask most people how a coding agent "edits your code," and the honest answer disappoints them: it generates a block of text that looks like a diff, and a separate tool applies that diff to your files — the same way a human running git apply would. The model isn't manipulating a parsed representation of your code. It's pattern-matching on text. Python has a genuinely different toolkit for this problem, and understanding it explains both why some agent edits fail in confusing ways and where agent tooling is actually headed.

TL;DR

Why "the agent edited my file" usually means "it wrote a diff"

Every major coding agent harness — Claude Code, Aider, Cursor, OpenHands, OpenCode — follows roughly the same loop for a file edit: the model reads the relevant file content (or a slice of it) as plain text, generates a proposed change also as plain text (usually a unified diff, or an explicit old-string/new-string pair), and a tool applies that change to disk. The LLM never receives, and never produces, anything resembling a parsed representation of the code's structure.

This works remarkably well most of the time, for a simple reason: LLMs are trained on enormous volumes of real commit diffs, so generating a plausible-looking patch is exactly the kind of task they're statistically good at. But it also means the model's "understanding" of your code is whatever it can infer from reading the surrounding text — it doesn't know, in any formal sense, that a function it's editing is called from three other files, or that renaming a variable would collide with an existing name in the same scope, unless that context happens to be visible in the text it was shown.

Where text-diff editing actually breaks

The failure modes of diff-based editing are specific and recognizable if you've used any coding agent for more than a few sessions:

• Diff doesn't apply cleanly. If the file changed slightly since the model last read it — a different agent turn touched it, or line numbers shifted — a line-based patch can fail to find its anchor text, and the harness has to retry or fall back to a full-file rewrite.
• Syntactically invalid output. The model can produce a diff that looks locally correct but breaks the file when applied — an unclosed bracket, a misindented block in Python specifically, a duplicate definition — because nothing in the pipeline checks validity before writing to disk.
• Silent scope collisions. Renaming a variable via text substitution can accidentally rename an unrelated variable that happens to share the same name in a different scope, because plain-text search-and-replace has no concept of lexical scope.
• Formatting drift. Repeated diff-based edits gradually accumulate whitespace and style inconsistencies that a structural tool wouldn't introduce, because the model is generating fresh text rather than modifying an existing tree in place.

None of these are exotic edge cases — they're the ordinary cost of treating source code as unstructured text, which is precisely the problem a parsed representation is built to solve.

The Python toolkit for structural code editing

Python's ecosystem has a mature, layered set of tools for treating code as a tree instead of a string, each suited to a different job:

ast — the standard library baseline

Python ships an ast module that parses source into an Abstract Syntax Tree and can walk, inspect, and modify it. It's the right tool for analysis — finding every function call to a given name, checking whether a file imports a specific module, computing complexity metrics — but it's a poor fit for editing, because ast.unparse() regenerates source code without preserving the original formatting, comments, or blank-line structure. Round-tripping a file through ast and back tends to produce code that's correct but unrecognizable from what a human wrote.

import ast

tree = ast.parse(source_code)
for node in ast.walk(tree):
    if isinstance(node, ast.FunctionDef) and node.name == "old_name":
        node.name = "new_name"
# ast.unparse(tree) works, but reformats everything

libcst — the formatting-preserving alternative

libcst (originally built at Instagram, now widely used across the Python tooling ecosystem) parses code into a Concrete Syntax Tree rather than an abstract one — meaning it retains every comment, blank line, and whitespace detail as part of the tree. Editing with libcst and writing the tree back out reproduces the original file byte-for-byte except for the specific change you made, which is exactly the property an agent needs: a surgical edit, not a full-file regeneration.

import libcst as cst

class RenameFunction(cst.CSTTransformer):
    def leave_FunctionDef(self, original_node, updated_node):
        if updated_node.name.value == "old_name":
            return updated_node.with_changes(
                name=cst.Name("new_name")
            )
        return updated_node

module = cst.parse_module(source_code)
modified = module.visit(RenameFunction())
new_source = modified.code  # formatting-preserving output

rope — a full refactoring engine

rope is a longstanding Python refactoring library (it predates the current AI-agent wave by well over a decade, originally built to power IDE refactoring features) that implements whole operations, not just tree edits: rename-across-project, extract-method, move-module, inline-variable. For an agent, rope is valuable specifically because it handles cross-file consistency — a project-wide rename that libcst alone would require you to orchestrate manually across every file that imports the renamed symbol.

tree-sitter — fast, multi-language, incremental parsing

tree-sitter isn't Python-specific — it's a parser generator used by editors like Neovim and VS Code for real-time syntax highlighting — but it has a Python binding and is increasingly showing up inside agent harnesses for code navigation and context retrieval rather than editing per se: quickly finding "every class definition in this 50,000-line repo" without running a full language-specific compiler front end, and doing it incrementally as files change during an agent session.

A minimal working example: a rename tool an agent can call

The practical pattern for wiring this into an actual agent isn't "give the LLM libcst and hope it writes correct transformer code on the fly" — it's building a small library of named, tested transformation functions the model can call as tools, the same way it calls a file-read or shell-execute tool today:

import libcst as cst

def rename_function(source: str, old_name: str, new_name: str) -> str:
    """A tool an agent calls with two strings — not a code-writing task."""
    class Renamer(cst.CSTTransformer):
        def leave_FunctionDef(self, original_node, updated_node):
            if updated_node.name.value == old_name:
                return updated_node.with_changes(name=cst.Name(new_name))
            return updated_node

        def leave_Call(self, original_node, updated_node):
            func = updated_node.func
            if isinstance(func, cst.Name) and func.value == old_name:
                return updated_node.with_changes(
                    func=cst.Name(new_name)
                )
            return updated_node

    tree = cst.parse_module(source)
    return tree.visit(Renamer()).code

The agent's job shifts from "generate a correct diff" to "decide that a rename is the right operation, and supply the two names" — a much narrower, much more reliable task for an LLM to get right, because the actual code transformation is handled by tested, deterministic code rather than freeform generation.

Where this fits in real agent harnesses today

This pattern already exists inside the tools you're likely using, just not always visible: language servers (via the LSP (Language Server Protocol)) expose rename-symbol and find-references as structured operations any editor or agent can call, and several agent harnesses route rename and move operations through a language server rather than a raw text edit specifically to get this reliability. explainx.ai's coverage of minimal agent harnesses like pi and the broader self-harness pattern both touch this design question — how much structure to give an agent's tools versus how much to leave to the model's own judgment on raw text.

The realistic picture for 2026 is a hybrid, not a replacement: diffs remain the default for open-ended edits because they're language-agnostic and match how models were trained, while structural, AST-based tools get reached for specifically on the operations where correctness matters more than flexibility — renames, signature changes, import reorganization, and other refactors where "syntactically guaranteed valid" is worth the cost of building a language-specific tool.

Honest limitations

• AST validity is not logical correctness. A structurally valid edit can still be the wrong edit — parsing guarantees the file compiles, not that the change does what was intended.
• One parser per language. libcst and ast are Python-only; a multi-language codebase needs separate tooling (or tree-sitter's broader language support) for the same guarantees elsewhere.
• Cross-file consistency is still hard. rope handles some of this, but a rename that needs to also update a string literal, a config file, or a docstring reference typically falls back to text-based search regardless of how the code edit itself was made.
• Building transformer functions has a real cost. Each new structural operation (extract-method, inline-variable, add-parameter) requires writing and testing its own tree-walking logic — this doesn't scale to "handle any possible edit" the way a general diff tool does.

The takeaway

When a coding agent successfully edits a file, in the overwhelming majority of cases today it did so by generating text that looks like a patch, not by understanding your code's structure the way a compiler or an IDE's refactoring tool does. Python's ast, libcst, rope, and tree-sitter give agent builders a genuine alternative for the operations where that distinction matters — turning "the model wrote something plausible" into "the tool guarantees the result parses," which is a meaningfully different and stronger claim for the narrow set of edits worth building it for.

Related on explainx.ai:

• Claude Code Commands: Complete Reference Guide — how one major harness structures its editing tools
• What Is Self-Harness? AI Agents That Improve Themselves — the broader pattern of agents building their own tooling
• Pi: A Minimal Agent Harness Guide — a harness built from first principles, useful for seeing the tool-calling loop directly
• OpenCode: Open-Source AI Coding Agent Guide — an open harness whose file-editing tools are inspectable
• Code Review Graph: Token-Efficient AI Code Review — a related structural approach applied to review instead of editing
• What Are Agent Skills? Complete Guide — packaging a capability like structural editing as a reusable skill

Library APIs referenced here (libcst, rope, tree-sitter) evolve between releases — check each project's current documentation before relying on the exact method signatures shown.