Concepts

The agent loop#

A turn starts when a user message reaches the agent (oino-agent). The loop sends the conversation to the provider, streams the assistant message back, executes the tool calls it contains, appends the results, and loops until the assistant answers without tool calls or the run is aborted. Tools run sequentially or in parallel as each tool declares; the loop itself is provider-agnostic and gets its stream function injected by oino-core.

While a turn runs, new input is not lost. enter in the TUI steers the current run: the message is delivered after the current tool call finishes. A queued follow-up waits for the whole run to settle. Delivery is controlled by the steeringMode and followUpMode settings (all or one-at-a-time), and both queues are part of the command surface: steer and follow_up on RPC.

Every stage has extension hooks: before provider headers and requests, on each stream event, before and after each tool call, on agent start and settle. An event handler can rewrite a request, veto a tool call, or append session entries.

Sessions#

A session is a tree of entries, one JSON object per line (format v3): messages, tool calls, results, custom extension entries. Forking or navigating back creates a branch; every branch stays resumable. Files live under ~/.oino/sessions/, organised by working directory, one file per session.

Resume with oino -c (most recent in this directory), oino -r (picker), oino --session <path|id>, or --fork to branch off a copy. In the UI: /new, /resume, /tree, /fork, /clone, /name. Sessions written by other tools that speak format v3 open directly.

Tools#

The built-in tools are read, write, edit, bash, grep, find, ls (and powershell on Windows), with fixed schemas and output truncation. Extensions register additional tools through the same registry; the model sees one flat tool list. -t/--tools and -xt/--exclude-tools control which are active, -nt disables all, -nbt only the built-ins. A tool can declare a sequential execution mode, an output schema, and which other tools it may call (used for nested agent tools).

Settings#

Two layers, both JSON: ~/.oino/settings.json (global) and <project>/.oino/settings.json (project; wins, read only for trusted projects). Writes are atomic and locked. The TUI's /settings edits them, or you edit the files by hand. Keys cover model defaults, compaction, retry, transport, shell, image handling and TUI preferences; extensions add their own namespaces under extensionSettings.<namespace>. The settings reference lists every core key.

Resources#

Things the system prompt and the UI discover on disk:

• Context files: AGENTS.md (also CLAUDE.md and a few legacy spellings), read from the working directory upward; project-local ones require trust. SYSTEM.md replaces the system prompt, APPEND_SYSTEM.md adds to it.
• Skills: folders with a SKILL.md (front matter name, description) plus supporting files. Skills are listed in the system prompt; the model reads the ones it needs. enableSkillCommands also exposes them as /skill:<name>.
• Prompt templates: Markdown files under prompts/ that become slash commands; $1, $2, $@ splice arguments.

Discovery order (later wins) is bundled extension resources, global (~/.oino/...), shared (~/.agents/... for skills), then project. --skill, --prompt-template and --theme load explicit paths; -ns, -np, -nc switch categories off.

Compaction#

When the context window fills, older turns are replaced by a summary entry and the session continues in the same file (or on /compact [instructions] on demand). Auto-compaction is tuned by compaction.enabled, compaction.reserveTokens and compaction.keepRecentTokens. Branch summaries keep navigation cheap: moving to an abandoned branch can summarise it first.

Modes#

One binary, five frontends. Interactive when stdin and stdout are both TTYs; otherwise print.

Extensions see the mode (init context) and can behave differently per mode; UI dialogs degrade to approval requests or are skipped where the client cannot show them.