# fanrec/uina-agent architecture

> Architecture diagram of the GitHub repository fanrec/uina-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fanrec/uina-agent
- Repository: https://github.com/fanrec/uina-agent

## Overview

Uina is a local-terminal digital-agent runtime. A user starts an interactive or one-shot session; the host configures the model and capabilities, the agent builds requests and runs turns, and results and session facts are displayed and persisted for later recovery. Extensions add tools, hooks, and domain capabilities; the terminal UI exposes session, task, subagent, and trajectory controls. Relationships for unsampled extension and UI internals are limited to documented capabilities and references in the source index.

Main entry points: [`src/host/host.ts`](https://github.com/fanrec/uina-agent/blob/main/src/host/host.ts) (Runtime host), [`src/agent/loop.ts`](https://github.com/fanrec/uina-agent/blob/main/src/agent/loop.ts) (Agent loop), [`src/extensions/runner.ts`](https://github.com/fanrec/uina-agent/blob/main/src/extensions/runner.ts) (Extension runner), [`src/cli/app.ts`](https://github.com/fanrec/uina-agent/blob/main/src/cli/app.ts) (CLI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and host"]
  node_cli["CLI application<br/>[app.ts]"]
  node_host["Runtime host<br/>[host.ts]"]
  node_profile["Runtime profile<br/>[profile.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_agent["Agent loop<br/>[loop.ts]"]
  node_context["Context projection<br/>[context.ts]"]
  node_queue["Input queues<br/>[queue.ts]"]
  node_runtime["Runtime hooks<br/>[hooks.ts]"]
end

subgraph group_capabilities["Extensions and tools"]
  node_broker["Tool broker<br/>[broker.ts]"]
  node_pipeline["Tool pipeline<br/>[pipeline.ts]"]
  node_extensions["Extension runner<br/>[runner.ts]"]
  node_workspace["Workspace tools"]
  node_cognition["Cognition memory"]
  node_jobs["Jobs and subagents"]
end

subgraph group_state["Session and providers"]
  node_provider["Provider adapters<br/>[providers.ts]"]
  node_config["Provider config<br/>[config.ts]"]
  node_session[("Session journal<br/>[jsonl-store.ts]")]
  node_recovery["Session recovery<br/>[recovery.ts]"]
end

subgraph group_interface["Terminal interface"]
  node_tui["Terminal UI<br/>[tui.ts]"]
  node_uihost["UI host<br/>[ui-host.ts]"]
end

node_user(("User"))
node_actor(("Model provider"))

node_user -->|"starts"| node_cli
node_cli -->|"loads profile"| node_profile
node_cli -->|"creates host"| node_host
node_cli -->|"starts interface"| node_tui
node_host -->|"loads config"| node_config
node_host -->|"configures providers"| node_provider
node_host -->|"creates loop"| node_agent
node_host -->|"configures tools"| node_broker
node_host -->|"runs extensions"| node_extensions
node_host -.->|"opens journal"| node_session
node_agent -->|"builds context"| node_context
node_agent -->|"consumes input"| node_queue
node_agent -->|"invokes hooks"| node_runtime
node_agent -->|"dispatches tools"| node_broker
node_agent -.->|"records turns"| node_session
node_agent -.->|"sends requests"| node_provider
node_broker -->|"executes pipeline"| node_pipeline
node_pipeline -->|"runs tool hooks"| node_runtime
node_extensions -->|"registers tools"| node_broker
node_extensions -->|"registers hooks"| node_runtime
node_extensions -.->|"loads capabilities"| node_workspace
node_extensions -.->|"loads capabilities"| node_cognition
node_extensions -.->|"loads capabilities"| node_jobs
node_provider -.->|"streams completions"| node_actor
node_session -->|"rehydrates history"| node_recovery
node_recovery -.->|"restores state"| node_agent
node_tui -.->|"renders controls"| node_uihost
node_uihost -.->|"controls runtime"| node_host

click node_cli "https://github.com/fanrec/uina-agent/blob/main/src/cli/app.ts"
click node_host "https://github.com/fanrec/uina-agent/blob/main/src/host/host.ts"
click node_profile "https://github.com/fanrec/uina-agent/blob/main/src/host/profile.ts"
click node_agent "https://github.com/fanrec/uina-agent/blob/main/src/agent/loop.ts"
click node_context "https://github.com/fanrec/uina-agent/blob/main/src/agent/context.ts"
click node_queue "https://github.com/fanrec/uina-agent/blob/main/src/agent/queue.ts"
click node_runtime "https://github.com/fanrec/uina-agent/blob/main/src/runtime/hooks.ts"
click node_broker "https://github.com/fanrec/uina-agent/blob/main/src/tools/broker.ts"
click node_pipeline "https://github.com/fanrec/uina-agent/blob/main/src/tools/pipeline.ts"
click node_extensions "https://github.com/fanrec/uina-agent/blob/main/src/extensions/runner.ts"
click node_workspace "https://github.com/fanrec/uina-agent/tree/main/src/extensions/workspace-tools"
click node_cognition "https://github.com/fanrec/uina-agent/tree/main/src/extensions/cognition"
click node_jobs "https://github.com/fanrec/uina-agent/tree/main/src/extensions"
click node_provider "https://github.com/fanrec/uina-agent/blob/main/src/ai/providers.ts"
click node_config "https://github.com/fanrec/uina-agent/blob/main/src/ai/config.ts"
click node_session "https://github.com/fanrec/uina-agent/blob/main/src/session/jsonl-store.ts"
click node_recovery "https://github.com/fanrec/uina-agent/blob/main/src/session/recovery.ts"
click node_tui "https://github.com/fanrec/uina-agent/blob/main/src/ui/tui.ts"
click node_uihost "https://github.com/fanrec/uina-agent/blob/main/src/ui/ui-host.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_host,node_profile,node_user toneBlue
class node_agent,node_context,node_queue,node_runtime toneAmber
class node_broker,node_pipeline,node_extensions,node_workspace,node_cognition,node_jobs toneMint
class node_provider,node_config,node_session,node_recovery toneRose
class node_tui,node_uihost,node_actor toneIndigo
```

## Components

### Entry and host

- [CLI application](https://github.com/fanrec/uina-agent/blob/main/src/cli/app.ts): `src/cli/app.ts`
- [Runtime host](https://github.com/fanrec/uina-agent/blob/main/src/host/host.ts): `src/host/host.ts`
- [Runtime profile](https://github.com/fanrec/uina-agent/blob/main/src/host/profile.ts): `src/host/profile.ts`

### Agent runtime

- [Agent loop](https://github.com/fanrec/uina-agent/blob/main/src/agent/loop.ts): `src/agent/loop.ts`
- [Context projection](https://github.com/fanrec/uina-agent/blob/main/src/agent/context.ts): `src/agent/context.ts`
- [Input queues](https://github.com/fanrec/uina-agent/blob/main/src/agent/queue.ts): `src/agent/queue.ts`
- [Runtime hooks](https://github.com/fanrec/uina-agent/blob/main/src/runtime/hooks.ts): `src/runtime/hooks.ts`

### Extensions and tools

- [Tool broker](https://github.com/fanrec/uina-agent/blob/main/src/tools/broker.ts): `src/tools/broker.ts`
- [Tool pipeline](https://github.com/fanrec/uina-agent/blob/main/src/tools/pipeline.ts): `src/tools/pipeline.ts`
- [Extension runner](https://github.com/fanrec/uina-agent/blob/main/src/extensions/runner.ts): `src/extensions/runner.ts`
- [Workspace tools](https://github.com/fanrec/uina-agent/tree/main/src/extensions/workspace-tools): `src/extensions/workspace-tools`
- [Cognition memory](https://github.com/fanrec/uina-agent/tree/main/src/extensions/cognition): `src/extensions/cognition`
- [Jobs and subagents](https://github.com/fanrec/uina-agent/tree/main/src/extensions): `src/extensions`

### Session and providers

- [Provider adapters](https://github.com/fanrec/uina-agent/blob/main/src/ai/providers.ts): `src/ai/providers.ts`
- [Provider config](https://github.com/fanrec/uina-agent/blob/main/src/ai/config.ts): `src/ai/config.ts`
- [Session journal](https://github.com/fanrec/uina-agent/blob/main/src/session/jsonl-store.ts): `src/session/jsonl-store.ts`
- [Session recovery](https://github.com/fanrec/uina-agent/blob/main/src/session/recovery.ts): `src/session/recovery.ts`

### Terminal interface

- [Terminal UI](https://github.com/fanrec/uina-agent/blob/main/src/ui/tui.ts): `src/ui/tui.ts`
- [UI host](https://github.com/fanrec/uina-agent/blob/main/src/ui/ui-host.ts): `src/ui/ui-host.ts`

### Other components

- **User**
- **Model provider**

## Connections

- User → CLI application: starts
- CLI application → Runtime profile: loads profile (evidence: `src/cli/app.ts`)
- CLI application → Runtime host: creates host (evidence: `src/cli/app.ts`)
- CLI application → Terminal UI: starts interface (evidence: `src/cli/app.ts`)
- Runtime host → Provider config: loads config (evidence: `src/host/host.ts`)
- Runtime host → Provider adapters: configures providers (evidence: `src/host/host.ts`)
- Runtime host → Agent loop: creates loop (evidence: `src/host/host.ts`)
- Runtime host → Tool broker: configures tools (evidence: `src/host/host.ts`)
- Runtime host → Extension runner: runs extensions (evidence: `src/host/host.ts`)
- Runtime host → Session journal: opens journal (evidence: `src/host/host.ts`)
- Agent loop → Context projection: builds context (evidence: `src/agent/loop.ts`)
- Agent loop → Input queues: consumes input (evidence: `src/agent/loop.ts`)
- Agent loop → Runtime hooks: invokes hooks (evidence: `src/agent/loop.ts`)
- Agent loop → Tool broker: dispatches tools (evidence: `src/agent/loop.ts`)
- Agent loop → Session journal: records turns
- Agent loop → Provider adapters: sends requests
- Tool broker → Tool pipeline: executes pipeline (evidence: `src/tools/broker.ts`)
- Tool pipeline → Runtime hooks: runs tool hooks (evidence: `src/tools/pipeline.ts`)
- Extension runner → Tool broker: registers tools (evidence: `src/extensions/runner.ts`)
- Extension runner → Runtime hooks: registers hooks (evidence: `src/extensions/runner.ts`)
- Extension runner → Workspace tools: loads capabilities
- Extension runner → Cognition memory: loads capabilities (evidence: `src/extensions/cognition/context.ts`)
- Extension runner → Jobs and subagents: loads capabilities (evidence: `src/extensions/runner.ts`)
- Provider adapters → Model provider: streams completions
- Session journal → Session recovery: rehydrates history (evidence: `src/session/jsonl-store.ts`)
- Session recovery → Agent loop: restores state (evidence: `src/agent/loop.ts`)
- Terminal UI → UI host: renders controls
- UI host → Runtime host: controls runtime