learn-agent

Learn Agent is a set of notes written while building a desktop AI agent called Reina, explaining how coding agent tools like Claude Code, Codex, and opencode actually work under the hood. Each chapter covers one mechanism and reduces the real production implementation from Reina into a small, dependency free, single file Node.js program you can run directly, so the ideas come from a working product rather than guesses based on API documentation alone.

To try it, you need Node 18 or newer and any OpenAI compatible API key, such as DeepSeek, Kimi, GLM, OpenRouter, or a local Ollama setup. Many of the demo scripts and the self test mode in the final chapter do not require a key at all.

The chapters are meant to be read roughly in order. The first twelve build up a complete, usable agent from scratch, covering the core agent loop, a growing tool system, budgets for loop steps and tool output, streaming output with interruption handling, compressing context without losing the original task, prompt caching to control cost, saving and resuming a session after a crash, running sub agents with a watchdog for stuck tasks, assembling the system prompt on demand, and coordinating multiple agents at once. The chapters after that cover edge cases found while building Reina in practice: permission checks before running risky commands, handling different providers whose tool call formats do not match, revealing tools gradually instead of dumping them all into context, whether letting multiple models deliberate together is worth it, letting an agent reflect on its own conversations to build memory and skills, deciding when an agent is truly allowed to say a task is done, resolving the conflict between context compression and prompt caching, and building long term memory that carries across projects without wasting money or accumulating clutter.

Each chapter's writeup ends by pointing to where the matching production code lives in the Reina repository. The project is released under the MIT License.