tinyloop

A small, readable agent loop for studying how model turns become tool calls, session events, and interface state.

npm install -g tinyloop

This minimal coding agent is heavily inspired by Pi.

Overview

A coding agent small enough to trace.

tinyloop is not trying to hide the machinery. It gives learners a concrete codebase where the model loop, tool calls, session events, and terminal UI are separate enough to inspect one piece at a time.

01Model turn
The model returns text or asks for a named function call.
02Local tool
tinyloop runs read_file, edit_file, write_file, or run_command.
03Session event
Tool progress, tool results, messages, and failures become ordered events.
04Transcript state
The TUI reduces events into state and renders from that state.

Learning map

Three ways into the same codebase.

Start with the architecture for the mechanics, read the principles for the design taste, or follow a walkthrough when you want one concrete path through the code.

Architecture

Model loop, tools, events, reducer.

Walk through a tinyloop turn from user input to model response, tool execution, session events, UI state, and terminal rendering.

Open architecture

Principles

Readable, eventful, honest.

tinyloop favors explicit contracts, swappable session drivers, visible state, and an honest boundary between learning project and production agent.

Open principles

Walkthroughs

Guided traces through one idea.

Follow one full turn or add one tiny tool while keeping the model, tool, event, and UI boundaries visible.

Open walkthroughs

The core boundary

The UI learns from events, not internals.

This is the main architectural lesson in the repo. The agent package emits a session event stream; the TUI package normalizes those events and reduces them into transcript state.