{"id":30702983,"url":"https://github.com/ghuntley/how-to-build-a-coding-agent","last_synced_at":"2025-09-02T16:03:34.763Z","repository":{"id":307169447,"uuid":"1025300166","full_name":"ghuntley/how-to-build-a-coding-agent","owner":"ghuntley","description":"A workshop that teaches you how to build your own coding agent. Similar to Roo code, Cline, Amp, Cursor, Windsurf or OpenCode.","archived":false,"fork":false,"pushed_at":"2025-08-24T03:14:15.000Z","size":31,"stargazers_count":118,"open_issues_count":2,"forks_count":32,"subscribers_count":3,"default_branch":"trunk","last_synced_at":"2025-08-24T11:13:17.016Z","etag":null,"topics":["agent","ai","cursor","tutorial","workshop"],"latest_commit_sha":null,"homepage":"https://ghuntley.com/agent/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ghuntley.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"ghuntley"}},"created_at":"2025-07-24T03:56:29.000Z","updated_at":"2025-08-24T11:09:51.000Z","dependencies_parsed_at":"2025-08-24T11:13:32.828Z","dependency_job_id":"381c2e4a-b8dd-4740-a676-099ace41c10f","html_url":"https://github.com/ghuntley/how-to-build-a-coding-agent","commit_stats":null,"previous_names":["ghuntley/how-to-build-an-agent","ghuntley/how-to-build-a-coding-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ghuntley/how-to-build-a-coding-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghuntley%2Fhow-to-build-a-coding-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghuntley%2Fhow-to-build-a-coding-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghuntley%2Fhow-to-build-a-coding-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghuntley%2Fhow-to-build-a-coding-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ghuntley","download_url":"https://codeload.github.com/ghuntley/how-to-build-a-coding-agent/tar.gz/refs/heads/trunk","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ghuntley%2Fhow-to-build-a-coding-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273309572,"owners_count":25082545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-02T02:00:09.530Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","cursor","tutorial","workshop"],"created_at":"2025-09-02T16:02:12.402Z","updated_at":"2025-09-02T16:03:34.753Z","avatar_url":"https://github.com/ghuntley.png","language":"Go","funding_links":["https://github.com/sponsors/ghuntley"],"categories":["Learning \u0026 Reference","Autonomous Research \u0026 Content Generation","A01_文本生成_文本对话","Go"],"sub_categories":["AI Assistants","大语言对话模型及数据"],"readme":"# 🧠 Build Your Own Coding Agent via a Step-by-Step Workshop\n\nWelcome! 👋 This workshop will guide you through building your own **AI-powered coding assistant** — starting from a basic chatbot, and adding powerful tools like file reading, shell command execution, and code searching.\n\nYou don’t need to be an AI expert. Just follow along and build step-by-step!\n\n🌐 **Want a detailed overview?** Check out the blog post: [ghuntley.com/agent](https://ghuntley.com/agent/)\n\n---\n\n## 🎯 What You'll Learn\n\nBy the end of this workshop, you’ll understand how to:\n\n- ✅ Connect to the Anthropic Claude API\n- ✅ Build a simple AI chatbot\n- ✅ Add tools like reading files, editing code, and running commands\n- ✅ Handle tool requests and errors\n- ✅ Build an agent that gets smarter with each step\n\n---\n\n## 🛠️ What We're Building\n\nYou’ll build 6 versions of a coding assistant. \n\nEach version adds more features:\n\n1. **Basic Chat** — talk to Claude\n2. **File Reader** — read code files\n3. **File Explorer** — list files in folders\n4. **Command Runner** — run shell commands\n5. **File Editor** — modify files\n6. **Code Search** — search your codebase with patterns\n\n```mermaid\ngraph LR\n    subgraph \"Application Progression\"\n        A[chat.go\u003cbr/\u003eBasic Chat] --\u003e B[read.go\u003cbr/\u003e+ File Reading]\n        B --\u003e C[list_files.go\u003cbr/\u003e+ Directory Listing]\n        C --\u003e D[bash_tool.go\u003cbr/\u003e+ Shell Commands]\n        D --\u003e E[edit_tool.go\u003cbr/\u003e+ File Editing]\n        E --\u003e F[code_search_tool.go\u003cbr/\u003e+ Code Search]\n    end\n    \n    subgraph \"Tool Capabilities\"\n        G[No Tools] --\u003e H[read_file]\n        H --\u003e I[read_file\u003cbr/\u003elist_files]\n        I --\u003e J[read_file\u003cbr/\u003elist_files\u003cbr/\u003ebash]\n        J --\u003e K[read_file\u003cbr/\u003elist_files\u003cbr/\u003ebash\u003cbr/\u003eedit_file]\n        K --\u003e L[read_file\u003cbr/\u003elist_files\u003cbr/\u003ebash\u003cbr/\u003ecode_search]\n    end\n    \n    A -.-\u003e G\n    B -.-\u003e H\n    C -.-\u003e I\n    D -.-\u003e J\n    E -.-\u003e K\n    F -.-\u003e L\n```\n\nAt the end, you’ll end up with a powerful local developer assistant!\n\n\n\n---\n\n## 🧱 How It Works (Architecture)\n\nEach agent works like this:\n\n1. Waits for your input\n2. Sends it to Claude\n3. Claude may respond directly or ask to use a tool\n4. The agent runs the tool (e.g., read a file)\n5. Sends the result back to Claude\n6. Claude gives you the final answer\n\nWe call this the **event loop** — it's like the agent's heartbeat.\n\n```mermaid\ngraph TB\n    subgraph \"Agent Architecture\"\n        A[Agent] --\u003e B[Anthropic Client]\n        A --\u003e C[Tool Registry]\n        A --\u003e D[getUserMessage Function]\n        A --\u003e E[Verbose Logging]\n    end\n    \n    subgraph \"Shared Event Loop\"\n        F[Start Chat Session] --\u003e G[Get User Input]\n        G --\u003e H{Empty Input?}\n        H --\u003e|Yes| G\n        H --\u003e|No| I[Add to Conversation]\n        I --\u003e J[runInference]\n        J --\u003e K[Claude Response]\n        K --\u003e L{Tool Use?}\n        L --\u003e|No| M[Display Text]\n        L --\u003e|Yes| N[Execute Tools]\n        N --\u003e O[Collect Results]\n        O --\u003e P[Send Results to Claude]\n        P --\u003e J\n        M --\u003e G\n    end\n    \n    subgraph \"Tool Execution Loop\"\n        N --\u003e Q[Find Tool by Name]\n        Q --\u003e R[Execute Tool Function]\n        R --\u003e S[Capture Result/Error]\n        S --\u003e T[Add to Tool Results]\n        T --\u003e U{More Tools?}\n        U --\u003e|Yes| Q\n        U --\u003e|No| O\n    end\n```\n\n## 🚀 Getting Started\n\n### ✅ Prerequisites\n\n* Go 1.24.2+ or [devenv](https://devenv.sh/) (recommended for easy setup)\n* An [Anthropic API Key](https://www.anthropic.com/product/claude)\n\n### 🔧 Set Up Your Environment\n\n**Option 1: Recommended (using devenv)**\n\n```bash\ndevenv shell  # Loads everything you need\n```\n\n**Option 2: Manual setup**\n\n```bash\n# Make sure Go is installed\ngo mod tidy\n```\n\n### 🔐 Add Your API Key\n\n```bash\nexport ANTHROPIC_API_KEY=\"your-api-key-here\"\n```\n\n---\n\n## 🏁 Start with the Basics\n\n### 1. `chat.go` — Basic Chat\n\nA simple chatbot that talks to Claude.\n\n```bash\ngo run chat.go\n```\n\n* ➡️ Try: “Hello!”\n* ➡️ Add `--verbose` to see detailed logs\n\n---\n\n## 🛠️ Add Tools (One Step at a Time)\n\n### 2. `read.go` — Read Files\n\nNow Claude can read files from your computer.\n\n```bash\ngo run read.go\n```\n\n* ➡️ Try: “Read fizzbuzz.js”\n\n---\n\n### 3. `list_files.go` — Explore Folders\n\nLets Claude look around your directory.\n\n```bash\ngo run list_files.go\n```\n\n* ➡️ Try: “List all files in this folder”\n* ➡️ Try: “What’s in fizzbuzz.js?”\n\n---\n\n### 4. `bash_tool.go` — Run Shell Commands\n\nAllows Claude to run safe terminal commands.\n\n```bash\ngo run bash_tool.go\n```\n\n* ➡️ Try: “Run git status”\n* ➡️ Try: “List all .go files using bash”\n\n---\n\n### 5. `edit_tool.go` — Edit Files\n\nClaude can now **modify code**, create files, and make changes.\n\n```bash\ngo run edit_tool.go\n```\n\n* ➡️ Try: “Create a Python hello world script”\n* ➡️ Try: “Add a comment to the top of fizzbuzz.js”\n\n---\n\n### 6. `code_search_tool.go` — Search Code\n\nUse pattern search (powered by [ripgrep](https://github.com/BurntSushi/ripgrep)).\n\n```bash\ngo run code_search_tool.go\n```\n\n* ➡️ Try: “Find all function definitions in Go files”\n* ➡️ Try: “Search for TODO comments”\n\n---\n\n## 🧪 Sample Files (Already Included)\n\n1. `fizzbuzz.js`: for file reading and editing\n1. `riddle.txt`: a fun text file to explore\n1. `AGENT.md`: info about the project environment\n\n---\n\n## 🐞 Troubleshooting\n\n**API key not working?**\n\n* Make sure it’s exported: `echo $ANTHROPIC_API_KEY`\n* Check your quota on [Anthropic’s dashboard](https://www.anthropic.com)\n\n**Go errors?**\n\n* Run `go mod tidy`\n* Make sure you’re using Go 1.24.2 or later\n\n**Tool errors?**\n\n* Use `--verbose` for full error logs\n* Check file paths and permissions\n\n**Environment issues?**\n\n* Use `devenv shell` to avoid config problems\n\n---\n\n## 💡 How Tools Work (Under the Hood)\n\nTools are like plugins. You define:\n\n* **Name** (e.g., `read_file`)\n* **Input Schema** (what info it needs)\n* **Function** (what it does)\n\nExample tool definition in Go:\n\n```go\nvar ToolDefinition = ToolDefinition{\n    Name:        \"read_file\",\n    Description: \"Reads the contents of a file\",\n    InputSchema: GenerateSchema[ReadFileInput](),\n    Function:    ReadFile,\n}\n```\n\nSchema generation uses Go structs — so it’s easy to define and reuse.\n\n---\n\n## 🧭 Workshop Path: Learn by Building\n\n| Phase | What to Focus On                                 |\n| ----- | ------------------------------------------------ |\n| **1** | `chat.go`: API integration and response handling |\n| **2** | `read.go`: Tool system, schema generation        |\n| **3** | `list_files.go`: Multiple tools, file system     |\n| **4** | `bash_tool.go`: Shell execution, error capture   |\n| **5** | `edit_tool.go`: File editing, safety checks      |\n| **6** | `code_search_tool.go`: Pattern search, ripgrep   |\n\n---\n\n## 🛠️ Developer Environment (Optional)\n\nIf you use [`devenv`](https://devenv.sh/), it gives you:\n\n* Go, Node, Python, Rust, .NET\n* Git and other dev tools\n\n```bash\ndevenv shell   # Load everything\ndevenv test    # Run checks\nhello          # Greeting script\n```\n\n---\n\n## 🚀 What's Next?\n\nOnce you complete the workshop, try building:\n\n* Custom tools (e.g., API caller, web scraper)\n* Tool chains (run tools in a sequence)\n* Memory features (remember things across sessions)\n* A web UI for your agent\n* Integration with other AI models\n\n---\n\n## 📦 Summary\n\nThis workshop helps you:\n\n* Understand agent architecture\n* Learn to build smart assistants\n* Grow capabilities step-by-step\n* Practice using Claude and Go together\n\n---\n\nHave fun exploring and building your own AI-powered tools! 💻✨\n\nIf you have questions or ideas, feel free to fork the repo, open issues, or connect with the community!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghuntley%2Fhow-to-build-a-coding-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fghuntley%2Fhow-to-build-a-coding-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fghuntley%2Fhow-to-build-a-coding-agent/lists"}