go-surgeon: A Go AST Precision Code Editing Tool for LLM Agents

go-surgeon is a Go code editing tool specifically designed for AI agents. It provides deterministic byte-level code modification capabilities based on Abstract Syntax Tree (AST), completely solving the indentation hallucination and syntax error issues that LLMs face when editing Go code.

When Large Language Models (LLMs) attempt to modify existing code, they usually rely on general text replacement tools like diff code blocks or regular expressions. These methods are theoretically simple and straightforward, but in practice, they have many hidden risks:

• Indentation Hallucination: LLMs often make mistakes in the indentation levels of code blocks, leading to invalid syntax
• Context Loss: Standard text replacement may accidentally break surrounding comments, docstrings, or formatting
• Infinite Loops: When modifications introduce syntax errors, agents may get stuck in an endless loop of repeated fixes
• Context Window Waste: To understand code structure, agents often need to load thousands of lines of code into the context window

For Go, a language extremely sensitive to format and syntax, these problems are particularly prominent.

go-surgeon fundamentally changes the way LLMs interact with Go code. Instead of relying on fragile text replacement, it provides a deterministic byte-level operation interface based on Go's Abstract Syntax Tree (AST).

Zero Indentation Errors: By precisely locating byte offsets in the AST, agents only need to provide the original code block— the tool automatically handles indentation and imports. The built-in goimports integration ensures correct code formatting and complete dependencies after each modification.

Perfect Context Preservation: Unlike standard AST mutations, go-surgeon's byte-range engine preserves all surrounding comments and synchronously updates Godoc blocks, ensuring code maintainability remains unaffected.

Maximize Context Window Efficiency: The tool acts as a CLI version of the Language Server Protocol (LSP). Agents can query function signatures, documentation, and code bodies via graph and symbol commands without loading entire large files into the context window.

Significantly Reduce Round Trips: By atomically updating complex methods, interfaces, or structs, a single operation completes modification tasks that originally required multiple rounds of interaction.

The graph command provides a panoramic view of the project structure:

• Lists import paths of all Go packages
• Displays all exported types, functions, and methods in the subtree via the --symbols --dir parameters
• Context window management flags (--depth, --focus, --exclude, --token-budget) allow agents to explore incrementally without exceeding the token budget.

The symbol command supports precise code snippet extraction:

• Extracts function signatures, documentation, or complete code bodies
• Smart compression: Automatically removes blank lines to save LLM tokens
• Supports precise lookup of Receiver.Method for quick target location.

go-surgeon provides a series of specialized subcommands for code modification:

• add-func: Add a new function
• update-func: Update an existing function
• delete-func: Delete a function
• add-struct: Add a struct
• add-interface: Add an interface

Each subcommand accepts raw Go source code via stdin and passes metadata through --flags. goimports runs automatically after each mutation to ensure correct code formatting and imports.

Interface Mock Generation: The mock command can create or update interfaces and their function field mock implementations in one step, automatically keeping them in sync.

Interface Implementation: The implement command automatically generates missing method stubs for structs to satisfy any interface (standard library, third-party, or project-local), scanning the entire package to prevent cross-file duplicates.

External Interface Mocking: The external-mock command allows generating function field mocks for interfaces you don't own, without modifying the interface file itself.