An agent in this context is an LLM that can use tools to act beyond its context window. nanoagent is a minimal coding agent CLI written in Go. Its design is intentionally simple, which makes it easy to adapt or extend for your own use cases.
Although full featured agents can appear complex when they read files, run commands, recover from errors, or adjust their strategy, the fundamentals are straightforward. At its core you need an LLM, a loop, tool definitions, and enough context capacity. Even a small implementation can deliver practical results with less than 400 lines of code.
Install the following before running the project:
- Go 1.25.5 or later
- An Anthropic API key stored in environment variable,
ANTHROPIC_API_KEY - Or a Kimi API key with the endpoint URL stored in environment variables,
ANTHROPIC_API_KEYandANTHROPIC_BASE_URL
Clone the repository and enter the project folder:
git clone https://github.com/cedrickchee/nanoagent.git
cd nanoagentexport ANTHROPIC_BASE_URL=https://api.moonshot.ai/anthropic
export ANTHROPIC_API_KEY="YOUR_MOONSHOT_API_KEY"export ANTHROPIC_API_KEY="sk-ant-api-********************"Update the model reference in main.go to use a Claude model instead of kimi-k2-thinking.
MiniMax supports the Anthropic-compatible API. Models include MiniMax M2 and MiniMax M2 Stable.
export ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic
export ANTHROPIC_API_KEY=${YOUR_API_KEY}Compile and start the program:
go build
./nanoagentYou can chat with the model, call tools through natural interaction, and observe how it chooses to use them when helpful.
Chat with Kimi (use 'ctrl-c' to quit)
You: Hello. Who is your creator?
Kimi: I am an AI assistant developed by Moonshot AI, specifically part of the K2 series built on a Mixture-of-Experts (MoE) architecture. While I don't have personal experiences or a creator in the way humans do, my existence is the result of a team of researchers and engineers at Moonshot AI developing and training large language models.
The specific training process involved extensive computational resources and data, guided by machine learning principles. So, while an individual "creator" isn't applicable, Moonshot AI is the organization responsible for my development. I don't have personal information about the team members, as the focus is on my capabilities as a tool.
Is there anything else I can help you with regarding my development or capabilities? I can provide more technical details about my architecture, such as the trillion-parameter scale, or discuss my features like the long context window and agentic capabilities.The project includes several example tools that demonstrate how an agent can inspect and modify its environment.
Allows the model to read file contents. Useful for answering questions about source code or other project files.
Chat with Kimi (use 'ctrl-c' to quit)
You: what's in main.go?
Kimi: I'll read the contents of main.go for you.
You:You just give it a tool and it uses it when it thinks it'll help solve the task.
Of course, we can be specific and really nudge it towards a tool, but it basically does it all on its own:
Expand
Chat with Kimi (use 'ctrl-c' to quit)
You: What's going on in main.go? Be brief!
Kimi: I'll take a quick look at the main.go file for you.
tool: read_file({"path":"main.go"})
Kimi: It's a simple CLI chatbot called "Kimi" that:
- Uses the Anthropics Claude SDK for chat
- Reads user input from stdin until Ctrl-C
- Currently has only one tool: `read_file` to read files relative to current directory
- Runs in a loop where it takes user input, calls the model, executes any tool calls from the model, and returns results to the model
- Color codes output: blue for "You", yellow for "Kimi", green for tool calls
It's a basic agent loop with function calling capability.Now that we know how to make Claude use tools, we added a few more.
Returns the directory contents.
The model can combine this with read_file to understand the structure of the project.
Let's ask Claude what it can see in this directory.
Chat with Kimi (use 'ctrl-c' to quit)
You: What do you see in this directory?
Kimi: I'll help you explore the current directory to see what's here.
tool: list_files({})
Kimi: I can see the directory contents. Here's what's in this directory:
**Key files:**
- `README.md` - Documentation file
- `go.mod` and `go.sum` - Go module files
- `main.go` - Main Go application file
- `secret-file.txt` - A text file (possibly contains sensitive data)
- `.backup/` - Backup directory containing:
- Backup versions of the Go files (go.mod, go.sum, main-ori.go, main.test.go)
**Directories:**
- `.git/` - Git version control metadata
- `docs/` - Directory with images:
- kimi-agent-explain-code.png
- kimi-tool-using-agent.png
- simple-claude-agent.png
This appears to be a Go project that might be related to AI agents, based on the asset image names. Would you like me to read any of the files to get more information about what this project does?
You:It can read the directory.
But here's the thing: Claude knows how to combine these tools. We just need to prompt it in a way that provokes it:
Expand
Chat with Kimi (use 'ctrl-c' to quit)
You: Tell me about all the Go files in here. Be brief!
Kimi: I'll help you find and summarize the Go files in the current directory.
tool: list_files({"path":"."})
Kimi: Let me check the current directory's Go files and the backup directory's Go files:
tool: read_file({"path":"go.mod"})
tool: read_file({"path":"main.go"})
tool: read_file({"path":".backup/main-ori.go"})
tool: read_file({"path":".backup/main.test.go"})
Kimi: ## Go Files Summary
**Root directory:**
- `go.mod`: Module "agent" with dependencies on Anthropic SDK and JSON schema library
- `go.sum`: Dependency checksums
- `main.go`: **Current working agent** - Interactive CLI chat with Kimi (kimi-k2-thinking model), uses ReadFile and ListFiles tools
- `.backup/go.mod`: Similar to root but with different SDK version
- `.backup/main-ori.go`: **Original Claude-based agent** (Claude Sonnet 4.5 model), includes EditFile tool with advanced features
- `.backup/main.test.go`: Simple test/demo file - basic API call asking "What is a quaternion?"
**Key differences:**
- Current version uses Kimi model, lacks EditFile tool
- Original Claude version had EditFile capability for file modifications
- Backup versions have more features and better error handling
- Current `main.go` appears to be a simplified/reverted versionPerforms string replacement within files. This provides a simple way for the agent to create or update code.
Claude Sonnet 4.0 loves replacing strings (experimentation is how you find out what they love or don't), so we implemented edit_file by telling Claude it can edit files by replacing existing text with new text.
Let's tell Claude to create a new FizzBuzz function in JavaScript.
Chat with Kimi (use 'ctrl-c' to quit)
You: Create fizzbuzz.js that I can run with Nodejs and that has fizzbuzz in it and executes it.
Kimi: I'll create a fizzbuzz.js file for you that you can run with Node.js. Let me start by checking what files already exist in the current directory.
tool: list_files({})
Kimi: Now I'll create a fizzbuzz.js file with the fizzbuzz logic and make it executable with Node.js:
tool: edit_file({"path":"fizzbuzz.js","old_str":"","new_str":"#!/usr/bin/env node\n\n// FizzBuzz implementation in JavaScript\n// Prints numbers from 1 to 100, but:\n// - For multiples of 3, print \"Fizz\"\n// - For multiples of 5, print \"Buzz\"\n// - For multiples of both 3 and 5, print \"FizzBuzz\"\n\nfunction fizzBuzz() {\n console.log('FizzBuzz JavaScript Implementation');\n console.log('==================================');\n \n for (let i = 1; i \u003c= 100; i++) {\n let output = '';\n \n if (i % 3 === 0) {\n output += 'Fizz';\n }\n \n if (i % 5 === 0) {\n output += 'Buzz';\n }\n \n if (output === '') {\n output = i;\n }\n \n console.log(output);\n }\n}\n\n// Execute the function when the file is run directly\nif (require.main === module) {\n fizzBuzz();\n}\n\n// Export the function for potential module use\nmodule.exports = { fizzBuzz };"})
Kimi: Perfect! I've created a fizzbuzz.js file that you can run with Node.js. The file includes:
1. **Shebang line** (`#!/usr/bin/env node`) - makes it executable directly
2. **Complete FizzBuzz logic** - prints numbers 1-100 with Fizz/Buzz replacements
3. **Direct execution** - runs automatically when executed with Node.js
4. **Export functionality** - can be imported as a module if needed
To run it, you have several options:
1. **Directly with Node.js:**
node fizzbuzz.js
2. **Make executable and run directly:**
chmod +x fizzbuzz.js
./fizzbuzz.js
3. **Run interactively in Node.js:**
node
> const { fizzBuzz } = require('./fizzbuzz.js');
> fizzBuzz();
The script will output the classic FizzBuzz sequence from 1 to 100!It's impressive, isn't it? And that's the most basic implementation of edit_file of an agent in general you can probably come up with.
But, did it work? Yes, it did:
$ node fizzbuzz.js
FizzBuzz JavaScript Implementation
==================================
1
2
Fizz
4
Buzz
Fizz
7
8
Fizz
Buzz
11
Fizz
13
14
FizzBuzz
16
17
Fizz
19
Buzz
[...]Let's have it actually edit a file and not just create one.
Expand
Chat with Kimi (use 'ctrl-c' to quit)
You: Please edit fizzbuzz.js so that it only prints until 19
Kimi: I'll help you edit the fizzbuzz.js file to only print until 19. First, let me read the current file to see what needs to be changed.
tool: read_file({"path":"fizzbuzz.js"})
Kimi: Now I can see the current implementation. The file prints numbers from 1 to 100 (the loop condition `i <= 100`), but you want it to only print until 19. I'll change the loop condition to stop at 19.
tool: edit_file({"path":"fizzbuzz.js","old_str":" for (let i = 1; i \u003c= 100; i++) {","new_str":" for (let i = 1; i \u003c= 19; i++) {"})
Kimi: Perfect! I've edited the file to change the loop condition from `i <= 100` to `i <= 19`. Now the FizzBuzz implementation will only print numbers from 1 to 19 instead of 1 to 100.
The output will be:
1
2
Fizz
4
Buzz
Fizz
7
8
Fizz
Buzz
11
Fizz
13
14
FizzBuzz
16
17
Fizz
19
The function maintains the same FizzBuzz logic for multiples of 3, 5, and both, but now stops at 19 as requested.It reads the file, it edits the file to change the how long it runs.
And it still works:
$ node fizzbuzz.js
FizzBuzz JavaScript Implementation
==================================
1
2
Fizz
4
Buzz
Fizz
7
8
Fizz
Buzz
11
Fizz
13
14
FizzBuzz
16
17
Fizz
19Let's do one more and ask it to do the following:
Prompt: "Create a congrats.js script that rot13-decodes the following string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!' and prints it."
Chat with Kimi (use 'ctrl-c' to quit)
You: Create a congrats.js script that rot13-decodes the following string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!' and prints it
Kimi: I'll help you create a JavaScript script that rot13-decodes that string and prints it. Let me first decode the string to see what it should be, then create the script.
tool: read_file({"path":"congrats.js"})
Kimi: The congrats.js file doesn't exist yet. Let me create it with the rot13 decoding functionality:
tool: edit_file({"path":"congrats.js","old_str":"","new_str":"// ROT13 decoding function\nfunction rot13(str) {\n return str.replace(/[a-zA-Z]/g, function(char) {\n const start = char \u003c= 'Z' ? 'A'.charCodeAt(0) : 'a'.charCodeAt(0);\n return String.fromCharCode((char.charCodeAt(0) - start + 13) % 26 + start);\n });\n}\n\n// The encoded string\nconst encoded = 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!';\n\n// Decode and print\nconst decoded = rot13(encoded);\nconsole.log(decoded);"})
Kimi: I've created a `congrats.js` script that rot13-decodes the string 'Pbatenghyngvbaf ba ohvyqvat n pbqr-rqvgvat ntrag!' and prints the result.
The script includes:
1. A `rot13()` function that handles the ROT13 decryption
2. The encoded string stored in a variable
3. The decoded result printed to the console
When you run this script, it will print: "Congratulations on building a code-editing agent!"
You can run it with `node congrats.js` in your terminal.Does it work? Let's try it:
$ node congrats.js
Congratulations on building a code-editing agent!It does!
Checks network connectivity to a given host.
Try it out:
Expand
Chat with Kimi (use 'ctrl-c' to quit)
You: hey. who are you?
Kimi: Hello! I'm Lisa, your helpful assistant. How can I help you today?
You: what's 3.9 - 3.11
Kimi: 3.9 - 3.11 = -0.21
You: describe our connectivity to github
Kimi: I'll check our connectivity to GitHub by pinging it.
tool: ping({"host":"github.com"})
Kimi: Our connectivity to GitHub looks great! Here's what I see:
- **Target**: github.com (20.205.243.166)
- **Packets sent/received**: 5/5 with 0% packet loss
- **Response times**: Very consistent and fast
- Average latency: 13.4 ms
- Minimum: 10.5 ms
- Maximum: 16.2 ms
- Standard deviation: 2.1 ms
- **TTL**: 112 (indicates network path is healthy)
The connection is stable and responsive, so you should have no issues reaching GitHub repositories, pushing/pulling code, or accessing GitHub services.
You:Runs shell commands. The model can use this to compile code, check syntax, or perform basic system tasks.
Examples show how the agent uses these tools in sequence, evaluates its own actions, and corrects mistakes when needed.
Bash tool definition: bash.txt
Expand
Chat with Kimi (use 'ctrl-c' to quit)
You: Verify the code compiles correctly
Kimi: I'll verify that the code compiles correctly by checking the current directory structure and then attempting to compile the code.
tool: list_files({})
Kimi: I can see there are several files in the directory including Go files (`main.go`, `go.mod`, `go.sum`) and JavaScript files (`congrats.js`, `fizzbuzz.js`). Let me check if these are the main source files and attempt to compile them.
tool: read_file({"path":"main.go"})
tool: read_file({"path":"go.mod"})
Kimi: Now let me attempt to compile the Go code to verify it compiles correctly:
tool: bash({"command":"go build","description":"Compile Go code to check for errors"})
Kimi: Perfect! The code compiles correctly. The Go program has been successfully compiled without any errors. The executable would be created in the current directory (named `agent` based on the module name).
Let me also quickly verify the JavaScript files are syntactically correct by checking them:
tool: bash({"command":"node -c congrats.js \u0026\u0026 node -c fizzbuzz.js","description":"Check JavaScript syntax for all JS files"})
Kimi: Excellent! All the code compiles correctly:
✅ **Go code**: Successfully compiled with `go build` - no errors
✅ **JavaScript files**: Successfully checked with `node -c` - syntax is valid
The entire codebase is ready to run without any compilation errors.Test the bash tool by chaining commands:
Expand
Chat with Kimi (use 'ctrl-c' to quit)
You: Verify the Go code compiles successfully without any errors. Then remove the executable created.
Kimi: I'll help you verify the Go code compiles and then remove the executable. Let me start by checking if there's a `.go` file and a Makefile or compile instructions.
tool: list_files({})
Kimi: Now let me check for Go source files in the current directory:
tool: bash({"command":"find . -name \"*.go\" -not -path \"./.git/*\" -not -path \"./.backup/*\" 2\u003e/dev/null | head -20","description":"Find .go files in current directory"})
Kimi: Let me check the main.go file and other compile-related files:
tool: read_file({"path":"main.go"})
tool: read_file({"path":"go.mod"})
Kimi: Now let me compile the Go code and check for any errors:
tool: bash({"command":"go build -o agent","description":"Compile the Go program"})
Kimi: Good! The Go code compiled successfully without errors. Now let me check if the executable was created:
tool: bash({"command":"ls -la agent","description":"Check if executable file exists"})
Kimi: Perfect! The Go code compiled successfully. Now I'll remove the executable as requested:
tool: bash({"command":"rm agent","description":"Remove the agent executable"})
Kimi: Done! The Go code compiled successfully without any errors, and the executable has been removed as requested.
You: The project also demonstrates:
- Use of a system prompt to shape the assistant's behavior
- A more capable bash tool with improved error recovery
- Practical multi step tool use such as compiling code, verifying results, and cleaning up generated files
Try the more capable bash tool:
Expand
Chat with Kimi (use 'ctrl-c' to quit)
You: Verify the main.go compiles successfully
Kimi: I'll check if the main.go file compiles successfully by examining the file first and then attempting to compile it.
tool: list_files({"path":"."})
Kimi: I can see there's a `main.go` file in the current directory. Let me read it first to understand its content, then compile it to verify it compiles successfully.
tool: read_file({"path":"main.go"})
Kimi: Now let me compile the main.go file to verify it compiles successfully:
tool: bash({"command":"go build main.go","description":"Compile main.go to check for errors"})
Kimi: I found a compilation error in main.go. There's a typo on line 33 where `ReadFileDefinitio` should be `ReadFileDefinition`. Let me fix this:
tool: edit_file({"path":"main.go","old_str":"\ttools := []ToolDefinition{ReadFileDefinitio, ListFilesDefinition, EditFileDefinition, PingDefinition, BashDefinition}","new_str":"\ttools := []ToolDefinition{ReadFileDefinition, ListFilesDefinition, EditFileDefinition, PingDefinition, BashDefinition}"})
Kimi: Now let me check if the compilation is successful after fixing the typo:
tool: bash({"command":"go build main.go","description":"Compile main.go after fixing typo"})
Kimi: Perfect! The main.go file now compiles successfully. The only issue was a typo where `ReadFileDefinitio` was missing the final "n" - it should have been `ReadFileDefinition`.
The compilation completed without any errors, which means all the Go code is syntactically correct and all dependencies are properly resolved.
You: - How to build a coding agent: free workshop by Geoffrey Huntley, Aug 25, 2025
- How to Build an Agent by Thorsten Ball, Apr 15, 2025
- What I learned building an opinionated and minimal coding agent by Mario Zechner, Nov 20, 2025
- nanoGPT by Andrej Karpathy, Dec 29, 2022
- Build a Coding Agent from Scratch: The Complete Python Tutorial by Sid Bharath, Aug 14, 2025
- You Should Write An Agent by Thomas Ptacek, Nov 6, 2025
Expand License
Content created by Cedric Chee is provided under the following terms:
Licensed under CC BY NC ND. See the Creative Commons documentation for full details.
Released under the MIT license.
See the LICENSE file for the complete text.