If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ghuntley/how-to-build-a-coding-agent shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Missing license — unclear to depend on

• Last commit 2d ago
• 3 active contributors
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 83% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ghuntley/how-to-build-a-coding-agent repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ghuntley/how-to-build-a-coding-agent.

What it runs against: a local clone of ghuntley/how-to-build-a-coding-agent — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ghuntley/how-to-build-a-coding-agent | Confirms the artifact applies here, not a fork | | 2 | Default branch trunk exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ghuntley/how-to-build-a-coding-agent. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ghuntley/how-to-build-a-coding-agent.git
#   cd how-to-build-a-coding-agent
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ghuntley/how-to-build-a-coding-agent and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ghuntley/how-to-build-a-coding-agent(\\.git)?\\b" \\
  && ok "origin remote is ghuntley/how-to-build-a-coding-agent" \\
  || miss "origin remote is not ghuntley/how-to-build-a-coding-agent (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify trunk >/dev/null 2>&1 \\
  && ok "default branch trunk exists" \\
  || miss "default branch trunk no longer exists"

# 4. Critical files exist
test -f "chat.go" \\
  && ok "chat.go" \\
  || miss "missing critical file: chat.go"
test -f "bash_tool.go" \\
  && ok "bash_tool.go" \\
  || miss "missing critical file: bash_tool.go"
test -f "edit_tool.go" \\
  && ok "edit_tool.go" \\
  || miss "missing critical file: edit_tool.go"
test -f "code_search_tool.go" \\
  && ok "code_search_tool.go" \\
  || miss "missing critical file: code_search_tool.go"
test -f "read.go" \\
  && ok "read.go" \\
  || miss "missing critical file: read.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ghuntley/how-to-build-a-coding-agent"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A step-by-step Go workshop that teaches how to build an AI-powered coding agent by progressively adding tool capabilities to Claude API interactions. It demonstrates the agentic loop pattern through 6 implementations: starting with basic chat, then adding file reading (read.go), directory listing (list_files.go), shell execution (bash_tool.go), file editing (edit_tool.go), and code search (code_search_tool.go)—similar to production agents like Cursor, Cline, or Roo Code. Sequential learning progression: core logic files (chat.go, read.go, list_files.go, bash_tool.go, edit_tool.go, code_search_tool.go) stack capabilities incrementally. Supporting files include prompts/ directory with markdown prompt templates for each stage (00-weather.md through 04-edit_tool.md), environment config via Nix (devenv.nix, .envrc), and build/task automation via Makefile. All 58KB of Go code lives at repo root.

Go developers and AI engineers who want to understand how coding assistants work under the hood, and need a concrete, educational implementation to learn the agentic event loop pattern without enterprise complexity.

Early-stage educational repository. It's a workshop/learning resource rather than production software, with clean pedagogical structure but limited evidence of CI/CD setup or automated testing in the file list. The Nix environment setup (devenv.nix, devenv.lock) and Makefile suggest deliberate tooling, but this is a teaching project, not a hardened library.

Low risk for educational use since it's intentionally a learning workshop. However, it has a single maintainer (ghuntley), depends on the Anthropic SDK (github.com/anthropics/anthropic-sdk-go v1.26.0) which could break, and requires an active Anthropic API key. No visible test suite in the file list means each step relies on manual verification.

No recent activity visible from the file list snapshot. The repository appears to be a stable, published workshop with completed implementation stages. Renovate configuration (renovate.json) suggests automated dependency updates are configured but the snapshots don't show pending PRs.

git clone https://github.com/ghuntley/how-to-build-a-coding-agent.git
cd how-to-build-a-coding-agent
eval "$(direnv hook bash)"  # activates .envrc
make                          # see Makefile for available targets

You'll need Go 1.24.2+ and an ANTHROPIC_API_KEY environment variable set.

Daily commands:

go run chat.go          # Basic chat (stage 1)
go run chat.go read.go  # With file reading (stage 2)
go run chat.go read.go list_files.go  # With directory listing (stage 3)
# ...continue adding more .go files per progression

Alternatively: make run (check Makefile for exact target).

