{ "@context": "https://schema.org", "@id": "https://aggr.aymericbeaumet.com/items/ampcode-com/2025-04-15-how-to-build-an-agent/#webpage", "@type": [ "WebPage", "ArchiveComponent" ], "articleBody": "Thorsten Ball//April 15, 2025\n\nor: The Emperor Has No Clothes\n\nIt’s not that hard to build a fully functioning, code-editing agent.\n\nIt seems like it would be. When you look at an agent editing files, running commands, wriggling itself out of errors, retrying different strategies - it seems like there has to be a secret behind it.\n\nThere isn’t. It’s an LLM, a loop, and enough tokens. It’s what we’ve been saying on the [podcast](https://ampcode.com/podcast) from the start. The rest, the stuff that makes [Amp](https://ampcode.com/) so addictive and impressive? Elbow grease.\n\nBut building a small and yet highly impressive agent doesn’t even require that. You can do it in less than 400 lines of code, most of which is boilerplate.\n\nI’m going to show you how, right now. We’re going to write some code together and go from zero lines of code to “oh wow, this is… a game changer.”\n\nI *urge* you to follow along. No, really. You might think you can just read this and that you don’t have to type out the code, but it’s less than 400 lines of code. I need you to *feel* how little code it is and I want you to see this with your own eyes in your own terminal in your own folders.\n\nHere’s what we need:\n\n- [Go](https://go.dev/)\n- [Anthropic API key](https://console.anthropic.com/settings/keys) that you set as an environment variable, `ANTHROPIC_API_KEY`\n\n## Pencils out!\n\nLet’s dive right in and get ourselves a new Go project set up in four easy commands:\n\n```shell\nmkdir code-editing-agent\ncd code-editing-agent\ngo mod init agent\ntouch main.go\n```\n\nNow, let’s open `main.go` and, as a first step, put a skeleton of things we need in it:\n\n```go\npackage main\n\nimport (\n\t\"bufio\"\n\t\"context\"\n\t\"fmt\"\n\t\"os\"\n\n\t\"github.com/anthropics/anthropic-sdk-go\"\n)\n\nfunc main() {\n\tclient := anthropic.NewClient()\n\n\tscanner := bufio.NewScanner(os.Stdin)\n\tgetUserMessage := func() (string, bool) {\n\t\tif !scanner.Scan() {\n\t\t\treturn \"\", false\n\t\t}\n\t\treturn scanner.Text(), true\n\t}\n\n\tagent := NewAgent(&client, getUserMessage)\n\terr := agent.Run(context.TODO())\n\tif err != nil {\n\t\tfmt.Printf(\"Error: %s\\n\", err.Error())\n\t}\n}\n\nfunc NewAgent(client *anthropic.Client, getUserMessage func() (string, bool)) *Agent {\n\treturn &Agent{\n\t\tclient: client,\n\t\tgetUserMessage: getUserMessage,\n\t}\n}\n\ntype Agent struct {\n\tclient *anthropic.Client\n\tgetUserMessage func() (string, bool)\n}\n```\n\nYes, this doesn’t compile yet. But what we have here is an `Agent` that has access to an `anthropic.Client` (which, by default, looks for `ANTHROPIC_API_KEY`) and that can get a user message by reading from stdin on the terminal.\n\nNow let’s add the missing `Run()` method:\n\n```go\n// main.go\n\nfunc (a *Agent) Run(ctx context.Context) error {\n\tconversation := []anthropic.MessageParam{}\n\n\tfmt.Println(\"Chat with Claude (use 'ctrl-c' to quit)\")\n\n\tfor {\n\t\tfmt.Print(\"\\\\u001b[94mYou\\\\u001b[0m: \")\n\t\tuserInput, ok := a.getUserMessage()\n\t\tif !ok {\n\t\t\tbreak\n\t\t}\n\n\t\tuserMessage := anthropic.NewUserMessage(anthropic.NewTextBlock(userInput))\n\t\tconversation = append(conversation, userMessage)\n\n\t\tmessage, err := a.runInference(ctx, conversation)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tconversation = append(conversation, message.ToParam())\n\n\t\tfor _, content := range message.Content {\n\t\t\tswitch content.Type {\n\t\t\tcase \"text\":\n\t\t\t\tfmt.Printf(\"\\\\u001b[93mClaude\\\\u001b[0m: %s\\n\", content.Text)\n\t\t\t}\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc (a *Agent) runInference(ctx context.Context, conversation []anthropic.MessageParam) (*anthropic.Message, error) {\n\tmessage, err := a.client.Messages.New(ctx, anthropic.MessageNewParams{\n\t\tModel: anthropic.ModelClaude3_7SonnetLatest,\n\t\tMaxTokens: int64(1024),\n\t\tMessages: conversation,\n\t})\n\treturn message, err\n}\n```\n\nIt’s not a lot, is it? 90 lines and the most important thing in them is this loop in `Run()` that lets us talk to Claude. But that’s already the heartbeat of this program.\n\nAnd for a heartbeat, it’s pretty straightforward: we first print a prompt, ask the user to type something, add it to the conversation, send it to Claude, add Claude’s response to the conversation, print the response, and around we go.\n\nThis is every AI chat application you’ve ever used, except it’s in the terminal.\n\nLet’s run it:\n\n```shell\nexport ANTHROPIC_API_KEY=\"this is the last time i will tell you to set this\"\n\n# Download the dependencies\ngo mod tidy\n# Run it\ngo run main.go\n```\n\nThen you can just talk to Claude, like this:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: Hey! I'm Thorsten! How are you?\n\nClaude: Hi Thorsten! I'm doing well, thanks for asking. It's nice to meet you. How are you doing today? Is there something I can help you with?\n\nYou: Can you come up with any horse-related nicknames that make fun of my first name?\n\nClaude: I can try to come up with some playful horse-related nicknames based on \"Thorsten\": \\* Thorough-bred Thorsten \\* Trotsten \\* Thorsten the Stallion \\* Neighsten \\* Horseten \\* Thorsten the Galloper \\* Saddle-sten \\* Thorsten of the Mane \\* Canter-sten \\* Thorsteed These are meant to be lighthearted - I hope they give you a chuckle!\n\nYou:\n\nNotice how we kept the same conversation going over multiple turns. It remembers my name from the first message. The `conversation` grows longer with every turn and we send the whole conversation every time. The server — Anthropic’s server — is stateless. It only sees what’s in the `conversation` slice. It’s up to us to maintain that.\n\nOkay, let’s move on, because the nicknames suck and this is not an agent yet. What’s an agent? Here’s [my definition](https://youtu.be/J1-W9O3n7j8?t=72): an LLM with *access to tools*, giving it the ability to modify something outside the context window.\n\n## A First Tool\n\nAn LLM with *access to tools*? What’s a tool? The basic idea is this: you send a prompt to the model that says it should reply in a certain way if it wants to use “a tool”. Then you, as the receiver of that message, “use the tool” by executing it and replying with the result. That’s it. Everything else we’ll see is just abstraction on top of it.\n\nImagine you’re talking to a friend and you tell them: “in the following conversation, wink if you want me to raise my arm”. Weird thing to say, but an easy concept to grasp.\n\nWe can already try it without changing any of our code.\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: You are a weather expert. When I ask you about the weather in a given location, I want you to reply with \\`get\\_weather(\\)\\`. I will then tell you what the weather in that location is. Understood?\n\nClaude: I understand your instructions. When you ask me about the weather in a specific location, I will reply with \\`get\\_weather(\\)\\`. Then you'll provide me with the weather information for that location, and I can discuss it further with you. I'm ready whenever you'd like to ask about the weather somewhere.\n\nYou: Hey, what's the weather in Munich?\n\nClaude: get\\_weather(Munich)\n\nWe told Claude to wink with `get_weather` when it wants to know about the weather. The next step is to raise our arm and reply with “result of the tool”:\n\nYou: hot and humid, 28 degrees celcius\n\nClaude: Thank you for providing that information. The current weather in Munich is hot and humid at 28 degrees Celsius (about 82 degrees Fahrenheit). These are fairly warm conditions for Munich, especially with the added humidity which can make it feel even warmer than the temperature indicates. If you're in Munich or planning to visit, it would be good to stay hydrated, wear light clothing, and perhaps plan indoor activities during the hottest parts of the day. The combination of heat and humidity can be quite uncomfortable, particularly if you're not accustomed to such weather. Would you like to know about the weather in any other location?\n\nThat worked very well, on first try, didn’t it?\n\nThese models are trained and fine-tuned to use “tools” and they’re very eager to do so. By now, 2025, they kinda “know” that they don’t know everything and can use tools to get more information. (Of course that’s not precisely what’s going on, but it’s good enough an explanation for now.)\n\nTo summarize, all there is to tools and tool use are two things:\n\n1. You tell the model what tools are available\n2. When the model wants to execute the tool, it tells you, you execute the tool and send the response up\n\nTo make (1) easier, the big model providers have built-in APIs to send tool definitions along.\n\nOkay, now let’s build our first tool: `read_file`\n\n## The `read_file` tool\n\nIn order to define the `read_file` tool, we’re going to use the types that the Anthropic SDK suggests, but keep in mind: under the hood, this will all end up as strings that are sent to the model. It’s all “wink if you want me to use `read_file`“.\n\nEach tool we’re going to add will require the following:\n\n- A name\n- A description to tell the model what the tool does, when to use it, when to not use it, what it returns and so on\n- An input schema that describes, as a JSON schema, what inputs this tool expects and in which form\n- A function that actually executes the tool with the input the model sends to us and returns the result\n\nSo let’s add that to our code:\n\n```go\n// main.go\n\ntype ToolDefinition struct {\n\tName string `json:\"name\"`\n\tDescription string `json:\"description\"`\n\tInputSchema anthropic.ToolInputSchemaParam `json:\"input_schema\"`\n\tFunction func(input json.RawMessage) (string, error)\n}\n```\n\nNow we give our `Agent` tool definitions:\n\n```go\n// main.go\n\n// `tools` is added here:\ntype Agent struct {\n\tclient *anthropic.Client\n\tgetUserMessage func() (string, bool)\n\ttools []ToolDefinition\n}\n\n// And here:\nfunc NewAgent(\n\tclient *anthropic.Client,\n\tgetUserMessage func() (string, bool),\n\ttools []ToolDefinition,\n) *Agent {\n\treturn &Agent{\n\t\tclient: client,\n\t\tgetUserMessage: getUserMessage,\n\t\ttools: tools,\n\t}\n}\n\n// And here:\nfunc main() {\n // [... previous code ...]\n\ttools := []ToolDefinition{}\n\tagent := NewAgent(&client, getUserMessage, tools)\n\n // [... previous code ...]\n}\n```\n\nAnd send them along to the model in `runInference`:\n\n```go\n// main.go\n\nfunc (a *Agent) runInference(ctx context.Context, conversation []anthropic.MessageParam) (*anthropic.Message, error) {\n\tanthropicTools := []anthropic.ToolUnionParam{}\n\tfor _, tool := range a.tools {\n\t\tanthropicTools = append(anthropicTools, anthropic.ToolUnionParam{\n\t\t\tOfTool: &anthropic.ToolParam{\n\t\t\t\tName: tool.Name,\n\t\t\t\tDescription: anthropic.String(tool.Description),\n\t\t\t\tInputSchema: tool.InputSchema,\n\t\t\t},\n\t\t})\n\t}\n\n\tmessage, err := a.client.Messages.New(ctx, anthropic.MessageNewParams{\n\t\tModel: anthropic.ModelClaude3_7SonnetLatest,\n\t\tMaxTokens: int64(1024),\n\t\tMessages: conversation,\n\t\tTools: anthropicTools,\n\t})\n\treturn message, err\n}\n```\n\nThere’s a bunch of type shenanigans going on and I’m not too good in Go-with-generics yet so I’m not going to try to explain `anthropic.String` and `ToolUnionParam` to you. But, really, I swear, it’s very simple:\n\nWe send along our tool definitions, on the server Anthropic then wraps these definitions in [this system prompt](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview#tool-use-system-prompt) (which isn’t much), which it adds to our `conversation`, and the model then replies in a specific way if it wants to use that tool.\n\nAlright, so tool definitions are being sent along, but we haven’t defined a tool yet. Let’s do that and define `read_file`:\n\n```go\n// main.go\n\nvar ReadFileDefinition = ToolDefinition{\n\tName: \"read_file\",\n\tDescription: \"Read the contents of a given relative file path. Use this when you want to see what's inside a file. Do not use this with directory names.\",\n\tInputSchema: ReadFileInputSchema,\n\tFunction: ReadFile,\n}\n\ntype ReadFileInput struct {\n\tPath string `json:\"path\" jsonschema_description:\"The relative path of a file in the working directory.\"`\n}\n\nvar ReadFileInputSchema = GenerateSchema[ReadFileInput]()\n\nfunc ReadFile(input json.RawMessage) (string, error) {\n\treadFileInput := ReadFileInput{}\n\terr := json.Unmarshal(input, &readFileInput)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tcontent, err := os.ReadFile(readFileInput.Path)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\treturn string(content), nil\n}\n\nfunc GenerateSchema[T any]() anthropic.ToolInputSchemaParam {\n\treflector := jsonschema.Reflector{\n\t\tAllowAdditionalProperties: false,\n\t\tDoNotReference: true,\n\t}\n\tvar v T\n\n\tschema := reflector.Reflect(v)\n\n\treturn anthropic.ToolInputSchemaParam{\n\t\tProperties: schema.Properties,\n\t}\n}\n```\n\nThat’s not much, is it? It’s a single function, `ReadFile`, and two descriptions the model will see: our `Description` that describes the tool itself (`\"Read the contents of a given relative file path. ...\"`) and a description of the single input parameter this tool has (`\"The relative path of a ...\"`).\n\nThe `ReadFileInputSchema` and `GenerateSchema` stuff? We need that so that we can generate a JSON schema for our tool definition which we send to the model. To do that, we use the `jsonschema` package, which we need to import and download:\n\n```go\n// main.go\n\npackage main\n\nimport (\n\t\"bufio\"\n\t\"context\"\n // Add this:\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"os\"\n\n\t\"github.com/anthropics/anthropic-sdk-go\"\n // Add this:\n\t\"github.com/invopop/jsonschema\"\n)\n```\n\nThen run the following:\n\n```text\ngo mod tidy\n```\n\nThen, in the `main` function, we need to make sure that we use the definition:\n\n```go\nfunc main() {\n // [... previous code ...]\n\ttools := []ToolDefinition{ReadFileDefinition}\n // [... previous code ...]\n}\n```\n\nTime to try it!\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: what's in main.go?\n\nClaude: I'll help you check what's in the main.go file. Let me read it for you.\n\nYou:\n\nWait, what? Ho, ho, ho, it wants to use the tool! Obviously the output will be slightly different for you, but it certainly sounds like Claude knows that it can read files, right?\n\nThe problem is that we don’t listen! When Claude winks, we ignore it. We need to fix that.\n\nHere, let me show you how to do that in a single, quick, surprisingly-agile-for-my-age move by replacing our `Agent`’s `Run` method with this:\n\n```go\n// main.go\n\nfunc (a *Agent) Run(ctx context.Context) error {\n\tconversation := []anthropic.MessageParam{}\n\n\tfmt.Println(\"Chat with Claude (use 'ctrl-c' to quit)\")\n\n\treadUserInput := true\n\tfor {\n\t\tif readUserInput {\n\t\t\tfmt.Print(\"\\\\u001b[94mYou\\\\u001b[0m: \")\n\t\t\tuserInput, ok := a.getUserMessage()\n\t\t\tif !ok {\n\t\t\t\tbreak\n\t\t\t}\n\n\t\t\tuserMessage := anthropic.NewUserMessage(anthropic.NewTextBlock(userInput))\n\t\t\tconversation = append(conversation, userMessage)\n\t\t}\n\n\t\tmessage, err := a.runInference(ctx, conversation)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tconversation = append(conversation, message.ToParam())\n\n\t\ttoolResults := []anthropic.ContentBlockParamUnion{}\n\t\tfor _, content := range message.Content {\n\t\t\tswitch content.Type {\n\t\t\tcase \"text\":\n\t\t\t\tfmt.Printf(\"\\\\u001b[93mClaude\\\\u001b[0m: %s\\n\", content.Text)\n\t\t\tcase \"tool_use\":\n\t\t\t\tresult := a.executeTool(content.ID, content.Name, content.Input)\n\t\t\t\ttoolResults = append(toolResults, result)\n\t\t\t}\n\t\t}\n\t\tif len(toolResults) == 0 {\n\t\t\treadUserInput = true\n\t\t\tcontinue\n\t\t}\n\t\treadUserInput = false\n\t\tconversation = append(conversation, anthropic.NewUserMessage(toolResults...))\n\t}\n\n\treturn nil\n}\n\nfunc (a *Agent) executeTool(id, name string, input json.RawMessage) anthropic.ContentBlockParamUnion {\n\tvar toolDef ToolDefinition\n\tvar found bool\n\tfor _, tool := range a.tools {\n\t\tif tool.Name == name {\n\t\t\ttoolDef = tool\n\t\t\tfound = true\n\t\t\tbreak\n\t\t}\n\t}\n\tif !found {\n\t\treturn anthropic.NewToolResultBlock(id, \"tool not found\", true)\n\t}\n\n\tfmt.Printf(\"\\\\u001b[92mtool\\\\u001b[0m: %s(%s)\\n\", name, input)\n\tresponse, err := toolDef.Function(input)\n\tif err != nil {\n\t\treturn anthropic.NewToolResultBlock(id, err.Error(), true)\n\t}\n\treturn anthropic.NewToolResultBlock(id, response, false)\n}\n```\n\nSquint and you’ll see that it’s 90% boilerplate and 10% that matter: when we get a `message` back from Claude, we check wether Claude asked us to execute a tool by looking for `content.Type == \"tool_use\"`, if so we hand over to `executeTool`, lookup the tool by name in our local registry, unmarshal the input, execute it, return the result. If it’s an error, we flip a boolean. That’s it.\n\n(Yes, there is a loop in a loop, but it doesn’t matter.)\n\nWe execute the tool, send the result back up to Claude, and ask again for Claude’s response. Truly: that’s *it*. Let me show you.\n\nMise-en-place, run this:\n\n```shell\necho 'what animal is the most disagreeable because it always says neigh?' >> secret-file.txt\n```\n\nThat creates a `secret-file.txt` in our directory, containing a mysterious riddle.\n\nIn that very same directory, let’s run our new tool-using agent, and ask it to look at the file:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: Claude, buddy, help me solve the riddle in the secret-file.txt file\n\nClaude: I'll help you solve the riddle in the secret-file.txt file. Let me first read the contents of this file to see what the riddle is.\n\ntool: read\\_file({\"path\":\"secret-file.txt\"})\n\nClaude: Great! I've found the riddle. The answer to the riddle is: \\*\\*A horse\\*\\* The riddle is playing on wordplay where \"neigh\" (the sound a horse makes) sounds like \"nay\" (a way to say \"no\" or disagree with something). So horses are described as disagreeable because they always say \"neigh/nay\" - implying they're always disagreeing.\n\nYou:\n\nLet’s take a deep breath and say it together. Ready? Here we go: *holy shit*. You just give it a tool and it… *uses it when it thinks it’ll help solve the task*. Remember: we didn’t say *anything* about “if a user asks you about a file, read the file”. We also didn’t say “if something looks like a filename, figure out how to read it”. No, none of that. We say “help me solve the thing in this file” and Claude realizes that it can read the file to answer that and off it goes.\n\nOf course, we *can* be specific and really nudge it towards a tool, but it basically does it all on its own:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: What's going on in main.go? Be brief!\n\nClaude: I'll check the main.go file to see what's going on.\n\ntool: read\\_file({\"path\":\"main.go\"})\n\nClaude: Based on my review, main.go implements a Claude AI assistant agent that can use tools. Here's a brief summary: - It creates a command-line chat interface with Claude using the Anthropic Go SDK - Implements a tool system with a single \"read\\_file\" tool for reading file contents - Manages the conversation flow with Claude, handling both regular text responses and tool use requests - When Claude requests to use a tool, the agent executes it and returns the results - The program loops continuously to maintain a conversation until the user exits The code essentially builds a simple CLI-based chatbot that can interact with the file system when requested by Claude.\n\nYou:\n\nSpot on. Okay, now that we know how to make Claude use tools, let’s add a few more.\n\n## The `list_files` tool\n\nIf you’re anything like me, the first thing you do when you log into a new computer is to get your bearings by running `ls` — list files.\n\nLet’s give Claude the same ability, a tool to list files. And here’s the complete implementation of a `list_files` tool:\n\n```go\n// main.go\n\nvar ListFilesDefinition = ToolDefinition{\n\tName: \"list_files\",\n\tDescription: \"List files and directories at a given path. If no path is provided, lists files in the current directory.\",\n\tInputSchema: ListFilesInputSchema,\n\tFunction: ListFiles,\n}\n\ntype ListFilesInput struct {\n\tPath string `json:\"path,omitempty\" jsonschema_description:\"Optional relative path to list files from. Defaults to current directory if not provided.\"`\n}\n\nvar ListFilesInputSchema = GenerateSchema[ListFilesInput]()\n\nfunc ListFiles(input json.RawMessage) (string, error) {\n\tlistFilesInput := ListFilesInput{}\n\terr := json.Unmarshal(input, &listFilesInput)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tdir := \".\"\n\tif listFilesInput.Path != \"\" {\n\t\tdir = listFilesInput.Path\n\t}\n\n\tvar files []string\n\terr = filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\trelPath, err := filepath.Rel(dir, path)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tif relPath != \".\" {\n\t\t\tif info.IsDir() {\n\t\t\t\tfiles = append(files, relPath+\"/\")\n\t\t\t} else {\n\t\t\t\tfiles = append(files, relPath)\n\t\t\t}\n\t\t}\n\t\treturn nil\n\t})\n\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\tresult, err := json.Marshal(files)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\treturn string(result), nil\n}\n```\n\nNothing fancy here: `list_files` returns the list of files and directories in the current folder. There’s a thousand optimizations we could (and probably should) make if this were a serious effort, but since I just want to show you what’s in the wizard’s hat, this is fine.\n\nOne thing to note: we return a list of strings and we denote directories with a trailing slash. That’s not required, it’s just something I just decided to do. There’s no fixed format. Anything goes as long as Claude can make sense of it and whether it can you need to figure out by experimentation. You could also prepend each directory with `\"directory: \"` or return a Markdown document with two headers: `\"directories\"` and `\"files\"`. There’s a ton of options and which one you chose depends on what Claude can make the most sense of, how many tokens it requires, how fast it is to generate and read, and so on.\n\nHere, we just want to create a small `list_files` tool and the easiest option wins.\n\nOf course we need to tell Claude about `list_files` too:\n\n```go\n// main.go\n\nfunc main() {\n\t// [... previous code ...]\n\n\ttools := []ToolDefinition{ReadFileDefinition, ListFilesDefinition}\n\n\t// [... previous code ...]\n}\n```\n\nAnd that’s it. Let’s ask Claude what it can see in this directory.\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: what do you see in this directory?\n\nClaude: I'll help you see what's in the current directory. Let me list the files and directories for you.\n\ntool: list\\_files({})\n\nClaude: I can see several files and directories in the current directory: 1. Git-related files and directories: - \\`.git/\\` directory with various Git configuration and tracking files - \\`.gitignore\\` file 2. Go project files: - \\`main.go\\` - the main Go source code file - \\`go.mod\\` - Go module definition file - \\`go.sum\\` - Go module checksum file 3. Documentation: - \\`blogpost.md\\` - a markdown file, likely containing blog content 4. Environment configuration: - \\`.envrc\\` - likely an environment configuration file Would you like me to examine the contents of any specific file from this list?\n\nYou:\n\nWorks! It can read the directory.\n\nBut here’s the thing: Claude knows how to combine these tools. We just need to prompt it in a way that provokes it:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: Tell me about all the Go files in here. Be brief!\n\nClaude: I'll examine the Go files in the current directory for you. Let me check what files are available first.\n\ntool: list\\_files({})\n\nClaude: I found a Go file in the current directory. Let me examine it:\n\ntool: read\\_file({\"path\":\"main.go\"})\n\ntool: read\\_file({\"path\":\"go.mod\"})\n\nClaude: Here's a brief overview of the Go files in this project: \\*\\*main.go\\*\\*: - Implements a Claude AI agent that can interact with the local filesystem - Uses the Anthropic SDK for Go to communicate with Claude AI models - Provides two tools: \\`read\\_file\\` and \\`list\\_files\\` that allow Claude to read file contents and list directory contents - Manages a conversation flow between the user and Claude, handling tool execution when Claude needs to access files \\*\\*go.mod\\*\\*: - Defines the module dependencies - Main dependencies are the Anthropic SDK for Go and a JSON schema library - Uses Go 1.24.1 This appears to be a simple terminal-based application that allows users to chat with Claude while giving the AI access to read local files and list directories.\n\nYou:\n\nFirst it used the `list_files` and then it called `read_file` twice with the Go-related files that I asked it about.\n\nJust… just like we would, right? I mean, here, what would you do if I ask you what version of Go we use in this project? Here’s what Claude does for me:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: What go version are we using in this project?\n\nClaude: I'll help you find the Go version being used in this project. Let me check the files to locate where the Go version might be specified.\n\ntool: list\\_files({})\n\nClaude: I can see there's a Go project here with several important files like \\`go.mod\\`, \\`go.sum\\`, and \\`main.go\\`. Let me check the \\`go.mod\\` file first, as it typically contains the Go version information.\n\ntool: read\\_file({\"path\":\"go.mod\"})\n\nClaude: According to the \\`go.mod\\` file, this project is using Go version 1.24.1.\n\nClaude looks at the directory, looks at `go.mod`, and has the answer.\n\nWe’re at around 190 lines of code now. Let that sink in. Once you have, let’s add another tool.\n\n## Let it `edit_file`\n\nThe last tool we’re going to add is `edit_file` — a tool that lets Claude edit files.\n\n“Holy shit”, you’re thinking now, “this is where the rubber hits the road, this is where he pulls the rabbit out of the hat.” Well, let’s see, shall we?\n\nFirst, let’s add a definition for our new `edit_file` tool:\n\n```go\n// main.go\n\nvar EditFileDefinition = ToolDefinition{\n\tName: \"edit_file\",\n\tDescription: `Make edits to a text file.\n\nReplaces 'old_str' with 'new_str' in the given file. 'old_str' and 'new_str' MUST be different from each other.\n\nIf the file specified with path doesn't exist, it will be created.\n`,\n\tInputSchema: EditFileInputSchema,\n\tFunction: EditFile,\n}\n\ntype EditFileInput struct {\n\tPath string `json:\"path\" jsonschema_description:\"The path to the file\"`\n\tOldStr string `json:\"old_str\" jsonschema_description:\"Text to search for - must match exactly and must only have one match exactly\"`\n\tNewStr string `json:\"new_str\" jsonschema_description:\"Text to replace old_str with\"`\n}\n\nvar EditFileInputSchema = GenerateSchema[EditFileInput]()\n```\n\nThat’s right, I again know what you’re thinking: “string replacement to edit files?” Claude 3.7 loves replacing strings (experimentation is how you find out what they love or don’t), so we’re going to implement `edit_file` by telling Claude it can edit files by replacing existing text with new text.\n\nNow here’s the implementation of the `EditFile` function in Go:\n\n```go\nfunc EditFile(input json.RawMessage) (string, error) {\n\teditFileInput := EditFileInput{}\n\terr := json.Unmarshal(input, &editFileInput)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\tif editFileInput.Path == \"\" || editFileInput.OldStr == editFileInput.NewStr {\n\t\treturn \"\", fmt.Errorf(\"invalid input parameters\")\n\t}\n\n\tcontent, err := os.ReadFile(editFileInput.Path)\n\tif err != nil {\n\t\tif os.IsNotExist(err) && editFileInput.OldStr == \"\" {\n\t\t\treturn createNewFile(editFileInput.Path, editFileInput.NewStr)\n\t\t}\n\t\treturn \"\", err\n\t}\n\n\toldContent := string(content)\n\tnewContent := strings.Replace(oldContent, editFileInput.OldStr, editFileInput.NewStr, -1)\n\n\tif oldContent == newContent && editFileInput.OldStr != \"\" {\n\t\treturn \"\", fmt.Errorf(\"old_str not found in file\")\n\t}\n\n\terr = os.WriteFile(editFileInput.Path, []byte(newContent), 0644)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\treturn \"OK\", nil\n}\n```\n\nIt checks the input parameters, it reads the file (or creates it if it exists), and replaces the `OldStr` with `NewStr`. Then it writes the content back to disk and returns `\"OK\"`.\n\nWhat’s missing still is `createNewFile`, which is just a tiny helper function that would be 70% shorter if this wasn’t Go:\n\n```go\nfunc createNewFile(filePath, content string) (string, error) {\n\tdir := path.Dir(filePath)\n\tif dir != \".\" {\n\t\terr := os.MkdirAll(dir, 0755)\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"failed to create directory: %w\", err)\n\t\t}\n\t}\n\n\terr := os.WriteFile(filePath, []byte(content), 0644)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to create file: %w\", err)\n\t}\n\n\treturn fmt.Sprintf(\"Successfully created file %s\", filePath), nil\n}\n```\n\nLast step: adding it to the list of tools that we send to Claude.\n\n```go\n// main.go\n\nfunc main() {\n\t// [... previous code ...]\n\n\ttools := []ToolDefinition{ReadFileDefinition, ListFilesDefinition, EditFileDefinition}\n\n\t// [... previous code ...]\n}\n```\n\nAnd… we’re ready, but are *you*? Are you ready to let it rip?\n\nThought so, let’s do this. Let’s tell Claude to create a new FizzBuzz function in JavaScript.\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: hey claude, create fizzbuzz.js that I can run with Nodejs and that has fizzbuzz in it and executes it\n\nClaude: I'll create a fizzbuzz.js file that you can run with Node.js. First, let me check if the file already exists:\n\ntool: list\\_files({})\n\nClaude: I don't see a fizzbuzz.js file, so I'll create one with a classic FizzBuzz implementation. This program will print numbers from 1 to 100, but for multiples of 3 it will print \"Fizz\", for multiples of 5 it will print \"Buzz\", and for numbers that are multiples of both 3 and 5 it will print \"FizzBuzz\".\n\ntool: edit\\_file({\"path\":\"fizzbuzz.js\",\"old\\_str\":\"\",\"new\\_str\":\"/\\*\\*\\\\n \\* FizzBuzz implementation in JavaScript\\\\n \\* Prints numbers from 1 to 100, but:\\\\n \\* - For multiples of 3, print \\\\\"Fizz\\\\\" instead of the number\\\\n \\* - For multiples of 5, print \\\\\"Buzz\\\\\" instead of the number\\\\n \\* - For multiples of both 3 and 5, print \\\\\"FizzBuzz\\\\\"\\\\n \\*/\\\\n\\\\nfunction fizzBuzz(n) {\\\\n for (let i = 1; i <= n; i++) {\\\\n let output = '';\\\\n \\\\n if (i % 3 === 0) output += 'Fizz';\\\\n if (i % 5 === 0) output += 'Buzz';\\\\n \\\\n console.log(output || i);\\\\n }\\\\n}\\\\n\\\\n// Execute FizzBuzz for numbers 1 to 100\\\\nconsole.log('Running FizzBuzz:');\\\\nfizzBuzz(100);\"}\n\nClaude: I've created a fizzbuzz.js file that you can run with Node.js. The program: 1. Defines a function called \\`fizzBuzz\\` that takes a parameter \\`n\\` for the upper limit 2. Loops from 1 to n (set to 100 in the execution) 3. For each number: - If it's divisible by 3, it adds \"Fizz\" to the output - If it's divisible by 5, it adds \"Buzz\" to the output - If it's divisible by both, it adds both resulting in \"FizzBuzz\" - If it's not divisible by either 3 or 5, it outputs the number itself 4. The script automatically executes the function for numbers 1 to 100 You can run this script using Node.js with the following command in your terminal: node fizzbuzz.js This will output the FizzBuzz sequence from 1 to 100 to your console.\n\nRight?! It’s impressive, isn’t it? And that’s the *most basic implemenation* of `edit_file` — of an agent in general — you can probably come up with.\n\nBut, did it work? Yes, it did:\n\n```text\n$ node fizzbuzz.js\nRunning FizzBuzz:\n1\n2\nFizz\n4\nBuzz\nFizz\n7\n8\nFizz\nBuzz\n11\nFizz\n13\n14\nFizzBuzz\n16\n[...]\n```\n\nAmazing. But hey, let’s have it actually *edit* a file and not just create one.\n\nHere’s what Claude does when I ask it to “Please edit the `fizzbuzz.js` so that it only prints until 15”:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: Please edit fizzbuzz.js so that it only prints until 15\n\nClaude: I'll edit the fizzbuzz.js file to print only until 15 instead of its current limit. First, let me check the current content of the file to understand what changes are needed.\n\ntool: read\\_file({\"path\":\"fizzbuzz.js\"})\n\nClaude: I can see that the file currently runs FizzBuzz up to 100. I'll modify it to only run up to 15 instead by changing the parameter in the fizzBuzz function call.\n\ntool: edit\\_file({\"path\":\"fizzbuzz.js\",\"old\\_str\":\"// Execute FizzBuzz for numbers 1 to 100\\\\nconsole.log('Running FizzBuzz:');\\\\nfizzBuzz(100);\",\"new\\_str\":\"// Execute FizzBuzz for numbers 1 to 15\\\\nconsole.log('Running FizzBuzz:');\\\\nfizzBuzz(15);\"})\n\nClaude: I also need to update the comment at the top of the file to reflect this change:\n\ntool: edit\\_file({\"path\":\"fizzbuzz.js\",\"old\\_str\":\"/\\*\\*\\\\n \\* FizzBuzz implementation in JavaScript\\\\n \\* Prints numbers from 1 to 100, but:\",\"new\\_str\":\"/\\*\\*\\\\n \\* FizzBuzz implementation in JavaScript\\\\n \\* Prints numbers from 1 to 15, but:\"})\n\nClaude: The changes have been successfully made to the fizzbuzz.js file. The program will now: 1. Only print FizzBuzz from 1 to 15 (instead of 1 to 100) 2. The documentation has been updated to reflect this change The function itself remains the same, as it takes a parameter to determine the upper limit, and we've simply changed that parameter from 100 to 15.\n\nIt reads the file, it edits the file to change the how long it runs, *and* then it also edits the file to update the comment at the top.\n\nAnd it still works:\n\n```text\n$ node fizzbuzz.js\nRunning FizzBuzz:\n1\n2\nFizz\n4\nBuzz\nFizz\n7\n8\nFizz\nBuzz\n11\nFizz\n13\n14\nFizzBuzz\n```\n\nOkay, let’s do one more and ask it to do the following:\n\n> Create a congrats.js script that rot13-decodes the following string ‘Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!’ and prints it\n\nMaybe a tall order. Let’s see:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: Create a congrats.js script that rot13-decodes the following string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!' and prints it\n\nClaude: I'll create a congrats.js script that decodes the ROT13-encoded string and prints it. ROT13 is a simple letter substitution cipher that replaces a letter with the 13th letter after it in the alphabet. Let me create this file for you:\n\ntool: edit\\_file({\"path\":\"congrats.js\",\"old\\_str\":\"\",\"new\\_str\":\"/\\*\\*\\\\n \\* A script to decode a ROT13-encoded string and print the result\\\\n \\*/\\\\n\\\\nfunction rot13Decode(encodedStr) {\\\\n return encodedStr.replace(/\\[a-zA-Z\\]/g, function(char) {\\\\n // Get the character code\\\\n const charCode = char.charCodeAt(0);\\\\n \\\\n // Handle uppercase letters\\\\n if (charCode >= 65 && charCode <= 90) {\\\\n return String.fromCharCode(((charCode - 65 + 13) % 26) + 65);\\\\n }\\\\n \\\\n // Handle lowercase letters\\\\n if (charCode >= 97 && charCode <= 122) {\\\\n return String.fromCharCode(((charCode - 97 + 13) % 26) + 97);\\\\n }\\\\n \\\\n // Return non-alphabetic characters as is\\\\n return char;\\\\n });\\\\n}\\\\n\\\\nconst encodedMessage = 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!';\\\\nconst decodedMessage = rot13Decode(encodedMessage);\\\\n\\\\nconsole.log(decodedMessage);\"})\n\nClaude: I've created a JavaScript file called congrats.js that: 1. Defines a \\`rot13Decode\\` function that takes an encoded string and applies the ROT13 cipher to decode it 2. Takes the provided string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!' 3. Decodes it using the function 4. Prints the decoded message to the console You can run this script using Node.js by typing \\`node congrats.js\\` in your terminal. The script will decode and display the hidden congratulatory message!\n\nDoes it work? Let’s try it:\n\n```text\n$ node congrats.js\nCongratulations on building a code-editing agent!\n```\n\nIt does!\n\n## Isn’t this amazing?\n\nIf you’re anything like all the engineers I’ve talked to in the past few months, chances are that, while reading this, you have been waiting for the rabbit to be pulled out of the hat, for me to say “well, in reality it’s much, much harder than this.” But it’s not.\n\nThis is essentially all there is to the inner loop of a code-editing agent. Sure, integrating it into your editor, tweaking the system prompt, giving it the right feedback at the right time, a nice UI around it, better tooling around the tools, support for multiple agents, and so on — we’ve built all of that in [Amp](https://ampcode.com/), but it didn’t require moments of genius. All that was required was practical engineering and elbow grease.\n\nThese models are incredibly powerful now. 300 lines of code and three tools and now you’re to be able to talk to an alien intelligence that edits your code. If you think “well, but we didn’t really…” — go and try it! Go and see how far you can get with this. I bet it’s a lot farther than you think.\n\n*That*’s why we think everything’s changing.\n", "authors": [], "captured_at": "2026-10-04T12:50:30.804479567+00:00", "category": "programming", "content_html": "

Thorsten Ball//April 15, 2025

\n

or: The Emperor Has No Clothes

\n

It’s not that hard to build a fully functioning, code-editing agent.

\n

It seems like it would be. When you look at an agent editing files, running commands, wriggling itself out of errors, retrying different strategies - it seems like there has to be a secret behind it.

\n

There isn’t. It’s an LLM, a loop, and enough tokens. It’s what we’ve been saying on the podcast from the start. The rest, the stuff that makes Amp so addictive and impressive? Elbow grease.

\n

But building a small and yet highly impressive agent doesn’t even require that. You can do it in less than 400 lines of code, most of which is boilerplate.

\n

I’m going to show you how, right now. We’re going to write some code together and go from zero lines of code to “oh wow, this is… a game changer.”

\n

I urge you to follow along. No, really. You might think you can just read this and that you don’t have to type out the code, but it’s less than 400 lines of code. I need you to feel how little code it is and I want you to see this with your own eyes in your own terminal in your own folders.

\n

Here’s what we need:

\n\n

Pencils out!

\n

Let’s dive right in and get ourselves a new Go project set up in four easy commands:

\n
mkdir code-editing-agent\ncd code-editing-agent\ngo mod init agent\ntouch main.go\n
\n

Now, let’s open main.go and, as a first step, put a skeleton of things we need in it:

\n
package main\n\nimport (\n\t"bufio"\n\t"context"\n\t"fmt"\n\t"os"\n\n\t"github.com/anthropics/anthropic-sdk-go"\n)\n\nfunc main() {\n\tclient := anthropic.NewClient()\n\n\tscanner := bufio.NewScanner(os.Stdin)\n\tgetUserMessage := func() (string, bool) {\n\t\tif !scanner.Scan() {\n\t\t\treturn "", false\n\t\t}\n\t\treturn scanner.Text(), true\n\t}\n\n\tagent := NewAgent(&client, getUserMessage)\n\terr := agent.Run(context.TODO())\n\tif err != nil {\n\t\tfmt.Printf("Error: %s\\n", err.Error())\n\t}\n}\n\nfunc NewAgent(client *anthropic.Client, getUserMessage func() (string, bool)) *Agent {\n\treturn &Agent{\n\t\tclient:         client,\n\t\tgetUserMessage: getUserMessage,\n\t}\n}\n\ntype Agent struct {\n\tclient         *anthropic.Client\n\tgetUserMessage func() (string, bool)\n}\n
\n

Yes, this doesn’t compile yet. But what we have here is an Agent that has access to an anthropic.Client (which, by default, looks for ANTHROPIC_API_KEY) and that can get a user message by reading from stdin on the terminal.

\n

Now let’s add the missing Run() method:

\n
// main.go\n\nfunc (a *Agent) Run(ctx context.Context) error {\n\tconversation := []anthropic.MessageParam{}\n\n\tfmt.Println("Chat with Claude (use 'ctrl-c' to quit)")\n\n\tfor {\n\t\tfmt.Print("\\\\u001b[94mYou\\\\u001b[0m: ")\n\t\tuserInput, ok := a.getUserMessage()\n\t\tif !ok {\n\t\t\tbreak\n\t\t}\n\n\t\tuserMessage := anthropic.NewUserMessage(anthropic.NewTextBlock(userInput))\n\t\tconversation = append(conversation, userMessage)\n\n\t\tmessage, err := a.runInference(ctx, conversation)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tconversation = append(conversation, message.ToParam())\n\n\t\tfor _, content := range message.Content {\n\t\t\tswitch content.Type {\n\t\t\tcase "text":\n\t\t\t\tfmt.Printf("\\\\u001b[93mClaude\\\\u001b[0m: %s\\n", content.Text)\n\t\t\t}\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc (a *Agent) runInference(ctx context.Context, conversation []anthropic.MessageParam) (*anthropic.Message, error) {\n\tmessage, err := a.client.Messages.New(ctx, anthropic.MessageNewParams{\n\t\tModel:     anthropic.ModelClaude3_7SonnetLatest,\n\t\tMaxTokens: int64(1024),\n\t\tMessages:  conversation,\n\t})\n\treturn message, err\n}\n
\n

It’s not a lot, is it? 90 lines and the most important thing in them is this loop in Run() that lets us talk to Claude. But that’s already the heartbeat of this program.

\n

And for a heartbeat, it’s pretty straightforward: we first print a prompt, ask the user to type something, add it to the conversation, send it to Claude, add Claude’s response to the conversation, print the response, and around we go.

\n

This is every AI chat application you’ve ever used, except it’s in the terminal.

\n

Let’s run it:

\n
export ANTHROPIC_API_KEY="this is the last time i will tell you to set this"\n\n# Download the dependencies\ngo mod tidy\n# Run it\ngo run main.go\n
\n

Then you can just talk to Claude, like this:

\n

$ go run main.go

\n

Chat with Claude (use 'ctrl-c' to quit)

\n

You: Hey! I'm Thorsten! How are you?

\n

Claude: Hi Thorsten! I'm doing well, thanks for asking. It's nice to meet you. How are you doing today? Is there something I can help you with?

\n

You: Can you come up with any horse-related nicknames that make fun of my first name?

\n

Claude: I can try to come up with some playful horse-related nicknames based on "Thorsten": * Thorough-bred Thorsten * Trotsten * Thorsten the Stallion * Neighsten * Horseten * Thorsten the Galloper * Saddle-sten * Thorsten of the Mane * Canter-sten * Thorsteed These are meant to be lighthearted - I hope they give you a chuckle!

\n

You:

\n

Notice how we kept the same conversation going over multiple turns. It remembers my name from the first message. The conversation grows longer with every turn and we send the whole conversation every time. The server — Anthropic’s server — is stateless. It only sees what’s in the conversation slice. It’s up to us to maintain that.

\n

Okay, let’s move on, because the nicknames suck and this is not an agent yet. What’s an agent? Here’s my definition: an LLM with access to tools, giving it the ability to modify something outside the context window.

\n

A First Tool

\n

An LLM with access to tools? What’s a tool? The basic idea is this: you send a prompt to the model that says it should reply in a certain way if it wants to use “a tool”. Then you, as the receiver of that message, “use the tool” by executing it and replying with the result. That’s it. Everything else we’ll see is just abstraction on top of it.

\n

Imagine you’re talking to a friend and you tell them: “in the following conversation, wink if you want me to raise my arm”. Weird thing to say, but an easy concept to grasp.

\n

We can already try it without changing any of our code.

\n

$ go run main.go

\n

Chat with Claude (use 'ctrl-c' to quit)

\n

You: You are a weather expert. When I ask you about the weather in a given location, I want you to reply with `get_weather(<location_name>)`. I will then tell you what the weather in that location is. Understood?

\n

Claude: I understand your instructions. When you ask me about the weather in a specific location, I will reply with `get_weather(<location_name>)`. Then you'll provide me with the weather information for that location, and I can discuss it further with you. I'm ready whenever you'd like to ask about the weather somewhere.

\n

You: Hey, what's the weather in Munich?

\n

Claude: get_weather(Munich)

\n

We told Claude to wink with get_weather when it wants to know about the weather. The next step is to raise our arm and reply with “result of the tool”:

\n

You: hot and humid, 28 degrees celcius

\n

Claude: Thank you for providing that information. The current weather in Munich is hot and humid at 28 degrees Celsius (about 82 degrees Fahrenheit). These are fairly warm conditions for Munich, especially with the added humidity which can make it feel even warmer than the temperature indicates. If you're in Munich or planning to visit, it would be good to stay hydrated, wear light clothing, and perhaps plan indoor activities during the hottest parts of the day. The combination of heat and humidity can be quite uncomfortable, particularly if you're not accustomed to such weather. Would you like to know about the weather in any other location?

\n

That worked very well, on first try, didn’t it?

\n

These models are trained and fine-tuned to use “tools” and they’re very eager to do so. By now, 2025, they kinda “know” that they don’t know everything and can use tools to get more information. (Of course that’s not precisely what’s going on, but it’s good enough an explanation for now.)

\n

To summarize, all there is to tools and tool use are two things:

\n
    \n
  1. You tell the model what tools are available
    2. \n
  2. When the model wants to execute the tool, it tells you, you execute the tool and send the response up
    3. \n
\n

To make (1) easier, the big model providers have built-in APIs to send tool definitions along.

\n

Okay, now let’s build our first tool: read_file

\n

The read_file tool

\n

In order to define the read_file tool, we’re going to use the types that the Anthropic SDK suggests, but keep in mind: under the hood, this will all end up as strings that are sent to the model. It’s all “wink if you want me to use read_file“.

\n

Each tool we’re going to add will require the following:

\n\n

So let’s add that to our code:

\n
// main.go\n\ntype ToolDefinition struct {\n\tName        string                         `json:"name"`\n\tDescription string                         `json:"description"`\n\tInputSchema anthropic.ToolInputSchemaParam `json:"input_schema"`\n\tFunction    func(input json.RawMessage) (string, error)\n}\n
\n

Now we give our Agent tool definitions:

\n
// main.go\n\n// `tools` is added here:\ntype Agent struct {\n\tclient         *anthropic.Client\n\tgetUserMessage func() (string, bool)\n\ttools          []ToolDefinition\n}\n\n// And here:\nfunc NewAgent(\n\tclient *anthropic.Client,\n\tgetUserMessage func() (string, bool),\n\ttools []ToolDefinition,\n) *Agent {\n\treturn &Agent{\n\t\tclient:         client,\n\t\tgetUserMessage: getUserMessage,\n\t\ttools:          tools,\n\t}\n}\n\n// And here:\nfunc main() {\n    // [... previous code ...]\n\ttools := []ToolDefinition{}\n\tagent := NewAgent(&client, getUserMessage, tools)\n\n    // [... previous code ...]\n}\n
\n

And send them along to the model in runInference:

\n
// main.go\n\nfunc (a *Agent) runInference(ctx context.Context, conversation []anthropic.MessageParam) (*anthropic.Message, error) {\n\tanthropicTools := []anthropic.ToolUnionParam{}\n\tfor _, tool := range a.tools {\n\t\tanthropicTools = append(anthropicTools, anthropic.ToolUnionParam{\n\t\t\tOfTool: &anthropic.ToolParam{\n\t\t\t\tName:        tool.Name,\n\t\t\t\tDescription: anthropic.String(tool.Description),\n\t\t\t\tInputSchema: tool.InputSchema,\n\t\t\t},\n\t\t})\n\t}\n\n\tmessage, err := a.client.Messages.New(ctx, anthropic.MessageNewParams{\n\t\tModel:     anthropic.ModelClaude3_7SonnetLatest,\n\t\tMaxTokens: int64(1024),\n\t\tMessages:  conversation,\n\t\tTools:     anthropicTools,\n\t})\n\treturn message, err\n}\n
\n

There’s a bunch of type shenanigans going on and I’m not too good in Go-with-generics yet so I’m not going to try to explain anthropic.String and ToolUnionParam to you. But, really, I swear, it’s very simple:

\n

We send along our tool definitions, on the server Anthropic then wraps these definitions in this system prompt (which isn’t much), which it adds to our conversation, and the model then replies in a specific way if it wants to use that tool.

\n

Alright, so tool definitions are being sent along, but we haven’t defined a tool yet. Let’s do that and define read_file:

\n
// main.go\n\nvar ReadFileDefinition = ToolDefinition{\n\tName:        "read_file",\n\tDescription: "Read the contents of a given relative file path. Use this when you want to see what's inside a file. Do not use this with directory names.",\n\tInputSchema: ReadFileInputSchema,\n\tFunction:    ReadFile,\n}\n\ntype ReadFileInput struct {\n\tPath string `json:"path" jsonschema_description:"The relative path of a file in the working directory."`\n}\n\nvar ReadFileInputSchema = GenerateSchema[ReadFileInput]()\n\nfunc ReadFile(input json.RawMessage) (string, error) {\n\treadFileInput := ReadFileInput{}\n\terr := json.Unmarshal(input, &readFileInput)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tcontent, err := os.ReadFile(readFileInput.Path)\n\tif err != nil {\n\t\treturn "", err\n\t}\n\treturn string(content), nil\n}\n\nfunc GenerateSchema[T any]() anthropic.ToolInputSchemaParam {\n\treflector := jsonschema.Reflector{\n\t\tAllowAdditionalProperties: false,\n\t\tDoNotReference:            true,\n\t}\n\tvar v T\n\n\tschema := reflector.Reflect(v)\n\n\treturn anthropic.ToolInputSchemaParam{\n\t\tProperties: schema.Properties,\n\t}\n}\n
\n

That’s not much, is it? It’s a single function, ReadFile, and two descriptions the model will see: our Description that describes the tool itself ("Read the contents of a given relative file path. ...") and a description of the single input parameter this tool has ("The relative path of a ...").

\n

The ReadFileInputSchema and GenerateSchema stuff? We need that so that we can generate a JSON schema for our tool definition which we send to the model. To do that, we use the jsonschema package, which we need to import and download:

\n
// main.go\n\npackage main\n\nimport (\n\t"bufio"\n\t"context"\n    // Add this:\n\t"encoding/json"\n\t"fmt"\n\t"os"\n\n\t"github.com/anthropics/anthropic-sdk-go"\n    // Add this:\n\t"github.com/invopop/jsonschema"\n)\n
\n

Then run the following:

\n
go mod tidy\n
\n

Then, in the main function, we need to make sure that we use the definition:

\n
func main() {\n    // [... previous code ...]\n\ttools := []ToolDefinition{ReadFileDefinition}\n    // [... previous code ...]\n}\n
\n

Time to try it!

\n

$ go run main.go

\n

Chat with Claude (use 'ctrl-c' to quit)

\n

You: what's in main.go?

\n

Claude: I'll help you check what's in the main.go file. Let me read it for you.

\n

You:

\n

Wait, what? Ho, ho, ho, it wants to use the tool! Obviously the output will be slightly different for you, but it certainly sounds like Claude knows that it can read files, right?

\n

The problem is that we don’t listen! When Claude winks, we ignore it. We need to fix that.

\n

Here, let me show you how to do that in a single, quick, surprisingly-agile-for-my-age move by replacing our Agent’s Run method with this:

\n
// main.go\n\nfunc (a *Agent) Run(ctx context.Context) error {\n\tconversation := []anthropic.MessageParam{}\n\n\tfmt.Println("Chat with Claude (use 'ctrl-c' to quit)")\n\n\treadUserInput := true\n\tfor {\n\t\tif readUserInput {\n\t\t\tfmt.Print("\\\\u001b[94mYou\\\\u001b[0m: ")\n\t\t\tuserInput, ok := a.getUserMessage()\n\t\t\tif !ok {\n\t\t\t\tbreak\n\t\t\t}\n\n\t\t\tuserMessage := anthropic.NewUserMessage(anthropic.NewTextBlock(userInput))\n\t\t\tconversation = append(conversation, userMessage)\n\t\t}\n\n\t\tmessage, err := a.runInference(ctx, conversation)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tconversation = append(conversation, message.ToParam())\n\n\t\ttoolResults := []anthropic.ContentBlockParamUnion{}\n\t\tfor _, content := range message.Content {\n\t\t\tswitch content.Type {\n\t\t\tcase "text":\n\t\t\t\tfmt.Printf("\\\\u001b[93mClaude\\\\u001b[0m: %s\\n", content.Text)\n\t\t\tcase "tool_use":\n\t\t\t\tresult := a.executeTool(content.ID, content.Name, content.Input)\n\t\t\t\ttoolResults = append(toolResults, result)\n\t\t\t}\n\t\t}\n\t\tif len(toolResults) == 0 {\n\t\t\treadUserInput = true\n\t\t\tcontinue\n\t\t}\n\t\treadUserInput = false\n\t\tconversation = append(conversation, anthropic.NewUserMessage(toolResults...))\n\t}\n\n\treturn nil\n}\n\nfunc (a *Agent) executeTool(id, name string, input json.RawMessage) anthropic.ContentBlockParamUnion {\n\tvar toolDef ToolDefinition\n\tvar found bool\n\tfor _, tool := range a.tools {\n\t\tif tool.Name == name {\n\t\t\ttoolDef = tool\n\t\t\tfound = true\n\t\t\tbreak\n\t\t}\n\t}\n\tif !found {\n\t\treturn anthropic.NewToolResultBlock(id, "tool not found", true)\n\t}\n\n\tfmt.Printf("\\\\u001b[92mtool\\\\u001b[0m: %s(%s)\\n", name, input)\n\tresponse, err := toolDef.Function(input)\n\tif err != nil {\n\t\treturn anthropic.NewToolResultBlock(id, err.Error(), true)\n\t}\n\treturn anthropic.NewToolResultBlock(id, response, false)\n}\n
\n

Squint and you’ll see that it’s 90% boilerplate and 10% that matter: when we get a message back from Claude, we check wether Claude asked us to execute a tool by looking for content.Type == "tool_use", if so we hand over to executeTool, lookup the tool by name in our local registry, unmarshal the input, execute it, return the result. If it’s an error, we flip a boolean. That’s it.

\n

(Yes, there is a loop in a loop, but it doesn’t matter.)

\n

We execute the tool, send the result back up to Claude, and ask again for Claude’s response. Truly: that’s it. Let me show you.

\n

Mise-en-place, run this:

\n
echo 'what animal is the most disagreeable because it always says neigh?' >> secret-file.txt\n
\n

That creates a secret-file.txt in our directory, containing a mysterious riddle.

\n

In that very same directory, let’s run our new tool-using agent, and ask it to look at the file:

\n

$ go run main.go

\n

Chat with Claude (use 'ctrl-c' to quit)

\n

You: Claude, buddy, help me solve the riddle in the secret-file.txt file

\n

Claude: I'll help you solve the riddle in the secret-file.txt file. Let me first read the contents of this file to see what the riddle is.

\n

tool: read_file({"path":"secret-file.txt"})

\n

Claude: Great! I've found the riddle. The answer to the riddle is: **A horse** The riddle is playing on wordplay where "neigh" (the sound a horse makes) sounds like "nay" (a way to say "no" or disagree with something). So horses are described as disagreeable because they always say "neigh/nay" - implying they're always disagreeing.

\n

You:

\n

Let’s take a deep breath and say it together. Ready? Here we go: holy shit. You just give it a tool and it… uses it when it thinks it’ll help solve the task. Remember: we didn’t say anything about “if a user asks you about a file, read the file”. We also didn’t say “if something looks like a filename, figure out how to read it”. No, none of that. We say “help me solve the thing in this file” and Claude realizes that it can read the file to answer that and off it goes.

\n

Of course, we can be specific and really nudge it towards a tool, but it basically does it all on its own:

\n

$ go run main.go

\n

Chat with Claude (use 'ctrl-c' to quit)

\n

You: What's going on in main.go? Be brief!

\n

Claude: I'll check the main.go file to see what's going on.

\n

tool: read_file({"path":"main.go"})

\n

Claude: Based on my review, main.go implements a Claude AI assistant agent that can use tools. Here's a brief summary: - It creates a command-line chat interface with Claude using the Anthropic Go SDK - Implements a tool system with a single "read_file" tool for reading file contents - Manages the conversation flow with Claude, handling both regular text responses and tool use requests - When Claude requests to use a tool, the agent executes it and returns the results - The program loops continuously to maintain a conversation until the user exits The code essentially builds a simple CLI-based chatbot that can interact with the file system when requested by Claude.

\n

You:

\n

Spot on. Okay, now that we know how to make Claude use tools, let’s add a few more.

\n

The list_files tool

\n

If you’re anything like me, the first thing you do when you log into a new computer is to get your bearings by running ls — list files.

\n

Let’s give Claude the same ability, a tool to list files. And here’s the complete implementation of a list_files tool:

\n
// main.go\n\nvar ListFilesDefinition = ToolDefinition{\n\tName:        "list_files",\n\tDescription: "List files and directories at a given path. If no path is provided, lists files in the current directory.",\n\tInputSchema: ListFilesInputSchema,\n\tFunction:    ListFiles,\n}\n\ntype ListFilesInput struct {\n\tPath string `json:"path,omitempty" jsonschema_description:"Optional relative path to list files from. Defaults to current directory if not provided."`\n}\n\nvar ListFilesInputSchema = GenerateSchema[ListFilesInput]()\n\nfunc ListFiles(input json.RawMessage) (string, error) {\n\tlistFilesInput := ListFilesInput{}\n\terr := json.Unmarshal(input, &listFilesInput)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tdir := "."\n\tif listFilesInput.Path != "" {\n\t\tdir = listFilesInput.Path\n\t}\n\n\tvar files []string\n\terr = filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\trelPath, err := filepath.Rel(dir, path)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tif relPath != "." {\n\t\t\tif info.IsDir() {\n\t\t\t\tfiles = append(files, relPath+"/")\n\t\t\t} else {\n\t\t\t\tfiles = append(files, relPath)\n\t\t\t}\n\t\t}\n\t\treturn nil\n\t})\n\n\tif err != nil {\n\t\treturn "", err\n\t}\n\n\tresult, err := json.Marshal(files)\n\tif err != nil {\n\t\treturn "", err\n\t}\n\n\treturn string(result), nil\n}\n
\n

Nothing fancy here: list_files returns the list of files and directories in the current folder. There’s a thousand optimizations we could (and probably should) make if this were a serious effort, but since I just want to show you what’s in the wizard’s hat, this is fine.

\n

One thing to note: we return a list of strings and we denote directories with a trailing slash. That’s not required, it’s just something I just decided to do. There’s no fixed format. Anything goes as long as Claude can make sense of it and whether it can you need to figure out by experimentation. You could also prepend each directory with "directory: " or return a Markdown document with two headers: "directories" and "files". There’s a ton of options and which one you chose depends on what Claude can make the most sense of, how many tokens it requires, how fast it is to generate and read, and so on.

\n

Here, we just want to create a small list_files tool and the easiest option wins.

\n

Of course we need to tell Claude about list_files too:

\n
// main.go\n\nfunc main() {\n\t// [... previous code ...]\n\n\ttools := []ToolDefinition{ReadFileDefinition, ListFilesDefinition}\n\n\t// [... previous code ...]\n}\n
\n

And that’s it. Let’s ask Claude what it can see in this directory.

\n

$ go run main.go

\n

Chat with Claude (use 'ctrl-c' to quit)

\n

You: what do you see in this directory?

\n

Claude: I'll help you see what's in the current directory. Let me list the files and directories for you.

\n

tool: list_files({})

\n

Claude: I can see several files and directories in the current directory: 1. Git-related files and directories: - `.git/` directory with various Git configuration and tracking files - `.gitignore` file 2. Go project files: - `main.go` - the main Go source code file - `go.mod` - Go module definition file - `go.sum` - Go module checksum file 3. Documentation: - `blogpost.md` - a markdown file, likely containing blog content 4. Environment configuration: - `.envrc` - likely an environment configuration file Would you like me to examine the contents of any specific file from this list?

\n

You:

\n

Works! It can read the directory.

\n

But here’s the thing: Claude knows how to combine these tools. We just need to prompt it in a way that provokes it:

\n

$ go run main.go

\n

Chat with Claude (use 'ctrl-c' to quit)

\n

You: Tell me about all the Go files in here. Be brief!

\n

Claude: I'll examine the Go files in the current directory for you. Let me check what files are available first.

\n

tool: list_files({})

\n

Claude: I found a Go file in the current directory. Let me examine it:

\n

tool: read_file({"path":"main.go"})

\n

tool: read_file({"path":"go.mod"})

\n

Claude: Here's a brief overview of the Go files in this project: **main.go**: - Implements a Claude AI agent that can interact with the local filesystem - Uses the Anthropic SDK for Go to communicate with Claude AI models - Provides two tools: `read_file` and `list_files` that allow Claude to read file contents and list directory contents - Manages a conversation flow between the user and Claude, handling tool execution when Claude needs to access files **go.mod**: - Defines the module dependencies - Main dependencies are the Anthropic SDK for Go and a JSON schema library - Uses Go 1.24.1 This appears to be a simple terminal-based application that allows users to chat with Claude while giving the AI access to read local files and list directories.

\n

You:

\n

First it used the list_files and then it called read_file twice with the Go-related files that I asked it about.

\n

Just… just like we would, right? I mean, here, what would you do if I ask you what version of Go we use in this project? Here’s what Claude does for me:

\n

$ go run main.go

\n

Chat with Claude (use 'ctrl-c' to quit)

\n

You: What go version are we using in this project?

\n

Claude: I'll help you find the Go version being used in this project. Let me check the files to locate where the Go version might be specified.

\n

tool: list_files({})

\n

Claude: I can see there's a Go project here with several important files like `go.mod`, `go.sum`, and `main.go`. Let me check the `go.mod` file first, as it typically contains the Go version information.

\n

tool: read_file({"path":"go.mod"})

\n

Claude: According to the `go.mod` file, this project is using Go version 1.24.1.

\n

Claude looks at the directory, looks at go.mod, and has the answer.

\n

We’re at around 190 lines of code now. Let that sink in. Once you have, let’s add another tool.

\n

Let it edit_file

\n

The last tool we’re going to add is edit_file — a tool that lets Claude edit files.

\n

“Holy shit”, you’re thinking now, “this is where the rubber hits the road, this is where he pulls the rabbit out of the hat.” Well, let’s see, shall we?

\n

First, let’s add a definition for our new edit_file tool:

\n
// main.go\n\nvar EditFileDefinition = ToolDefinition{\n\tName: "edit_file",\n\tDescription: `Make edits to a text file.\n\nReplaces 'old_str' with 'new_str' in the given file. 'old_str' and 'new_str' MUST be different from each other.\n\nIf the file specified with path doesn't exist, it will be created.\n`,\n\tInputSchema: EditFileInputSchema,\n\tFunction:    EditFile,\n}\n\ntype EditFileInput struct {\n\tPath   string `json:"path" jsonschema_description:"The path to the file"`\n\tOldStr string `json:"old_str" jsonschema_description:"Text to search for - must match exactly and must only have one match exactly"`\n\tNewStr string `json:"new_str" jsonschema_description:"Text to replace old_str with"`\n}\n\nvar EditFileInputSchema = GenerateSchema[EditFileInput]()\n
\n

That’s right, I again know what you’re thinking: “string replacement to edit files?” Claude 3.7 loves replacing strings (experimentation is how you find out what they love or don’t), so we’re going to implement edit_file by telling Claude it can edit files by replacing existing text with new text.

\n

Now here’s the implementation of the EditFile function in Go:

\n
func EditFile(input json.RawMessage) (string, error) {\n\teditFileInput := EditFileInput{}\n\terr := json.Unmarshal(input, &editFileInput)\n\tif err != nil {\n\t\treturn "", err\n\t}\n\n\tif editFileInput.Path == "" || editFileInput.OldStr == editFileInput.NewStr {\n\t\treturn "", fmt.Errorf("invalid input parameters")\n\t}\n\n\tcontent, err := os.ReadFile(editFileInput.Path)\n\tif err != nil {\n\t\tif os.IsNotExist(err) && editFileInput.OldStr == "" {\n\t\t\treturn createNewFile(editFileInput.Path, editFileInput.NewStr)\n\t\t}\n\t\treturn "", err\n\t}\n\n\toldContent := string(content)\n\tnewContent := strings.Replace(oldContent, editFileInput.OldStr, editFileInput.NewStr, -1)\n\n\tif oldContent == newContent && editFileInput.OldStr != "" {\n\t\treturn "", fmt.Errorf("old_str not found in file")\n\t}\n\n\terr = os.WriteFile(editFileInput.Path, []byte(newContent), 0644)\n\tif err != nil {\n\t\treturn "", err\n\t}\n\n\treturn "OK", nil\n}\n
\n

It checks the input parameters, it reads the file (or creates it if it exists), and replaces the OldStr with NewStr. Then it writes the content back to disk and returns "OK".

\n

What’s missing still is createNewFile, which is just a tiny helper function that would be 70% shorter if this wasn’t Go:

\n
func createNewFile(filePath, content string) (string, error) {\n\tdir := path.Dir(filePath)\n\tif dir != "." {\n\t\terr := os.MkdirAll(dir, 0755)\n\t\tif err != nil {\n\t\t\treturn "", fmt.Errorf("failed to create directory: %w", err)\n\t\t}\n\t}\n\n\terr := os.WriteFile(filePath, []byte(content), 0644)\n\tif err != nil {\n\t\treturn "", fmt.Errorf("failed to create file: %w", err)\n\t}\n\n\treturn fmt.Sprintf("Successfully created file %s", filePath), nil\n}\n
\n

Last step: adding it to the list of tools that we send to Claude.

\n
// main.go\n\nfunc main() {\n\t// [... previous code ...]\n\n\ttools := []ToolDefinition{ReadFileDefinition, ListFilesDefinition, EditFileDefinition}\n\n\t// [... previous code ...]\n}\n
\n

And… we’re ready, but are you? Are you ready to let it rip?

\n

Thought so, let’s do this. Let’s tell Claude to create a new FizzBuzz function in JavaScript.

\n

$ go run main.go

\n

Chat with Claude (use 'ctrl-c' to quit)

\n

You: hey claude, create fizzbuzz.js that I can run with Nodejs and that has fizzbuzz in it and executes it

\n

Claude: I'll create a fizzbuzz.js file that you can run with Node.js. First, let me check if the file already exists:

\n

tool: list_files({})

\n

Claude: I don't see a fizzbuzz.js file, so I'll create one with a classic FizzBuzz implementation. This program will print numbers from 1 to 100, but for multiples of 3 it will print "Fizz", for multiples of 5 it will print "Buzz", and for numbers that are multiples of both 3 and 5 it will print "FizzBuzz".

\n

tool: edit_file({"path":"fizzbuzz.js","old_str":"","new_str":"/**\\n * FizzBuzz implementation in JavaScript\\n * Prints numbers from 1 to 100, but:\\n * - For multiples of 3, print \\"Fizz\\" instead of the number\\n * - For multiples of 5, print \\"Buzz\\" instead of the number\\n * - For multiples of both 3 and 5, print \\"FizzBuzz\\"\\n */\\n\\nfunction fizzBuzz(n) {\\n for (let i = 1; i <= n; i++) {\\n let output = '';\\n \\n if (i % 3 === 0) output += 'Fizz';\\n if (i % 5 === 0) output += 'Buzz';\\n \\n console.log(output || i);\\n }\\n}\\n\\n// Execute FizzBuzz for numbers 1 to 100\\nconsole.log('Running FizzBuzz:');\\nfizzBuzz(100);"}

\n

Claude: I've created a fizzbuzz.js file that you can run with Node.js. The program: 1. Defines a function called `fizzBuzz` that takes a parameter `n` for the upper limit 2. Loops from 1 to n (set to 100 in the execution) 3. For each number: - If it's divisible by 3, it adds "Fizz" to the output - If it's divisible by 5, it adds "Buzz" to the output - If it's divisible by both, it adds both resulting in "FizzBuzz" - If it's not divisible by either 3 or 5, it outputs the number itself 4. The script automatically executes the function for numbers 1 to 100 You can run this script using Node.js with the following command in your terminal: node fizzbuzz.js This will output the FizzBuzz sequence from 1 to 100 to your console.

\n

Right?! It’s impressive, isn’t it? And that’s the most basic implemenation of edit_file — of an agent in general — you can probably come up with.

\n

But, did it work? Yes, it did:

\n
$ node fizzbuzz.js\nRunning FizzBuzz:\n1\n2\nFizz\n4\nBuzz\nFizz\n7\n8\nFizz\nBuzz\n11\nFizz\n13\n14\nFizzBuzz\n16\n[...]\n
\n

Amazing. But hey, let’s have it actually edit a file and not just create one.

\n

Here’s what Claude does when I ask it to “Please edit the fizzbuzz.js so that it only prints until 15”:

\n

$ go run main.go

\n

Chat with Claude (use 'ctrl-c' to quit)

\n

You: Please edit fizzbuzz.js so that it only prints until 15

\n

Claude: I'll edit the fizzbuzz.js file to print only until 15 instead of its current limit. First, let me check the current content of the file to understand what changes are needed.

\n

tool: read_file({"path":"fizzbuzz.js"})

\n

Claude: I can see that the file currently runs FizzBuzz up to 100. I'll modify it to only run up to 15 instead by changing the parameter in the fizzBuzz function call.

\n

tool: edit_file({"path":"fizzbuzz.js","old_str":"// Execute FizzBuzz for numbers 1 to 100\\nconsole.log('Running FizzBuzz:');\\nfizzBuzz(100);","new_str":"// Execute FizzBuzz for numbers 1 to 15\\nconsole.log('Running FizzBuzz:');\\nfizzBuzz(15);"})

\n

Claude: I also need to update the comment at the top of the file to reflect this change:

\n

tool: edit_file({"path":"fizzbuzz.js","old_str":"/**\\n * FizzBuzz implementation in JavaScript\\n * Prints numbers from 1 to 100, but:","new_str":"/**\\n * FizzBuzz implementation in JavaScript\\n * Prints numbers from 1 to 15, but:"})

\n

Claude: The changes have been successfully made to the fizzbuzz.js file. The program will now: 1. Only print FizzBuzz from 1 to 15 (instead of 1 to 100) 2. The documentation has been updated to reflect this change The function itself remains the same, as it takes a parameter to determine the upper limit, and we've simply changed that parameter from 100 to 15.

\n

It reads the file, it edits the file to change the how long it runs, and then it also edits the file to update the comment at the top.

\n

And it still works:

\n
$ node fizzbuzz.js\nRunning FizzBuzz:\n1\n2\nFizz\n4\nBuzz\nFizz\n7\n8\nFizz\nBuzz\n11\nFizz\n13\n14\nFizzBuzz\n
\n

Okay, let’s do one more and ask it to do the following:

\n
\n

Create a congrats.js script that rot13-decodes the following string ‘Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!’ and prints it

\n
\n

Maybe a tall order. Let’s see:

\n

$ go run main.go

\n

Chat with Claude (use 'ctrl-c' to quit)

\n

You: Create a congrats.js script that rot13-decodes the following string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!' and prints it

\n

Claude: I'll create a congrats.js script that decodes the ROT13-encoded string and prints it. ROT13 is a simple letter substitution cipher that replaces a letter with the 13th letter after it in the alphabet. Let me create this file for you:

\n

tool: edit_file({"path":"congrats.js","old_str":"","new_str":"/**\\n * A script to decode a ROT13-encoded string and print the result\\n */\\n\\nfunction rot13Decode(encodedStr) {\\n return encodedStr.replace(/[a-zA-Z]/g, function(char) {\\n // Get the character code\\n const charCode = char.charCodeAt(0);\\n \\n // Handle uppercase letters\\n if (charCode >= 65 && charCode <= 90) {\\n return String.fromCharCode(((charCode - 65 + 13) % 26) + 65);\\n }\\n \\n // Handle lowercase letters\\n if (charCode >= 97 && charCode <= 122) {\\n return String.fromCharCode(((charCode - 97 + 13) % 26) + 97);\\n }\\n \\n // Return non-alphabetic characters as is\\n return char;\\n });\\n}\\n\\nconst encodedMessage = 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!';\\nconst decodedMessage = rot13Decode(encodedMessage);\\n\\nconsole.log(decodedMessage);"})

\n

Claude: I've created a JavaScript file called congrats.js that: 1. Defines a `rot13Decode` function that takes an encoded string and applies the ROT13 cipher to decode it 2. Takes the provided string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!' 3. Decodes it using the function 4. Prints the decoded message to the console You can run this script using Node.js by typing `node congrats.js` in your terminal. The script will decode and display the hidden congratulatory message!

\n

Does it work? Let’s try it:

\n
$ node congrats.js\nCongratulations on building a code-editing agent!\n
\n

It does!

\n

Isn’t this amazing?

\n

If you’re anything like all the engineers I’ve talked to in the past few months, chances are that, while reading this, you have been waiting for the rabbit to be pulled out of the hat, for me to say “well, in reality it’s much, much harder than this.” But it’s not.

\n

This is essentially all there is to the inner loop of a code-editing agent. Sure, integrating it into your editor, tweaking the system prompt, giving it the right feedback at the right time, a nice UI around it, better tooling around the tools, support for multiple agents, and so on — we’ve built all of that in Amp, but it didn’t require moments of genius. All that was required was practical engineering and elbow grease.

\n

These models are incredibly powerful now. 300 lines of code and three tools and now you’re to be able to talk to an alien intelligence that edits your code. If you think “well, but we didn’t really…” — go and try it! Go and see how far you can get with this. I bet it’s a lot farther than you think.

\n

That’s why we think everything’s changing.

\n", "content_markdown": "Thorsten Ball//April 15, 2025\n\nor: The Emperor Has No Clothes\n\nIt’s not that hard to build a fully functioning, code-editing agent.\n\nIt seems like it would be. When you look at an agent editing files, running commands, wriggling itself out of errors, retrying different strategies - it seems like there has to be a secret behind it.\n\nThere isn’t. It’s an LLM, a loop, and enough tokens. It’s what we’ve been saying on the [podcast](https://ampcode.com/podcast) from the start. The rest, the stuff that makes [Amp](https://ampcode.com/) so addictive and impressive? Elbow grease.\n\nBut building a small and yet highly impressive agent doesn’t even require that. You can do it in less than 400 lines of code, most of which is boilerplate.\n\nI’m going to show you how, right now. We’re going to write some code together and go from zero lines of code to “oh wow, this is… a game changer.”\n\nI *urge* you to follow along. No, really. You might think you can just read this and that you don’t have to type out the code, but it’s less than 400 lines of code. I need you to *feel* how little code it is and I want you to see this with your own eyes in your own terminal in your own folders.\n\nHere’s what we need:\n\n- [Go](https://go.dev/)\n- [Anthropic API key](https://console.anthropic.com/settings/keys) that you set as an environment variable, `ANTHROPIC_API_KEY`\n\n## Pencils out!\n\nLet’s dive right in and get ourselves a new Go project set up in four easy commands:\n\n```shell\nmkdir code-editing-agent\ncd code-editing-agent\ngo mod init agent\ntouch main.go\n```\n\nNow, let’s open `main.go` and, as a first step, put a skeleton of things we need in it:\n\n```go\npackage main\n\nimport (\n\t\"bufio\"\n\t\"context\"\n\t\"fmt\"\n\t\"os\"\n\n\t\"github.com/anthropics/anthropic-sdk-go\"\n)\n\nfunc main() {\n\tclient := anthropic.NewClient()\n\n\tscanner := bufio.NewScanner(os.Stdin)\n\tgetUserMessage := func() (string, bool) {\n\t\tif !scanner.Scan() {\n\t\t\treturn \"\", false\n\t\t}\n\t\treturn scanner.Text(), true\n\t}\n\n\tagent := NewAgent(&client, getUserMessage)\n\terr := agent.Run(context.TODO())\n\tif err != nil {\n\t\tfmt.Printf(\"Error: %s\\n\", err.Error())\n\t}\n}\n\nfunc NewAgent(client *anthropic.Client, getUserMessage func() (string, bool)) *Agent {\n\treturn &Agent{\n\t\tclient: client,\n\t\tgetUserMessage: getUserMessage,\n\t}\n}\n\ntype Agent struct {\n\tclient *anthropic.Client\n\tgetUserMessage func() (string, bool)\n}\n```\n\nYes, this doesn’t compile yet. But what we have here is an `Agent` that has access to an `anthropic.Client` (which, by default, looks for `ANTHROPIC_API_KEY`) and that can get a user message by reading from stdin on the terminal.\n\nNow let’s add the missing `Run()` method:\n\n```go\n// main.go\n\nfunc (a *Agent) Run(ctx context.Context) error {\n\tconversation := []anthropic.MessageParam{}\n\n\tfmt.Println(\"Chat with Claude (use 'ctrl-c' to quit)\")\n\n\tfor {\n\t\tfmt.Print(\"\\\\u001b[94mYou\\\\u001b[0m: \")\n\t\tuserInput, ok := a.getUserMessage()\n\t\tif !ok {\n\t\t\tbreak\n\t\t}\n\n\t\tuserMessage := anthropic.NewUserMessage(anthropic.NewTextBlock(userInput))\n\t\tconversation = append(conversation, userMessage)\n\n\t\tmessage, err := a.runInference(ctx, conversation)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tconversation = append(conversation, message.ToParam())\n\n\t\tfor _, content := range message.Content {\n\t\t\tswitch content.Type {\n\t\t\tcase \"text\":\n\t\t\t\tfmt.Printf(\"\\\\u001b[93mClaude\\\\u001b[0m: %s\\n\", content.Text)\n\t\t\t}\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc (a *Agent) runInference(ctx context.Context, conversation []anthropic.MessageParam) (*anthropic.Message, error) {\n\tmessage, err := a.client.Messages.New(ctx, anthropic.MessageNewParams{\n\t\tModel: anthropic.ModelClaude3_7SonnetLatest,\n\t\tMaxTokens: int64(1024),\n\t\tMessages: conversation,\n\t})\n\treturn message, err\n}\n```\n\nIt’s not a lot, is it? 90 lines and the most important thing in them is this loop in `Run()` that lets us talk to Claude. But that’s already the heartbeat of this program.\n\nAnd for a heartbeat, it’s pretty straightforward: we first print a prompt, ask the user to type something, add it to the conversation, send it to Claude, add Claude’s response to the conversation, print the response, and around we go.\n\nThis is every AI chat application you’ve ever used, except it’s in the terminal.\n\nLet’s run it:\n\n```shell\nexport ANTHROPIC_API_KEY=\"this is the last time i will tell you to set this\"\n\n# Download the dependencies\ngo mod tidy\n# Run it\ngo run main.go\n```\n\nThen you can just talk to Claude, like this:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: Hey! I'm Thorsten! How are you?\n\nClaude: Hi Thorsten! I'm doing well, thanks for asking. It's nice to meet you. How are you doing today? Is there something I can help you with?\n\nYou: Can you come up with any horse-related nicknames that make fun of my first name?\n\nClaude: I can try to come up with some playful horse-related nicknames based on \"Thorsten\": \\* Thorough-bred Thorsten \\* Trotsten \\* Thorsten the Stallion \\* Neighsten \\* Horseten \\* Thorsten the Galloper \\* Saddle-sten \\* Thorsten of the Mane \\* Canter-sten \\* Thorsteed These are meant to be lighthearted - I hope they give you a chuckle!\n\nYou:\n\nNotice how we kept the same conversation going over multiple turns. It remembers my name from the first message. The `conversation` grows longer with every turn and we send the whole conversation every time. The server — Anthropic’s server — is stateless. It only sees what’s in the `conversation` slice. It’s up to us to maintain that.\n\nOkay, let’s move on, because the nicknames suck and this is not an agent yet. What’s an agent? Here’s [my definition](https://youtu.be/J1-W9O3n7j8?t=72): an LLM with *access to tools*, giving it the ability to modify something outside the context window.\n\n## A First Tool\n\nAn LLM with *access to tools*? What’s a tool? The basic idea is this: you send a prompt to the model that says it should reply in a certain way if it wants to use “a tool”. Then you, as the receiver of that message, “use the tool” by executing it and replying with the result. That’s it. Everything else we’ll see is just abstraction on top of it.\n\nImagine you’re talking to a friend and you tell them: “in the following conversation, wink if you want me to raise my arm”. Weird thing to say, but an easy concept to grasp.\n\nWe can already try it without changing any of our code.\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: You are a weather expert. When I ask you about the weather in a given location, I want you to reply with \\`get\\_weather(\\)\\`. I will then tell you what the weather in that location is. Understood?\n\nClaude: I understand your instructions. When you ask me about the weather in a specific location, I will reply with \\`get\\_weather(\\)\\`. Then you'll provide me with the weather information for that location, and I can discuss it further with you. I'm ready whenever you'd like to ask about the weather somewhere.\n\nYou: Hey, what's the weather in Munich?\n\nClaude: get\\_weather(Munich)\n\nWe told Claude to wink with `get_weather` when it wants to know about the weather. The next step is to raise our arm and reply with “result of the tool”:\n\nYou: hot and humid, 28 degrees celcius\n\nClaude: Thank you for providing that information. The current weather in Munich is hot and humid at 28 degrees Celsius (about 82 degrees Fahrenheit). These are fairly warm conditions for Munich, especially with the added humidity which can make it feel even warmer than the temperature indicates. If you're in Munich or planning to visit, it would be good to stay hydrated, wear light clothing, and perhaps plan indoor activities during the hottest parts of the day. The combination of heat and humidity can be quite uncomfortable, particularly if you're not accustomed to such weather. Would you like to know about the weather in any other location?\n\nThat worked very well, on first try, didn’t it?\n\nThese models are trained and fine-tuned to use “tools” and they’re very eager to do so. By now, 2025, they kinda “know” that they don’t know everything and can use tools to get more information. (Of course that’s not precisely what’s going on, but it’s good enough an explanation for now.)\n\nTo summarize, all there is to tools and tool use are two things:\n\n1. You tell the model what tools are available\n2. When the model wants to execute the tool, it tells you, you execute the tool and send the response up\n\nTo make (1) easier, the big model providers have built-in APIs to send tool definitions along.\n\nOkay, now let’s build our first tool: `read_file`\n\n## The `read_file` tool\n\nIn order to define the `read_file` tool, we’re going to use the types that the Anthropic SDK suggests, but keep in mind: under the hood, this will all end up as strings that are sent to the model. It’s all “wink if you want me to use `read_file`“.\n\nEach tool we’re going to add will require the following:\n\n- A name\n- A description to tell the model what the tool does, when to use it, when to not use it, what it returns and so on\n- An input schema that describes, as a JSON schema, what inputs this tool expects and in which form\n- A function that actually executes the tool with the input the model sends to us and returns the result\n\nSo let’s add that to our code:\n\n```go\n// main.go\n\ntype ToolDefinition struct {\n\tName string `json:\"name\"`\n\tDescription string `json:\"description\"`\n\tInputSchema anthropic.ToolInputSchemaParam `json:\"input_schema\"`\n\tFunction func(input json.RawMessage) (string, error)\n}\n```\n\nNow we give our `Agent` tool definitions:\n\n```go\n// main.go\n\n// `tools` is added here:\ntype Agent struct {\n\tclient *anthropic.Client\n\tgetUserMessage func() (string, bool)\n\ttools []ToolDefinition\n}\n\n// And here:\nfunc NewAgent(\n\tclient *anthropic.Client,\n\tgetUserMessage func() (string, bool),\n\ttools []ToolDefinition,\n) *Agent {\n\treturn &Agent{\n\t\tclient: client,\n\t\tgetUserMessage: getUserMessage,\n\t\ttools: tools,\n\t}\n}\n\n// And here:\nfunc main() {\n // [... previous code ...]\n\ttools := []ToolDefinition{}\n\tagent := NewAgent(&client, getUserMessage, tools)\n\n // [... previous code ...]\n}\n```\n\nAnd send them along to the model in `runInference`:\n\n```go\n// main.go\n\nfunc (a *Agent) runInference(ctx context.Context, conversation []anthropic.MessageParam) (*anthropic.Message, error) {\n\tanthropicTools := []anthropic.ToolUnionParam{}\n\tfor _, tool := range a.tools {\n\t\tanthropicTools = append(anthropicTools, anthropic.ToolUnionParam{\n\t\t\tOfTool: &anthropic.ToolParam{\n\t\t\t\tName: tool.Name,\n\t\t\t\tDescription: anthropic.String(tool.Description),\n\t\t\t\tInputSchema: tool.InputSchema,\n\t\t\t},\n\t\t})\n\t}\n\n\tmessage, err := a.client.Messages.New(ctx, anthropic.MessageNewParams{\n\t\tModel: anthropic.ModelClaude3_7SonnetLatest,\n\t\tMaxTokens: int64(1024),\n\t\tMessages: conversation,\n\t\tTools: anthropicTools,\n\t})\n\treturn message, err\n}\n```\n\nThere’s a bunch of type shenanigans going on and I’m not too good in Go-with-generics yet so I’m not going to try to explain `anthropic.String` and `ToolUnionParam` to you. But, really, I swear, it’s very simple:\n\nWe send along our tool definitions, on the server Anthropic then wraps these definitions in [this system prompt](https://docs.anthropic.com/en/docs/build-with-claude/tool-use/overview#tool-use-system-prompt) (which isn’t much), which it adds to our `conversation`, and the model then replies in a specific way if it wants to use that tool.\n\nAlright, so tool definitions are being sent along, but we haven’t defined a tool yet. Let’s do that and define `read_file`:\n\n```go\n// main.go\n\nvar ReadFileDefinition = ToolDefinition{\n\tName: \"read_file\",\n\tDescription: \"Read the contents of a given relative file path. Use this when you want to see what's inside a file. Do not use this with directory names.\",\n\tInputSchema: ReadFileInputSchema,\n\tFunction: ReadFile,\n}\n\ntype ReadFileInput struct {\n\tPath string `json:\"path\" jsonschema_description:\"The relative path of a file in the working directory.\"`\n}\n\nvar ReadFileInputSchema = GenerateSchema[ReadFileInput]()\n\nfunc ReadFile(input json.RawMessage) (string, error) {\n\treadFileInput := ReadFileInput{}\n\terr := json.Unmarshal(input, &readFileInput)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tcontent, err := os.ReadFile(readFileInput.Path)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\treturn string(content), nil\n}\n\nfunc GenerateSchema[T any]() anthropic.ToolInputSchemaParam {\n\treflector := jsonschema.Reflector{\n\t\tAllowAdditionalProperties: false,\n\t\tDoNotReference: true,\n\t}\n\tvar v T\n\n\tschema := reflector.Reflect(v)\n\n\treturn anthropic.ToolInputSchemaParam{\n\t\tProperties: schema.Properties,\n\t}\n}\n```\n\nThat’s not much, is it? It’s a single function, `ReadFile`, and two descriptions the model will see: our `Description` that describes the tool itself (`\"Read the contents of a given relative file path. ...\"`) and a description of the single input parameter this tool has (`\"The relative path of a ...\"`).\n\nThe `ReadFileInputSchema` and `GenerateSchema` stuff? We need that so that we can generate a JSON schema for our tool definition which we send to the model. To do that, we use the `jsonschema` package, which we need to import and download:\n\n```go\n// main.go\n\npackage main\n\nimport (\n\t\"bufio\"\n\t\"context\"\n // Add this:\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"os\"\n\n\t\"github.com/anthropics/anthropic-sdk-go\"\n // Add this:\n\t\"github.com/invopop/jsonschema\"\n)\n```\n\nThen run the following:\n\n```text\ngo mod tidy\n```\n\nThen, in the `main` function, we need to make sure that we use the definition:\n\n```go\nfunc main() {\n // [... previous code ...]\n\ttools := []ToolDefinition{ReadFileDefinition}\n // [... previous code ...]\n}\n```\n\nTime to try it!\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: what's in main.go?\n\nClaude: I'll help you check what's in the main.go file. Let me read it for you.\n\nYou:\n\nWait, what? Ho, ho, ho, it wants to use the tool! Obviously the output will be slightly different for you, but it certainly sounds like Claude knows that it can read files, right?\n\nThe problem is that we don’t listen! When Claude winks, we ignore it. We need to fix that.\n\nHere, let me show you how to do that in a single, quick, surprisingly-agile-for-my-age move by replacing our `Agent`’s `Run` method with this:\n\n```go\n// main.go\n\nfunc (a *Agent) Run(ctx context.Context) error {\n\tconversation := []anthropic.MessageParam{}\n\n\tfmt.Println(\"Chat with Claude (use 'ctrl-c' to quit)\")\n\n\treadUserInput := true\n\tfor {\n\t\tif readUserInput {\n\t\t\tfmt.Print(\"\\\\u001b[94mYou\\\\u001b[0m: \")\n\t\t\tuserInput, ok := a.getUserMessage()\n\t\t\tif !ok {\n\t\t\t\tbreak\n\t\t\t}\n\n\t\t\tuserMessage := anthropic.NewUserMessage(anthropic.NewTextBlock(userInput))\n\t\t\tconversation = append(conversation, userMessage)\n\t\t}\n\n\t\tmessage, err := a.runInference(ctx, conversation)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tconversation = append(conversation, message.ToParam())\n\n\t\ttoolResults := []anthropic.ContentBlockParamUnion{}\n\t\tfor _, content := range message.Content {\n\t\t\tswitch content.Type {\n\t\t\tcase \"text\":\n\t\t\t\tfmt.Printf(\"\\\\u001b[93mClaude\\\\u001b[0m: %s\\n\", content.Text)\n\t\t\tcase \"tool_use\":\n\t\t\t\tresult := a.executeTool(content.ID, content.Name, content.Input)\n\t\t\t\ttoolResults = append(toolResults, result)\n\t\t\t}\n\t\t}\n\t\tif len(toolResults) == 0 {\n\t\t\treadUserInput = true\n\t\t\tcontinue\n\t\t}\n\t\treadUserInput = false\n\t\tconversation = append(conversation, anthropic.NewUserMessage(toolResults...))\n\t}\n\n\treturn nil\n}\n\nfunc (a *Agent) executeTool(id, name string, input json.RawMessage) anthropic.ContentBlockParamUnion {\n\tvar toolDef ToolDefinition\n\tvar found bool\n\tfor _, tool := range a.tools {\n\t\tif tool.Name == name {\n\t\t\ttoolDef = tool\n\t\t\tfound = true\n\t\t\tbreak\n\t\t}\n\t}\n\tif !found {\n\t\treturn anthropic.NewToolResultBlock(id, \"tool not found\", true)\n\t}\n\n\tfmt.Printf(\"\\\\u001b[92mtool\\\\u001b[0m: %s(%s)\\n\", name, input)\n\tresponse, err := toolDef.Function(input)\n\tif err != nil {\n\t\treturn anthropic.NewToolResultBlock(id, err.Error(), true)\n\t}\n\treturn anthropic.NewToolResultBlock(id, response, false)\n}\n```\n\nSquint and you’ll see that it’s 90% boilerplate and 10% that matter: when we get a `message` back from Claude, we check wether Claude asked us to execute a tool by looking for `content.Type == \"tool_use\"`, if so we hand over to `executeTool`, lookup the tool by name in our local registry, unmarshal the input, execute it, return the result. If it’s an error, we flip a boolean. That’s it.\n\n(Yes, there is a loop in a loop, but it doesn’t matter.)\n\nWe execute the tool, send the result back up to Claude, and ask again for Claude’s response. Truly: that’s *it*. Let me show you.\n\nMise-en-place, run this:\n\n```shell\necho 'what animal is the most disagreeable because it always says neigh?' >> secret-file.txt\n```\n\nThat creates a `secret-file.txt` in our directory, containing a mysterious riddle.\n\nIn that very same directory, let’s run our new tool-using agent, and ask it to look at the file:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: Claude, buddy, help me solve the riddle in the secret-file.txt file\n\nClaude: I'll help you solve the riddle in the secret-file.txt file. Let me first read the contents of this file to see what the riddle is.\n\ntool: read\\_file({\"path\":\"secret-file.txt\"})\n\nClaude: Great! I've found the riddle. The answer to the riddle is: \\*\\*A horse\\*\\* The riddle is playing on wordplay where \"neigh\" (the sound a horse makes) sounds like \"nay\" (a way to say \"no\" or disagree with something). So horses are described as disagreeable because they always say \"neigh/nay\" - implying they're always disagreeing.\n\nYou:\n\nLet’s take a deep breath and say it together. Ready? Here we go: *holy shit*. You just give it a tool and it… *uses it when it thinks it’ll help solve the task*. Remember: we didn’t say *anything* about “if a user asks you about a file, read the file”. We also didn’t say “if something looks like a filename, figure out how to read it”. No, none of that. We say “help me solve the thing in this file” and Claude realizes that it can read the file to answer that and off it goes.\n\nOf course, we *can* be specific and really nudge it towards a tool, but it basically does it all on its own:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: What's going on in main.go? Be brief!\n\nClaude: I'll check the main.go file to see what's going on.\n\ntool: read\\_file({\"path\":\"main.go\"})\n\nClaude: Based on my review, main.go implements a Claude AI assistant agent that can use tools. Here's a brief summary: - It creates a command-line chat interface with Claude using the Anthropic Go SDK - Implements a tool system with a single \"read\\_file\" tool for reading file contents - Manages the conversation flow with Claude, handling both regular text responses and tool use requests - When Claude requests to use a tool, the agent executes it and returns the results - The program loops continuously to maintain a conversation until the user exits The code essentially builds a simple CLI-based chatbot that can interact with the file system when requested by Claude.\n\nYou:\n\nSpot on. Okay, now that we know how to make Claude use tools, let’s add a few more.\n\n## The `list_files` tool\n\nIf you’re anything like me, the first thing you do when you log into a new computer is to get your bearings by running `ls` — list files.\n\nLet’s give Claude the same ability, a tool to list files. And here’s the complete implementation of a `list_files` tool:\n\n```go\n// main.go\n\nvar ListFilesDefinition = ToolDefinition{\n\tName: \"list_files\",\n\tDescription: \"List files and directories at a given path. If no path is provided, lists files in the current directory.\",\n\tInputSchema: ListFilesInputSchema,\n\tFunction: ListFiles,\n}\n\ntype ListFilesInput struct {\n\tPath string `json:\"path,omitempty\" jsonschema_description:\"Optional relative path to list files from. Defaults to current directory if not provided.\"`\n}\n\nvar ListFilesInputSchema = GenerateSchema[ListFilesInput]()\n\nfunc ListFiles(input json.RawMessage) (string, error) {\n\tlistFilesInput := ListFilesInput{}\n\terr := json.Unmarshal(input, &listFilesInput)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\n\tdir := \".\"\n\tif listFilesInput.Path != \"\" {\n\t\tdir = listFilesInput.Path\n\t}\n\n\tvar files []string\n\terr = filepath.Walk(dir, func(path string, info os.FileInfo, err error) error {\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\trelPath, err := filepath.Rel(dir, path)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\n\t\tif relPath != \".\" {\n\t\t\tif info.IsDir() {\n\t\t\t\tfiles = append(files, relPath+\"/\")\n\t\t\t} else {\n\t\t\t\tfiles = append(files, relPath)\n\t\t\t}\n\t\t}\n\t\treturn nil\n\t})\n\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\tresult, err := json.Marshal(files)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\treturn string(result), nil\n}\n```\n\nNothing fancy here: `list_files` returns the list of files and directories in the current folder. There’s a thousand optimizations we could (and probably should) make if this were a serious effort, but since I just want to show you what’s in the wizard’s hat, this is fine.\n\nOne thing to note: we return a list of strings and we denote directories with a trailing slash. That’s not required, it’s just something I just decided to do. There’s no fixed format. Anything goes as long as Claude can make sense of it and whether it can you need to figure out by experimentation. You could also prepend each directory with `\"directory: \"` or return a Markdown document with two headers: `\"directories\"` and `\"files\"`. There’s a ton of options and which one you chose depends on what Claude can make the most sense of, how many tokens it requires, how fast it is to generate and read, and so on.\n\nHere, we just want to create a small `list_files` tool and the easiest option wins.\n\nOf course we need to tell Claude about `list_files` too:\n\n```go\n// main.go\n\nfunc main() {\n\t// [... previous code ...]\n\n\ttools := []ToolDefinition{ReadFileDefinition, ListFilesDefinition}\n\n\t// [... previous code ...]\n}\n```\n\nAnd that’s it. Let’s ask Claude what it can see in this directory.\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: what do you see in this directory?\n\nClaude: I'll help you see what's in the current directory. Let me list the files and directories for you.\n\ntool: list\\_files({})\n\nClaude: I can see several files and directories in the current directory: 1. Git-related files and directories: - \\`.git/\\` directory with various Git configuration and tracking files - \\`.gitignore\\` file 2. Go project files: - \\`main.go\\` - the main Go source code file - \\`go.mod\\` - Go module definition file - \\`go.sum\\` - Go module checksum file 3. Documentation: - \\`blogpost.md\\` - a markdown file, likely containing blog content 4. Environment configuration: - \\`.envrc\\` - likely an environment configuration file Would you like me to examine the contents of any specific file from this list?\n\nYou:\n\nWorks! It can read the directory.\n\nBut here’s the thing: Claude knows how to combine these tools. We just need to prompt it in a way that provokes it:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: Tell me about all the Go files in here. Be brief!\n\nClaude: I'll examine the Go files in the current directory for you. Let me check what files are available first.\n\ntool: list\\_files({})\n\nClaude: I found a Go file in the current directory. Let me examine it:\n\ntool: read\\_file({\"path\":\"main.go\"})\n\ntool: read\\_file({\"path\":\"go.mod\"})\n\nClaude: Here's a brief overview of the Go files in this project: \\*\\*main.go\\*\\*: - Implements a Claude AI agent that can interact with the local filesystem - Uses the Anthropic SDK for Go to communicate with Claude AI models - Provides two tools: \\`read\\_file\\` and \\`list\\_files\\` that allow Claude to read file contents and list directory contents - Manages a conversation flow between the user and Claude, handling tool execution when Claude needs to access files \\*\\*go.mod\\*\\*: - Defines the module dependencies - Main dependencies are the Anthropic SDK for Go and a JSON schema library - Uses Go 1.24.1 This appears to be a simple terminal-based application that allows users to chat with Claude while giving the AI access to read local files and list directories.\n\nYou:\n\nFirst it used the `list_files` and then it called `read_file` twice with the Go-related files that I asked it about.\n\nJust… just like we would, right? I mean, here, what would you do if I ask you what version of Go we use in this project? Here’s what Claude does for me:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: What go version are we using in this project?\n\nClaude: I'll help you find the Go version being used in this project. Let me check the files to locate where the Go version might be specified.\n\ntool: list\\_files({})\n\nClaude: I can see there's a Go project here with several important files like \\`go.mod\\`, \\`go.sum\\`, and \\`main.go\\`. Let me check the \\`go.mod\\` file first, as it typically contains the Go version information.\n\ntool: read\\_file({\"path\":\"go.mod\"})\n\nClaude: According to the \\`go.mod\\` file, this project is using Go version 1.24.1.\n\nClaude looks at the directory, looks at `go.mod`, and has the answer.\n\nWe’re at around 190 lines of code now. Let that sink in. Once you have, let’s add another tool.\n\n## Let it `edit_file`\n\nThe last tool we’re going to add is `edit_file` — a tool that lets Claude edit files.\n\n“Holy shit”, you’re thinking now, “this is where the rubber hits the road, this is where he pulls the rabbit out of the hat.” Well, let’s see, shall we?\n\nFirst, let’s add a definition for our new `edit_file` tool:\n\n```go\n// main.go\n\nvar EditFileDefinition = ToolDefinition{\n\tName: \"edit_file\",\n\tDescription: `Make edits to a text file.\n\nReplaces 'old_str' with 'new_str' in the given file. 'old_str' and 'new_str' MUST be different from each other.\n\nIf the file specified with path doesn't exist, it will be created.\n`,\n\tInputSchema: EditFileInputSchema,\n\tFunction: EditFile,\n}\n\ntype EditFileInput struct {\n\tPath string `json:\"path\" jsonschema_description:\"The path to the file\"`\n\tOldStr string `json:\"old_str\" jsonschema_description:\"Text to search for - must match exactly and must only have one match exactly\"`\n\tNewStr string `json:\"new_str\" jsonschema_description:\"Text to replace old_str with\"`\n}\n\nvar EditFileInputSchema = GenerateSchema[EditFileInput]()\n```\n\nThat’s right, I again know what you’re thinking: “string replacement to edit files?” Claude 3.7 loves replacing strings (experimentation is how you find out what they love or don’t), so we’re going to implement `edit_file` by telling Claude it can edit files by replacing existing text with new text.\n\nNow here’s the implementation of the `EditFile` function in Go:\n\n```go\nfunc EditFile(input json.RawMessage) (string, error) {\n\teditFileInput := EditFileInput{}\n\terr := json.Unmarshal(input, &editFileInput)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\tif editFileInput.Path == \"\" || editFileInput.OldStr == editFileInput.NewStr {\n\t\treturn \"\", fmt.Errorf(\"invalid input parameters\")\n\t}\n\n\tcontent, err := os.ReadFile(editFileInput.Path)\n\tif err != nil {\n\t\tif os.IsNotExist(err) && editFileInput.OldStr == \"\" {\n\t\t\treturn createNewFile(editFileInput.Path, editFileInput.NewStr)\n\t\t}\n\t\treturn \"\", err\n\t}\n\n\toldContent := string(content)\n\tnewContent := strings.Replace(oldContent, editFileInput.OldStr, editFileInput.NewStr, -1)\n\n\tif oldContent == newContent && editFileInput.OldStr != \"\" {\n\t\treturn \"\", fmt.Errorf(\"old_str not found in file\")\n\t}\n\n\terr = os.WriteFile(editFileInput.Path, []byte(newContent), 0644)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\treturn \"OK\", nil\n}\n```\n\nIt checks the input parameters, it reads the file (or creates it if it exists), and replaces the `OldStr` with `NewStr`. Then it writes the content back to disk and returns `\"OK\"`.\n\nWhat’s missing still is `createNewFile`, which is just a tiny helper function that would be 70% shorter if this wasn’t Go:\n\n```go\nfunc createNewFile(filePath, content string) (string, error) {\n\tdir := path.Dir(filePath)\n\tif dir != \".\" {\n\t\terr := os.MkdirAll(dir, 0755)\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"failed to create directory: %w\", err)\n\t\t}\n\t}\n\n\terr := os.WriteFile(filePath, []byte(content), 0644)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"failed to create file: %w\", err)\n\t}\n\n\treturn fmt.Sprintf(\"Successfully created file %s\", filePath), nil\n}\n```\n\nLast step: adding it to the list of tools that we send to Claude.\n\n```go\n// main.go\n\nfunc main() {\n\t// [... previous code ...]\n\n\ttools := []ToolDefinition{ReadFileDefinition, ListFilesDefinition, EditFileDefinition}\n\n\t// [... previous code ...]\n}\n```\n\nAnd… we’re ready, but are *you*? Are you ready to let it rip?\n\nThought so, let’s do this. Let’s tell Claude to create a new FizzBuzz function in JavaScript.\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: hey claude, create fizzbuzz.js that I can run with Nodejs and that has fizzbuzz in it and executes it\n\nClaude: I'll create a fizzbuzz.js file that you can run with Node.js. First, let me check if the file already exists:\n\ntool: list\\_files({})\n\nClaude: I don't see a fizzbuzz.js file, so I'll create one with a classic FizzBuzz implementation. This program will print numbers from 1 to 100, but for multiples of 3 it will print \"Fizz\", for multiples of 5 it will print \"Buzz\", and for numbers that are multiples of both 3 and 5 it will print \"FizzBuzz\".\n\ntool: edit\\_file({\"path\":\"fizzbuzz.js\",\"old\\_str\":\"\",\"new\\_str\":\"/\\*\\*\\\\n \\* FizzBuzz implementation in JavaScript\\\\n \\* Prints numbers from 1 to 100, but:\\\\n \\* - For multiples of 3, print \\\\\"Fizz\\\\\" instead of the number\\\\n \\* - For multiples of 5, print \\\\\"Buzz\\\\\" instead of the number\\\\n \\* - For multiples of both 3 and 5, print \\\\\"FizzBuzz\\\\\"\\\\n \\*/\\\\n\\\\nfunction fizzBuzz(n) {\\\\n for (let i = 1; i <= n; i++) {\\\\n let output = '';\\\\n \\\\n if (i % 3 === 0) output += 'Fizz';\\\\n if (i % 5 === 0) output += 'Buzz';\\\\n \\\\n console.log(output || i);\\\\n }\\\\n}\\\\n\\\\n// Execute FizzBuzz for numbers 1 to 100\\\\nconsole.log('Running FizzBuzz:');\\\\nfizzBuzz(100);\"}\n\nClaude: I've created a fizzbuzz.js file that you can run with Node.js. The program: 1. Defines a function called \\`fizzBuzz\\` that takes a parameter \\`n\\` for the upper limit 2. Loops from 1 to n (set to 100 in the execution) 3. For each number: - If it's divisible by 3, it adds \"Fizz\" to the output - If it's divisible by 5, it adds \"Buzz\" to the output - If it's divisible by both, it adds both resulting in \"FizzBuzz\" - If it's not divisible by either 3 or 5, it outputs the number itself 4. The script automatically executes the function for numbers 1 to 100 You can run this script using Node.js with the following command in your terminal: node fizzbuzz.js This will output the FizzBuzz sequence from 1 to 100 to your console.\n\nRight?! It’s impressive, isn’t it? And that’s the *most basic implemenation* of `edit_file` — of an agent in general — you can probably come up with.\n\nBut, did it work? Yes, it did:\n\n```text\n$ node fizzbuzz.js\nRunning FizzBuzz:\n1\n2\nFizz\n4\nBuzz\nFizz\n7\n8\nFizz\nBuzz\n11\nFizz\n13\n14\nFizzBuzz\n16\n[...]\n```\n\nAmazing. But hey, let’s have it actually *edit* a file and not just create one.\n\nHere’s what Claude does when I ask it to “Please edit the `fizzbuzz.js` so that it only prints until 15”:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: Please edit fizzbuzz.js so that it only prints until 15\n\nClaude: I'll edit the fizzbuzz.js file to print only until 15 instead of its current limit. First, let me check the current content of the file to understand what changes are needed.\n\ntool: read\\_file({\"path\":\"fizzbuzz.js\"})\n\nClaude: I can see that the file currently runs FizzBuzz up to 100. I'll modify it to only run up to 15 instead by changing the parameter in the fizzBuzz function call.\n\ntool: edit\\_file({\"path\":\"fizzbuzz.js\",\"old\\_str\":\"// Execute FizzBuzz for numbers 1 to 100\\\\nconsole.log('Running FizzBuzz:');\\\\nfizzBuzz(100);\",\"new\\_str\":\"// Execute FizzBuzz for numbers 1 to 15\\\\nconsole.log('Running FizzBuzz:');\\\\nfizzBuzz(15);\"})\n\nClaude: I also need to update the comment at the top of the file to reflect this change:\n\ntool: edit\\_file({\"path\":\"fizzbuzz.js\",\"old\\_str\":\"/\\*\\*\\\\n \\* FizzBuzz implementation in JavaScript\\\\n \\* Prints numbers from 1 to 100, but:\",\"new\\_str\":\"/\\*\\*\\\\n \\* FizzBuzz implementation in JavaScript\\\\n \\* Prints numbers from 1 to 15, but:\"})\n\nClaude: The changes have been successfully made to the fizzbuzz.js file. The program will now: 1. Only print FizzBuzz from 1 to 15 (instead of 1 to 100) 2. The documentation has been updated to reflect this change The function itself remains the same, as it takes a parameter to determine the upper limit, and we've simply changed that parameter from 100 to 15.\n\nIt reads the file, it edits the file to change the how long it runs, *and* then it also edits the file to update the comment at the top.\n\nAnd it still works:\n\n```text\n$ node fizzbuzz.js\nRunning FizzBuzz:\n1\n2\nFizz\n4\nBuzz\nFizz\n7\n8\nFizz\nBuzz\n11\nFizz\n13\n14\nFizzBuzz\n```\n\nOkay, let’s do one more and ask it to do the following:\n\n> Create a congrats.js script that rot13-decodes the following string ‘Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!’ and prints it\n\nMaybe a tall order. Let’s see:\n\n$ go run main.go\n\nChat with Claude (use 'ctrl-c' to quit)\n\nYou: Create a congrats.js script that rot13-decodes the following string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!' and prints it\n\nClaude: I'll create a congrats.js script that decodes the ROT13-encoded string and prints it. ROT13 is a simple letter substitution cipher that replaces a letter with the 13th letter after it in the alphabet. Let me create this file for you:\n\ntool: edit\\_file({\"path\":\"congrats.js\",\"old\\_str\":\"\",\"new\\_str\":\"/\\*\\*\\\\n \\* A script to decode a ROT13-encoded string and print the result\\\\n \\*/\\\\n\\\\nfunction rot13Decode(encodedStr) {\\\\n return encodedStr.replace(/\\[a-zA-Z\\]/g, function(char) {\\\\n // Get the character code\\\\n const charCode = char.charCodeAt(0);\\\\n \\\\n // Handle uppercase letters\\\\n if (charCode >= 65 && charCode <= 90) {\\\\n return String.fromCharCode(((charCode - 65 + 13) % 26) + 65);\\\\n }\\\\n \\\\n // Handle lowercase letters\\\\n if (charCode >= 97 && charCode <= 122) {\\\\n return String.fromCharCode(((charCode - 97 + 13) % 26) + 97);\\\\n }\\\\n \\\\n // Return non-alphabetic characters as is\\\\n return char;\\\\n });\\\\n}\\\\n\\\\nconst encodedMessage = 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!';\\\\nconst decodedMessage = rot13Decode(encodedMessage);\\\\n\\\\nconsole.log(decodedMessage);\"})\n\nClaude: I've created a JavaScript file called congrats.js that: 1. Defines a \\`rot13Decode\\` function that takes an encoded string and applies the ROT13 cipher to decode it 2. Takes the provided string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!' 3. Decodes it using the function 4. Prints the decoded message to the console You can run this script using Node.js by typing \\`node congrats.js\\` in your terminal. The script will decode and display the hidden congratulatory message!\n\nDoes it work? Let’s try it:\n\n```text\n$ node congrats.js\nCongratulations on building a code-editing agent!\n```\n\nIt does!\n\n## Isn’t this amazing?\n\nIf you’re anything like all the engineers I’ve talked to in the past few months, chances are that, while reading this, you have been waiting for the rabbit to be pulled out of the hat, for me to say “well, in reality it’s much, much harder than this.” But it’s not.\n\nThis is essentially all there is to the inner loop of a code-editing agent. Sure, integrating it into your editor, tweaking the system prompt, giving it the right feedback at the right time, a nice UI around it, better tooling around the tools, support for multiple agents, and so on — we’ve built all of that in [Amp](https://ampcode.com/), but it didn’t require moments of genius. All that was required was practical engineering and elbow grease.\n\nThese models are incredibly powerful now. 300 lines of code and three tools and now you’re to be able to talk to an alien intelligence that edits your code. If you think “well, but we didn’t really…” — go and try it! Go and see how far you can get with this. I bet it’s a lot farther than you think.\n\n*That*’s why we think everything’s changing.\n", "dateCreated": "2026-10-04T12:50:30.804479567+00:00", "date_created": "2025-04-15T00:00:00+00:00", "date_modified": "2025-04-15T00:00:00+00:00", "date_published": "2025-04-15T00:00:00+00:00", "description": "It’s not that hard to build a fully functioning, code-editing agent.", "external_url": "https://ampcode.com/notes/how-to-build-an-agent", "git": { "commit": "ebb0941c5c06a2ab2377342d607535262a3e969e", "path": "items/ampcode-com/2025/04/2025-04-15-how-to-build-an-agent.md", "permalink": "https://github.com/aymericbeaumet/aggr-instance/blob/ebb0941c5c06a2ab2377342d607535262a3e969e/items/ampcode-com/2025/04/2025-04-15-how-to-build-an-agent.md" }, "id": "urn:aggr:item:43f6f4064a6e47c9349e862e6132e3632348d8e3", "isBasedOn": { "@id": "https://ampcode.com/notes/how-to-build-an-agent" }, "mainEntity": { "@id": "https://ampcode.com/notes/how-to-build-an-agent", "@type": "CreativeWork", "archivedAt": { "@id": "https://aggr.aymericbeaumet.com/items/ampcode-com/2025-04-15-how-to-build-an-agent/#webpage" }, "dateModified": "2025-04-15T00:00:00+00:00", "datePublished": "2025-04-15T00:00:00+00:00", "headline": "How to Build an Agent", "timeRequired": "PT24M", "url": "https://ampcode.com/notes/how-to-build-an-agent", "wordCount": 5377 }, "name": "Archived snapshot: How to Build an Agent", "preview": null, "reading_minutes": 24, "replicated_at": null, "source": "ampcode-com", "source_name": "Amp News", "summary": "It’s not that hard to build a fully functioning, code-editing agent.", "tags": [], "temporalCoverage": "2026-10-04T12:50:30.804479567+00:00", "title": "How to Build an Agent", "url": "https://aggr.aymericbeaumet.com/items/ampcode-com/2025-04-15-how-to-build-an-agent/", "word_count": 5377 }