01
STREAMING TOOL LOOP
ProtoAgent streams model output, executes tools, appends results, retries transient failures, and keeps going until the model can answer directly.
what the agent is actually doing
★ READABLE AI CODING AGENT★ MULTI-STEP TOOL LOOPS★ MCP + SKILLS SUPPORT★ SESSION PERSISTENCE★ LEARNING BY BUILDING★ READABLE AI CODING AGENT★ MULTI-STEP TOOL LOOPS★ MCP + SKILLS SUPPORT★ SESSION PERSISTENCE★ LEARNING BY BUILDING
PROTOAGENT
█▀█ █▀█ █▀█ ▀█▀ █▀█ ▄▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀▀ █▀▄ █▄█ █ █▄█ █▀█ █▄█ ██▄ █ ▀█ █
A coding agent you can actually read
You've probably used coding agents that feel a bit magical. They read files, run commands, edit code, and somehow hold the whole loop together. ProtoAgent is a small TypeScript CLI built so you can actually see how that works.
It is small enough to understand in an afternoon, but real enough to use on an actual project.
// readable codebase
SMALL
// core loop
VISIBLE
// docs mode
LIVE
PROTOAGENT -- LIVE SESSIONNODE 12
PROTO> read this repo and explain how the agent loop works
Reading src/agentic-loop.ts...
USER> now add session resume support
[PLAN] Add session persistence in src/sessions.ts
[PLAN] Wire --session into src/cli.tsx
[EXEC] Updating App state and save/load flow...
[TEST] Re-running the flow from a fresh terminal...
[TEST] Running test suite...
[OK] sessions resume with TODO state intact
[OK] the exact resume command is printed on quit
[OK] docs updated to match the runtime
PROTO>
02
FILES, SHELL, AND WEB
It can read, write, and edit files, search a repo, run shell commands with approvals, fetch docs from the web, and keep a TODO list while it works.
the practical core
03
APPROVALS THAT MATTER
Writes, edits, and non-safe shell commands go through inline approvals, while a small set of dangerous shell patterns stays blocked outright.
local safety rails
04
SESSIONS THAT RESUME
Sessions are saved to disk with message history and TODOs, so you can quit, come back later, and keep working without starting from scratch.
persistent context
05
SKILLS AND MCP
Skills let you package project-specific instructions, and MCP lets you connect external tools without hardcoding them into the app.
easy extension points
06
SUB-AGENTS
Focused research can be pushed into child runs so the parent conversation stays lighter and easier to follow.
keeping the main thread clean