# iofficeai/aionrs architecture

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

- Interactive diagram: https://gitdiagram.com/iofficeai/aionrs
- Repository: https://github.com/iofficeai/aionrs

## Overview

aionrs is a Rust command-line LLM tool-use agent. A user submits a task through the CLI or interactive TUI; the CLI configures an agent engine, which streams model responses, dispatches approved tool calls, and returns output through the selected sink. The workflow includes model interaction, tool execution, and iterative results. README-described branches include MCP, skills, plan mode, sub-agents, persistent memory, session persistence, hooks, and context/output compression. Several subsystem links reflect documented architecture because their implementation was not sampled.

Main entry points: [`crates/aion-agent/src/engine.rs`](https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/engine.rs) (Agent engine), [`crates/aion-agent/src/orchestration.rs`](https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/orchestration.rs) (Tool orchestration), [`crates/aion-cli/src/run.rs`](https://github.com/iofficeai/aionrs/blob/main/crates/aion-cli/src/run.rs) (CLI run flow), [`crates/aion-cli/src/main.rs`](https://github.com/iofficeai/aionrs/blob/main/crates/aion-cli/src/main.rs) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI entry<br/>[main.rs]"]
  node_run["CLI run flow<br/>[run.rs]"]
  node_tui["Interactive TUI<br/>[app.rs]"]
  node_json["JSON stream<br/>[session.rs]"]
end

subgraph group_agent["Agent runtime"]
  node_engine["Agent engine<br/>[engine.rs]"]
  node_orchestration["Tool orchestration<br/>[orchestration.rs]"]
  node_hooks["Tool lifecycle hooks<br/>[hooks.rs]"]
  node_sink["Output sinks<br/>[sink.rs]"]
end

subgraph group_integrations["Models and tools"]
  node_provider["Provider adapters<br/>[provider.rs]"]
  node_tools["Local tool suite<br/>[lib.rs]"]
  node_process["Process runner<br/>[runner.rs]"]
  node_mcp["MCP client<br/>[manager.rs]"]
end

subgraph group_context["Context features"]
  node_skills["Skills system<br/>[lib.rs]"]
  node_plan["Plan mode<br/>[mod.rs]"]
  node_memory[("Persistent memory<br/>[store.rs]")]
  node_compact["Context compression<br/>[mod.rs]"]
end

subgraph group_state["Persistence and config"]
  node_config["Configuration<br/>[config.rs]"]
  node_session[("Session persistence<br/>[session.rs]")]
end

node_user(("User or host"))
node_llm{{"LLM services"}}
node_mcpservers{{"MCP servers"}}

node_user -->|"submits task"| node_cli
node_user -->|"interacts"| node_tui
node_user -->|"sends commands"| node_json
node_cli -->|"dispatches run"| node_run
node_run -->|"loads settings"| node_config
node_run -->|"builds runtime"| node_engine
node_tui -->|"runs turns"| node_engine
node_json -->|"runs messages"| node_engine
node_engine -->|"streams requests"| node_provider
node_provider -->|"calls model"| node_llm
node_engine -->|"dispatches calls"| node_orchestration
node_orchestration -->|"executes tools"| node_tools
node_tools -.->|"runs commands"| node_process
node_orchestration -.->|"executes remote tools"| node_mcp
node_mcp -.->|"sends MCP requests"| node_mcpservers
node_engine -->|"loads skill context"| node_skills
node_orchestration -->|"applies plan tools"| node_plan
node_engine -->|"uses project memory"| node_memory
node_engine -->|"compresses context"| node_compact
node_engine -->|"saves or resumes"| node_session
node_orchestration -->|"runs lifecycle hooks"| node_hooks
node_engine -->|"emits agent output"| node_sink
node_sink -->|"presents results"| node_user

click node_cli "https://github.com/iofficeai/aionrs/blob/main/crates/aion-cli/src/main.rs"
click node_run "https://github.com/iofficeai/aionrs/blob/main/crates/aion-cli/src/run.rs"
click node_tui "https://github.com/iofficeai/aionrs/blob/main/crates/aion-tui/src/app.rs"
click node_json "https://github.com/iofficeai/aionrs/blob/main/crates/aion-cli/src/json_stream/session.rs"
click node_config "https://github.com/iofficeai/aionrs/blob/main/crates/aion-config/src/config.rs"
click node_engine "https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/engine.rs"
click node_orchestration "https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/orchestration.rs"
click node_provider "https://github.com/iofficeai/aionrs/blob/main/crates/aion-providers/src/provider.rs"
click node_tools "https://github.com/iofficeai/aionrs/blob/main/crates/aion-tools/src/lib.rs"
click node_process "https://github.com/iofficeai/aionrs/blob/main/crates/aion-process/src/runner.rs"
click node_mcp "https://github.com/iofficeai/aionrs/blob/main/crates/aion-mcp/src/manager.rs"
click node_skills "https://github.com/iofficeai/aionrs/blob/main/crates/aion-skills/src/lib.rs"
click node_plan "https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/plan/mod.rs"
click node_memory "https://github.com/iofficeai/aionrs/blob/main/crates/aion-memory/src/store.rs"
click node_compact "https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/compact/mod.rs"
click node_session "https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/session.rs"
click node_hooks "https://github.com/iofficeai/aionrs/blob/main/crates/aion-config/src/hooks.rs"
click node_sink "https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/output/sink.rs"

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_run,node_tui,node_json,node_user toneBlue
class node_engine,node_orchestration,node_hooks,node_sink toneAmber
class node_provider,node_tools,node_process,node_mcp,node_mcpservers toneMint
class node_skills,node_plan,node_memory,node_compact toneRose
class node_config,node_session,node_llm toneIndigo
```

## Components

### User interfaces

- [CLI entry](https://github.com/iofficeai/aionrs/blob/main/crates/aion-cli/src/main.rs): `crates/aion-cli/src/main.rs`
- [CLI run flow](https://github.com/iofficeai/aionrs/blob/main/crates/aion-cli/src/run.rs): `crates/aion-cli/src/run.rs`
- [Interactive TUI](https://github.com/iofficeai/aionrs/blob/main/crates/aion-tui/src/app.rs): `crates/aion-tui/src/app.rs`
- [JSON stream](https://github.com/iofficeai/aionrs/blob/main/crates/aion-cli/src/json_stream/session.rs): `crates/aion-cli/src/json_stream/session.rs`

### Agent runtime

- [Agent engine](https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/engine.rs): `crates/aion-agent/src/engine.rs`
- [Tool orchestration](https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/orchestration.rs): `crates/aion-agent/src/orchestration.rs`
- [Tool lifecycle hooks](https://github.com/iofficeai/aionrs/blob/main/crates/aion-config/src/hooks.rs): `crates/aion-config/src/hooks.rs`
- [Output sinks](https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/output/sink.rs): `crates/aion-agent/src/output/sink.rs`

### Models and tools

- [Provider adapters](https://github.com/iofficeai/aionrs/blob/main/crates/aion-providers/src/provider.rs): `crates/aion-providers/src/provider.rs`
- [Local tool suite](https://github.com/iofficeai/aionrs/blob/main/crates/aion-tools/src/lib.rs): `crates/aion-tools/src/lib.rs`
- [Process runner](https://github.com/iofficeai/aionrs/blob/main/crates/aion-process/src/runner.rs): `crates/aion-process/src/runner.rs`
- [MCP client](https://github.com/iofficeai/aionrs/blob/main/crates/aion-mcp/src/manager.rs): `crates/aion-mcp/src/manager.rs`

### Context features

- [Skills system](https://github.com/iofficeai/aionrs/blob/main/crates/aion-skills/src/lib.rs): `crates/aion-skills/src/lib.rs`
- [Plan mode](https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/plan/mod.rs): `crates/aion-agent/src/plan/mod.rs`
- [Persistent memory](https://github.com/iofficeai/aionrs/blob/main/crates/aion-memory/src/store.rs): `crates/aion-memory/src/store.rs`
- [Context compression](https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/compact/mod.rs): `crates/aion-agent/src/compact/mod.rs`

### Persistence and config

- [Configuration](https://github.com/iofficeai/aionrs/blob/main/crates/aion-config/src/config.rs): `crates/aion-config/src/config.rs`
- [Session persistence](https://github.com/iofficeai/aionrs/blob/main/crates/aion-agent/src/session.rs): `crates/aion-agent/src/session.rs`

### Other components

- **User or host**
- **LLM services**
- **MCP servers**

## Connections

- User or host → CLI entry: submits task
- User or host → Interactive TUI: interacts
- User or host → JSON stream: sends commands
- CLI entry → CLI run flow: dispatches run
- CLI run flow → Configuration: loads settings
- CLI run flow → Agent engine: builds runtime
- Interactive TUI → Agent engine: runs turns
- JSON stream → Agent engine: runs messages
- Agent engine → Provider adapters: streams requests
- Provider adapters → LLM services: calls model
- Agent engine → Tool orchestration: dispatches calls
- Tool orchestration → Local tool suite: executes tools
- Local tool suite → Process runner: runs commands
- Tool orchestration → MCP client: executes remote tools
- MCP client → MCP servers: sends MCP requests
- Agent engine → Skills system: loads skill context
- Tool orchestration → Plan mode: applies plan tools
- Agent engine → Persistent memory: uses project memory
- Agent engine → Context compression: compresses context
- Agent engine → Session persistence: saves or resumes
- Tool orchestration → Tool lifecycle hooks: runs lifecycle hooks
- Agent engine → Output sinks: emits agent output
- Output sinks → User or host: presents results