Follow one prompt through the oven.

Trace a turn

The user is in plan mode and asks for a small feature. Step through the turn and watch which crate is working, what reaches the screen and which events go out on the bus. Use the arrow keys once the player has focus.

The agent loop

Agent::run is one loop policy over Agent::step. A step is one provider round trip plus the tools it asked for; the loop keeps stepping until a reply asks for no tools. Click a stage, or animate two laps.

Tool calls

Every tool declares what it may do — read, write, execute or reach outside — and the mode decides what that means. The model only sees tools it is allowed to call. Switch modes to compare.

One reply, five calls

Calls from one reply run at the same time. Approvals are asked one by one in the model's order, tools that rewrite a file or talk to the user take turns, and results enter the history in the order the model asked — which is what a provider expects back.

Plan mode & the checklist

There is no separate todo mode: the checklist lives on plan mode. Shift+Tab switches live; the next step picks it up. Each todo_write replaces the whole list. Walk through one plan.

• Whole list, every time. At most 40 items and only one in_progress; an invalid list is rejected and the old one stays.
• Survives mode switches. Leaving plan mode drops the plan prompt and todo_write, but a non-empty list stays in the prompt.
• Persisted. The list is saved as a TodoList record in the session file, so a resumed session shows it again.

Subagents

The task tool hands a self-contained job to another Agent with its own history, on the same router and the same tool instances. Only its final report comes back as the tool result.

• Never waits on you. A subagent's turn has no request sink, so it can't ask for approval or a question; its role decides what it may do.
• Stops with its parent. One cancel token per subagent, linked to app shutdown, to the turn that spawned it and to /agents stop.
• Lives for the app run. Only the task call and its report are saved. By default 4 run at once and the rest queue as pending.

Memory

History, compaction and todos die with the session. Memory is what outlives it: one markdown file per memory, a one-line description of each in the system prompt, and the body read on demand.

---
kind: fact
description: Integration tests need OVEN_TEST_PROXY=1 or they hang on DNS.
source: 01J8Z…
---
Run `OVEN_TEST_PROXY=1 cargo test -p tiny-cli`. Without it the
resolver blocks for 30s per test. Seen in CI and locally.

Would oven remember this?

Ending a turn

A turn ends with exactly one of Completed, Cancelled or Failed. The runtime then saves, publishes the new state and may compact before it goes back to idle. Click a phase.

1. Save

   New history records are appended to the session JSONL under ~/.oven/sessions/, plus a checklist snapshot when it changed.

2. Publish

   The runtime writes the new AppState to a watch channel: events say something happened, state says what is true.

3. Compact?

   Past 80% of the model's context window, the history is summarized into one message in a fresh session file. Todos survive.

4. Idle

   Inputs queued during the turn now run in order. Esc Esc undoes the last exchange — your message, the reply and the tools it ran. Mid-turn the same two keys cancel instead, and a queued prompt goes back to the composer first.

Read the design notes

• 🧭

  Architecture

  Commands, events, state; the phase and turn machines; every invariant.

• 🧁

  Subagents

  The supervisor, roles, cancellation and the seams left for loop and graph engineering.

• 🧠

  Memory

  Why files and not RAG, the trust model and every failure mode.

• 🧱

  App layer

  The runtime actor, sessions, slash commands and MCP.

• 🖥️

  TUI

  The event loop, transcript, widgets and the Esc ladder.

• 📚

  All docs

  Every design note in the repository.