• chat.go — Main entry point and orchestrator for the AI agent loop; handles Claude API calls and tool execution flow
• bash_tool.go — Implements shell command execution capability; critical for demonstrating tool integration and handling subprocess safety
• edit_tool.go — Implements file modification capability; shows how to handle structured tool requests from the LLM and validate file changes
• code_search_tool.go — Implements pattern-based code search; demonstrates advanced tool capability and file traversal patterns
• read.go — Implements file reading capability; foundational tool that shows basic file I/O and error handling patterns
• go.mod — Dependencies and Go version; Anthropic SDK is the core dependency enabling this agent framework
• README.md — Workshop guide and learning roadmap; documents the 6-step progression and intended learning outcomes

• chat.go (Agent Orchestrator) (Go, Anthropic SDK) — Manages the agentic loop: reads prompts, sends messages to Claude, dispatches tool calls, collects results, repeats until final response
  • Failure mode: API error, malformed response from Claude, or tool panic → agent halts with error message
• read.go (File Reader) (Go os/io packages) — Implements read_file tool: opens a file, reads contents, returns as string or error if file not found
  • Failure mode: Permission denied, file not found, or read error → returns error string to Claude
• bash_tool.go (Shell Executor) (Go os/exec package) — Executes arbitrary shell commands via os/exec; captures stdout, stderr, and exit code
  • Failure mode: Command not found, timeout, segfault → returns error output; unsafe against prompt injection
• edit_tool.go (File Editor) (Go file I/O, string manipulation) — Modifies files using line-based replace semantics; validates line ranges and prevents out-of-bounds edits
  • Failure mode: Invalid line range, read-only file, or invalid regex → returns error; file not modified
• code_search_tool.go (Code Search) (Go filepath, regexp packages) — Recursively searches directory tree for files matching regex pattern; returns matching lines with line numbers
  • Failure mode: Invalid regex or permission denied on subdirectory → returns error; partial results possible
