An agent you can actually read, built one lesson at a time

What it does

NamiAgent is a Chinese-language tutorial that doubles as a working local agent. It starts with a minimal loop — call the model, run a tool, write results back to context, repeat — and each of the 11 lessons adds one piece: tools, permissions, context management, Skills, MCP, sub-agents, planning, long-term memory. Every lesson is a complete runnable snapshot in lessons/lesson-01 through lesson-11, so you can diff adjacent lessons to see exactly what each concept costs in code. The final section is pure analysis: teardowns of Claude Code, Codex, Pi, Grok Bot, and others.

The interesting bit

The bundled web UI is the real hook: the left pane shows every model call, thought, and tool invocation; the right pane shows the complete context sent to the model each turn, color-coded by who wrote it and roughly how many tokens it costs. Watching the context balloon per loop does more for understanding agents than most blog posts. Notably, the web app imports the lesson-11 agent unmodified — it only swaps three interfaces (model client, handle_call, and the permission prompt) and uses nothing but the Python standard library.

Key highlights

• Only dependency is openai; no agent framework anywhere
• Vendor-neutral via OpenAI-compatible APIs, defaults to DeepSeek, switching models is two environment variables
• 49 tests in lesson 11 run against a fake model — no API key, no cost
• Permission system with risk tiers and human confirmation before file writes or command execution; long-term memory requires per-item confirmation
• Runs fully offline in demo mode with a scripted fake model

Caveats

• The docs are in Chinese; the code itself is readable regardless, but the articles are the main content
• Explicitly teaching code, not production: the permission system blocks mistakes and cheap escapes, not deliberate attacks — the README says so itself
• Part 3’s teardowns are a snapshot (dated October 2026 in the README) and may drift from the products

Verdict

If you’ve used Claude Code and want to know what’s actually happening in that context window, this is one of the most honest ways to find out. Skip it if you want a framework to build on — the author is clear that it isn’t one.