// BUILD-YOUR-OWN CODING AGENT //
ProtoAgent

Build Your Own Coding Agent ​

ProtoAgent was built to understand how coding agents actually work, not just use them.

If you've used tools like Claude Code, Cursor, or Copilot, you have probably had that same moment: it reads files, runs commands, edits code, and somehow keeps the whole loop together. It feels a bit magical.

This tutorial is about removing that magic.

Every chapter includes complete, copy-pasteable code for every file at every stage. You can rebuild the entire project from scratch by following the parts in order.

How to use this tutorial ​

Each part has two jobs:

  • explain why that layer exists
  • give you the exact code to build it

Every chapter is cumulative. Start at Part 1 and move forward in order.

For each stage, you should end up with a folder that matches one of these snapshots, available in the GitHub repository:

  • protoagent-build-your-own-checkpoints/part-1
  • protoagent-build-your-own-checkpoints/part-2
  • protoagent-build-your-own-checkpoints/part-3
  • protoagent-build-your-own-checkpoints/part-4
  • protoagent-build-your-own-checkpoints/part-5
  • protoagent-build-your-own-checkpoints/part-6
  • protoagent-build-your-own-checkpoints/part-7
  • protoagent-build-your-own-checkpoints/part-8
  • protoagent-build-your-own-checkpoints/part-9
  • protoagent-build-your-own-checkpoints/part-10
  • protoagent-build-your-own-checkpoints/part-11
  • protoagent-build-your-own-checkpoints/part-12
  • protoagent-build-your-own-checkpoints/part-13

The snapshots are the verification path. If a part says you should match protoagent-build-your-own-checkpoints/part-6, that folder represents the completed result of following Parts 1 through 6 in order.

Before you start ​

You'll want:

  • Node.js 22+
  • npm
  • an API key for one of the supported providers (OpenAI, Anthropic, or Google)
  • basic TypeScript knowledge
  • a terminal you are comfortable working in

The parts ​

Foundation ​

  1. Scaffolding — Commander, Ink, and the basic CLI shell
  2. AI Integration — OpenAI SDK streaming and message flow
  3. Configuration Management — provider/model selection, persisted config, and API key resolution

Core runtime ​

  1. The Agentic Loop — the tool-use loop, streaming events, retries, and termination
  2. Core Tools: Files, TODOs, and Web Fetching — path validation, approval system, file tools, TODO tracking, and web fetching
  3. Shell Commands & Approvals — bash tool with three-tier security (hard-blocked, auto-approved, requires approval)
  4. System Prompt & Runtime Policy — dynamic system prompt with directory tree and tool descriptions
  5. Compaction & Cost Tracking — token estimation, cost display, and long-context compaction

Persistence and reuse ​

  1. Skills & AGENTS.md — SKILL.md and AGENTS.md discovery, validation, activation, and catalog generation
  2. Sessions — persisted conversations, TODO restore, and resume flows

Extensibility ​

  1. MCP Integration — runtime config, MCP client for stdio and HTTP servers, dynamic tool registration
  2. Sub-agents — isolated child agent execution for context-heavy tasks

UI and operations ​

  1. Polish, Rendering & Logging — components, formatted output, grouped tool rendering, slash commands, fuzzy edit matching, and the final App

Philosophy ​

ProtoAgent is intentionally small. It has persisted sessions, TODO state, web fetching, skills, MCP, sub-agents, compaction, and a rich terminal UI.

That is exactly why this tutorial exists. Once you understand the core loop and the runtime boundaries, the rest of the codebase stops feeling mysterious.

By the end, the tutorial should not just make the codebase feel understandable. It should make it reproducible.

Built to teach how production-style coding agents actually work.