• list_files.go (File Lister) — Lists files and directories in a given path; returns flat list with basic metadata (is_dir,

Add a New Tool

1. Create a new .go file for the tool (e.g., my_tool.go) with a handler function that returns JSON-serializable results (my_tool.go)
2. Define a struct with Name, Description, InputSchema fields compatible with Anthropic's tool protocol (my_tool.go)
3. Add the tool to the tools list in chat.go by appending it to the tools slice before the API call (chat.go)
4. Add a case statement in the tool execution logic in chat.go to call your tool handler when the tool name matches (chat.go)
5. Create a prompt file in prompts/NN-my_tool.md documenting the tool capability and example usage (prompts/05-my_tool.md)

Extend a Tool with New Functionality

1. Open the relevant tool file (e.g., edit_tool.go to add a new edit mode) (edit_tool.go)
2. Modify the input schema (the InputSchema field) to include new optional or required parameters (edit_tool.go)
3. Update the handler function to parse and act on the new parameters (edit_tool.go)
4. Update the tool description to reflect the new capability (edit_tool.go)

Change the Agent's Behavior via System Prompt

1. Identify which prompt file corresponds to the workshop step you are on (e.g., prompts/03-bash_tool.md) (prompts/03-bash_tool.md)
2. Edit the markdown file to modify the system prompt instructions for Claude (prompts/03-bash_tool.md)
3. In chat.go, update the call to read the new prompt file if using a different step (chat.go)
4. Re-run the agent to see how the new instructions change Claude's behavior (chat.go)

• Go 1.24.2 — Compiled, statically-typed language with minimal runtime overhead; ideal for building fast, composable CLI tools and agents
• Anthropic Claude SDK (v1.26.0) — Official, well-maintained SDK providing full access to Claude's API, including tool use / function calling for agentic workflows
• jsonschema (invopop) — Generates JSON Schema from Go structs; required to properly describe tool input schemas to Claude
• Nix (devenv) — Provides reproducible development environment; ensures all workshop participants have identical toolchains

• Sequential tool execution (no parallelization)

  • Why: Simplifies the workshop narrative and makes the agentic loop easy to understand
  • Consequence: Agent throughput is limited by slowest tool; real-world agents often execute tools in parallel

• No persistent conversation history

  • Why: Keeps the codebase minimal and focused on agent mechanics rather than session management
  • Consequence: Each conversation starts fresh; cannot leverage long-term context across sessions

• Bash tool has no sandboxing

  • Why: Demonstrates the tool interface clearly; production agents require containerization or safe-guard layers
  • Consequence: Unsafe for untrusted inputs; any prompt injection can lead to arbitrary code execution

• Prompt text embedded in markdown files

  • Why: Makes prompts easy to edit and iterate without recompiling; teaches prompt engineering as part of agent tuning
  • Consequence: No version control or A/B testing framework built-in; changes are not automatically tracked

• Production-grade safety/sandboxing for shell execution
• Multi-user session management or conversation persistence
• Real-time streaming or chunked responses
• Authentication or API key management beyond ANTHROPIC_API_KEY env var
• Web UI or REST API layer (CLI-only)
• Logging, telemetry, or observability instrumentation
• Advanced retrieval-augmented generation (RAG) or vector search

Must set ANTHROPIC_API_KEY environment variable before running any stage or chat.go will fail silently or error on first inference. The .envrc file expects direnv to be installed and activated. Tool execution (bash_tool.go) runs commands with inherited environment—be careful of secrets leakage. jsonschema auto-generation requires Go struct field tags (e.g., jsonschema:"required"); missing tags cause malformed tool schemas sent to Claude.

• Agentic Loop / Event Loop — The core pattern in chat.go that alternates between user input → Claude inference → tool execution → result feedback is the heartbeat of all modern coding assistants; understanding this loop is essential to grasping how agents work.
• Tool Use / Function Calling — Anthropic's tool_use response type (handled in chat.go message parsing) enables Claude to request tool execution; this is the mechanism that elevates a chatbot to an agent.
• JSON Schema Auto-Generation — The invopop/jsonschema library dynamically generates tool schemas from Go struct tags (e.g., in read.go's ReadFileInput); understanding this pattern avoids manual schema drift and makes tool definitions maintainable.
• Prompt Engineering / System Prompts — The prompts/ directory shows how task-specific system instructions guide Claude's behavior; stages 00-04 demonstrate iterative prompt refinement as capabilities expand, a critical skill for agents.
• Subprocess / Shell Command Execution — bash_tool.go uses os/exec to run arbitrary commands; understanding subprocess safety (input validation, environment isolation, error handling) is essential to building secure agents.
• Conversational State Management — The conversation history management in chat.go (building up []anthropic.MessageParam) ensures Claude maintains context across multiple tool invocations; this enables coherent multi-step tasks.
• Regex-Based Code Search — code_search_tool.go demonstrates pattern matching for semantic queries (finding function definitions, imports, etc.) without parsing ASTs; a practical middle ground for agent-driven code exploration.

• anthropics/anthropic-sdk-go — Official Anthropic Go SDK that this workshop wraps; essential for understanding the Messages API and tool_use response handling.
• aider-ai/aider — Production coding agent in Python; demonstrates the same agentic loop patterns at scale with additional features like git integration and model selection.
• continuedev/continue — IDE-native coding agent (VS Code, JetBrains) that extends the same tool-based architecture with editor integration and multi-model support.
• gpt-engineer-org/gpt-engineer — Project generation agent showing how agentic loops scale to multi-file code generation, useful reference for extending this workshop's capabilities.
• anthropics/anthropic-sdk-python — Python equivalent SDK; if learner prefers Python examples alongside Go, provides parallel implementation reference.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for tool execution pipeline (bash_tool.go, edit_tool.go, code_search_tool.go)

The repo has multiple tool implementations but no visible test files. New contributors should add integration tests that verify each tool (bash execution, file editing, code search) works correctly with the Claude API. This ensures the workshop's practical examples are reliable and helps contributors understand tool validation.

• [ ] Create bash_tool_test.go with tests for command execution safety and output capture
• [ ] Create edit_tool_test.go with tests for file modification scenarios (create, update, delete)
• [ ] Create code_search_tool_test.go with tests for search functionality and result formatting
• [ ] Add test fixtures in a testdata/ directory with sample files for testing read/edit/search operations
• [ ] Update Makefile with a 'test' target that runs go test ./...

Complete the README.md workshop progression documentation

The README snippet shows the workshop structure is incomplete (cuts off at 'File Explorer — lis'). The prompts/ directory shows 5 lessons (00-04) but the learning path isn't fully documented. Contributors should complete the README to show all 6 versions mentioned and what each step teaches.

• [ ] Expand README to describe all 6 versions (currently cuts off at version 3)
• [ ] Add a 'Getting Started' section with setup instructions (API key, environment variables from .envrc)
• [ ] Link each README section to corresponding prompts/ files (e.g., '2. File Reader' → prompts/01-read_file.md)
• [ ] Add a 'Running the Workshop' section explaining how to progress through each version
• [ ] Document what each prompt file teaches and which Go files correspond to each step

Add Go module documentation and examples for chat.go and read.go exported functions

The core agent logic lives in chat.go and read.go but these files lack documentation. New contributors should add godoc comments and example usage to help learners understand the API. This makes the code workshop-friendly and easier to reference.

• [ ] Add godoc comments to all exported functions in chat.go (following Go conventions)
• [ ] Add godoc comments to all exported functions in read.go
• [ ] Create examples_test.go demonstrating basic usage of the chat and file-reading API
• [ ] Verify godoc renders correctly by running 'go doc ./...' and checking output
• [ ] Update AGENT.md if it exists to reference the documented functions with code examples

• Add integration tests for each stage (test/chat_test.go, test/read_test.go, etc.) using mock Anthropic responses and file fixtures—currently no test files visible.
• Document the Anthropic API response structure and tool_use parsing logic with inline comments and a separate ARCHITECTURE.md explaining the event loop and message flow.
• Add a stage 7 example (e.g., multi-file refactoring or project analysis) that combines multiple tools, demonstrating advanced agentic patterns beyond the basic 6 stages.

This coding agent workshop demonstrates significant security risks inherent in its design. The primary concerns are unrestricted shell command execution (bash_tool.go), unrestricted file system access (edit_tool.go, read.go), and potential credential exposure in environment configuration files. While this is acceptable for educational purposes, production deployment would require robust sandboxing, strict input validation, path whitelisting, and comprehensive access controls. The codebase lacks security hardening measures and would require substantial modifications before being suitable for untrusted environments. Immediate attention should be given to implementing file system and command execution restrictions.

• High · Potential Hardcoded API Keys in .envrc — .envrc. The presence of .envrc file suggests environment variable management. If this file contains hardcoded Anthropic API keys or credentials, they could be exposed in version control history or accidentally committed to the repository. Fix: Ensure .envrc is properly listed in .gitignore and never contains hardcoded secrets. Use environment variable injection at runtime instead. Review git history to ensure no credentials were previously committed.
• High · Unrestricted Shell Command Execution — bash_tool.go. The presence of bash_tool.go suggests the agent can execute arbitrary bash commands. Without proper input validation and sandboxing, this could allow an attacker to execute malicious commands through crafted prompts or tool requests. Fix: Implement strict input validation, command whitelisting, and sandboxing. Consider using restricted shell environments or containers. Validate all user-provided inputs before passing to bash execution.
• High · Unrestricted File System Access — edit_tool.go, read.go, list_files.go. The edit_tool.go and read.go files suggest the agent can read and modify arbitrary files. Without proper path validation and access controls, this could lead to unauthorized file access or modification outside intended directories. Fix: Implement strict path validation and chroot/jail the file system access to a specific directory. Use allowlists for accessible paths. Validate all file operations against a sandbox boundary.
• Medium · Lack of Rate Limiting on API Calls — chat.go. The code uses Anthropic SDK without visible rate limiting mechanisms. Malicious users could attempt to exhaust API quotas or cause financial impact through excessive API calls. Fix: Implement rate limiting on API calls. Add request throttling, quota management, and monitoring for unusual activity patterns.
• Medium · Missing Input Validation Framework — code_search_tool.go, bash_tool.go. Code search functionality (code_search_tool.go) and file operations lack visible input validation patterns, which could expose the system to injection attacks or unexpected behavior. Fix: Implement comprehensive input validation for all user-controlled inputs. Sanitize search patterns, file paths, and command arguments. Use parameterized approaches where applicable.
• Medium · Dependency Vulnerabilities Exposure — go.mod, go.sum. The codebase depends on Anthropic SDK and JSON schema libraries. While versions are pinned, no automated dependency scanning or security update process is visible. Fix: Implement automated dependency scanning using tools like Dependabot or Snyk. Regularly update dependencies and monitor security advisories. Consider using SBOM (Software Bill of Materials).
• Low · Missing Security Documentation — Repository root. No security policy, vulnerability disclosure guidelines, or security.md file is present in the repository. Fix: Add a SECURITY.md file with vulnerability disclosure guidelines and contact information. Document security considerations in AGENT.md.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.