Build Your Own Coding Agent in 21 Days

What Layers Make Up a Coding Agent: the REPL Skeleton, the Command System, and a Provider-Neutral Gateway Abstraction

First split a terminal Coding Agent into five layers, see which layer is yours and which belongs to the provider, then build a working conversational shell: a readline loop, a slash-command table, an OpenAI-compatible gateway provider, and an offline script — so it still runs with no balance left.

Streaming Output and Terminal Rendering: Hand-Writing an SSE Parser, Incremental Markdown, and an Interruptible Typewriter

Peel back the gateway's SSE byte stream one layer at a time: parse events, merge them into incremental events, then hand them to a renderer that prints character by character — and handle stream disconnects, cursor control, and user keypress interrupts, the three things real engineering gets wrong most often.

The Tool Protocol and the Read-Only Trio: Schema Design, Chunk Merging, and Result Truncation

Give the agent eyes to read code: write three read-only tools — read file, find file, search content — and nail down the tool schema, merging streamed tool-call chunks, and how to truncate an overly long result once and for all; the next eighteen days rely on it.

File Editing and Shell Execution: Exact-Match Replacement, Conflict Detection, and a Timeout-Killable Subprocess

Upgrade read access to write access: implement an edit tool based on exact-match replacement and a shell tool that runs commands, handle four real failure modes — stale content not matching, files changed externally, a command hanging, and output too large — then let the agent fix a failing test green for the first time.

Permissions and Approval: a Three-State Rule Set, Matching by Tool and Path, and the Boundaries of Auto Mode

Give the agent an approval gate: judge every tool call against a set of allow/ask/deny three-state rules, match rules by tool name and path pattern, remember approval decisions, and work out exactly when fully automatic mode is responsible to enable.

Error Handling and Self-Correction: Feeding Failures Back, Backoff Retries, Loop Detection, and Cancellation

Clean up six real failure categories in one pass: tool failure, invalid arguments, gateway rate limiting, command timeout, stream disconnection, and a model spinning in circles. One principle only — feed back any error the model can fix itself, surface to the user only what it can't — and the user can always press cancel.

Session Persistence and Recovery: an Append-Only Event Log, Resume and Forking, Week One Retrospective

Stop a conversation from vanishing with the process: use an append-only JSONL event log to record every message, tool call, and usage figure, replay the log to restore state after a restart, and fork a new session from any event — then look back at how these seven layers stacked up over week one.

Reference Injection: Parsing @ Files, Directories, URLs, and Images, and Accounting for What Got Injected

Don't make the agent scan the whole repo itself: implement @-reference syntax that parses files, directories, and web addresses into structured injected content, handle binary and oversized files, and print in the terminal exactly how many characters were injected and how much budget that used.

Project Instruction Files: Three-Tier Loading, Import Expansion, and the System Prompt's Merge Order

Make the agent know the house rules the moment it enters a repo: implement discovery and loading of user-level, project-level, and directory-level instruction files, support imports between files, define a deterministic merge order and conflict rule, and give the user one command that shows exactly how the final system prompt was assembled.

Task Lists and Self-Planning: the Todo Tool, Progress Rendering, and Early Detection of Spinning

Give long tasks a dashboard: implement a tool that lets the model maintain its own todo list, render that list live in the terminal, use it to keep the model to one thing at a time, and use changes in the list to catch the model spinning in circles at the earliest moment.

Cross-Session Memory: Explicit Memory, Automatic Memory, and Three Criteria for Retrieval Injection

Make the agent remember this repo's pitfalls: implement a file-based memory directory, distinguish memory a user writes explicitly from memory the model distills automatically, retrieve by keyword and path and inject only the relevant few entries, and work out exactly what should never be remembered.

Context Compression: How to Count Tokens, What to Compress and What to Keep, and How to Verify Nothing Was Lost

Context always fills up eventually: first calibrate a local token estimator against real usage, implement segment-summary compression, pin down which message categories must be kept verbatim, then verify that compression didn't lose key information, using a set of probes that ask about early facts.

Ask Before Acting: a Structured Question Tool, a Read-Only Exploration Mode, and Plan Approval

Make the agent spell things out before touching anything: implement a tool that lets the model ask structured clarifying questions, add an exploration mode that only allows read-only tools, then have it produce an approvable plan and switch back to a writable state to execute only after the user approves it.

Checkpoints and Rewind: File Snapshots, Conversation Rollback, and Why the Two Must Stay Independent

Make bad edits undoable: implement content-hash-based file snapshots, form two independent timelines with the session event log, support rolling back files only, the conversation only, or both together, and handle a repo that already had uncommitted changes — week two retrospective.

Wiring Up MCP: a Hand-Written JSON-RPC Client, Two Transports, and a Tool Namespace

Wire someone else's tools into your own agent: hand-write an MCP client without the official SDK, get both stdio and Streamable HTTP transports working, aggregate remote tools into the local tool list with a namespace, and route them through the same approval gate from day five.

Loading Skills: Scanning, Progressive Disclosure, and Trigger Judgment — Bringing Experience to the Table on Demand

Turn reusable experience into skill packs: implement a skill loader that reads only a summary at startup, reads the full body only when a trigger condition matches, and runs an attached script only when needed — and use real numbers to show exactly how much context this progressive disclosure saves.

Subagents and Parallelism: Independent Context, a Tool Allowlist, Worktree Isolation, and Result Aggregation

Split the work when one agent can't finish it alone: implement a subagent mechanism where each subagent has its own context and tool allowlist, edits files in its own git worktree without stepping on others, and aggregates results back into the main session in structured form — and work out which tasks shouldn't be parallelized.

Hooks and Background Tasks: Lifecycle Hooks, Deterministic Checks, and Notifications That Don't Interrupt the Conversation

Some things shouldn't be left to the model's judgment: implement lifecycle hooks that insert deterministic checks and formatting before and after tool execution, then implement background tasks so a long-running command doesn't block the conversation and notifies the REPL when it finishes.

Multimodal Input: Pasting Screenshots, Image Validation, and Fixing Code From a Screenshot

Give the agent eyes: wire images into the message structure, handle both paste and file sources, size and dimension floors, and how to degrade gracefully for a model that doesn't support images, then drive a real code change from one screenshot of a UI.

Evaluation and Cost: Designing a Benchmark Set, Computing Pass Rate, and Reading Token Usage and Cache Hits

Tuning an agent by gut feel only makes it worse: design a benchmark set of tasks that can be scored automatically, get out a pass rate, average turn count, and token usage, compute the cache hit rate, then use a before-and-after comparison of one prompt change to show why evaluation must come before optimization.

Packaging and Release: a Global Command, a Config Directory, Versioning and Updates — a Twenty-One-Day Retrospective

Turn it into a tool other people can use too: set up an executable entry point and packaging output, gather configuration scattered across environment variables into a config directory while keeping the override order, handle versioning and update prompts, write a README and demo, then look back at how these twenty-one layers grew into one tool.